RESTのコール

コールのRESTアクションは、サービス定義とともにRESTコールを行うために使用されます。

内部的には、このアクションはパブリック・ユーティリティである「RESTヘルパー」を使用します。パラメータは次のとおりです。

パラメータ名	説明
endpoint	サービス構成で定義されているエンドポイントID。
uriParams	サービス・エンドポイントで定義されたパスと問合せのパラメータを無効にするために使用されるキー/バリュー・ペア・マップ。
body	本文として送信される構造化オブジェクト。
requestType	リクエストのコンテンツ・タイプ( 'json'、'form'、または'url')。ノート: これは推奨されていません。かわりに、'contentType'と'fileContentType'を使用します。
headers	オブジェクト。各プロパティ名は、リクエストと共に送信されるヘッダー名と値です。
contentType	実際のMIMEタイプを持つオプションの文字列値。これは"content-type"ヘッダーに使用されます。 "fileContentType"で使用する場合、これはファイルblobのタイプとしても使用されます。
responseType	設定されている場合、指定されたタイプを使用して実行時に次の2つの処理が実行されます: フェッチされる属性を制限するREST URIのフィールド・パラメータを生成フェッチされたレスポンスをレスポンス・タイプに自動的にマップします(組込みvb/BusinessObjectsTransformで使用する場合)。これは、標準のアクション・チェーンに適用されます。割り当てられたタイプがそのコンテキストでどのように使用されるかの詳細は、「サービス・データ・プロバイダのプロパティ」の「responseType」の定義を参照してください。
filePath	リクエストとともに送信するファイルへのオプションのパス。「contentType」が設定されている場合は、Fileコンテンツのタイプとして使用されます。 "contentType"が設定されていない場合、一般的なファイル拡張子の検索が使用されます。
filePartName	オプションで、filePathとともに使用して、FormData部品のデフォルト名("file")を上書きできるようにします。
fileContentType	オプションの文字列。「contentType」、「multipart/form-data」、および「filePath」と組み合わせて使用します。
hookHandler	主にデータ・フェッチを外部化するときにvb/ServiceDataProviderによって使用されます。詳細は「サービス・データ・プロバイダ」を参照してください。
requestTransformOptions	"options"パラメータとして、対応する変換に渡す値のマップ。
requestTransformFunctions	リクエストを行う前に呼び出された名前付き変換関数のマップ。関数は次のとおりです:fn(configuration, options)
responseTransformFunctions	レスポンスを作成する前に呼び出された名前付き変換関数のマップ。関数は次のとおりです:fn(configuration, options)
responseBodyFormat	標準Rest動作をオーバーライドできる文字列。通常は"content-type"ヘッダーを検索してレスポンスの読取り方法と解析方法を判断します。使用可能な値は、text、json、blob、arrayBuffer、base64、base64UrlおよびformDataです。
responseFields	これは、特にJET動的フォームで使用するための拡張フィールドです。この値は通常、`<oj-dynamic-form>`のrendered-fields属性にバインドされた変数です。これは、計算済レイアウトがどのフィールドをフェッチするかをRest Actionコールに通知する方法です。ノート: この値から問合せを作成するには、vb/BusinessObjectsTransform変換が必要です。ノート: 「responseFields」が指定されている場合、「responseType」は無視されます。

マルチパート/フォーム・データの使用

"contentType"を"multipart/form-data"に設定すると、コールRESTアクションによって、リクエスト"body"オブジェクトがフォーム部分として解釈されます。本文オブジェクトの各プロパティはフォーム部分であり、独自のコンテンツ・タイプおよびディス・ポジションを持つキーと値のペアです。

"filePath"も設定されている場合は、一般的なファイル拡張子タイプのルックアップを使用して、追加の部分として追加されます。

"filePath"も設定されている場合、サンプルの単純なファイル拡張子タイプの関連付けを使用して、追加パートとして追加されます。この部分の名前は"file"であるか、"filePartName"を使用して指定できます。

ファイル・パートでfileContentTypeを使用してファイル・タイプをオーバーライドすることもできます。

multipart/form-data形式の操作の詳細は、このOracleブログ「VBでのREST APIの使用 - multipart/form-data」を参照してください。

エンドポイント・タイプごとに通常必要なパラメータ

これらは、各エンドポイント・タイプに通常必要なパラメータです:

POST:
- bodyパラメータは、新しいレコードのデータを含む変数に設定されます。
- uriParamsパラメータを使用して、必要な入力パラメータを指定します。
POSTエンドポイント・コールの例を次に示します:
```
      const callRestCreateIncident = await Actions.callRest(context, {
        endpoint: 'fixitfast/putIncident',
        body: $variables.incidentPayload ,
        uriParams: {
          id: $constants.incidentId,
        },
      });
```
GET:
- uriParamsパラメータは、単一のレコードを取得するためのID入力パラメータなど、必要な入力パラメータを指定するために使用されます。
  単一のレコードを取得するためのGETエンドポイント・コールの例を次に示します。 empIDToGet_ip変数は、このコールRESTコールを含むアクション・チェーンにレコードのIDを渡す入力パラメータです:
```
      const getEmployeeResult = await Actions.callRest(context, {
        endpoint: 'businessObjects/get_Employee',
        uriParams: {
          'Employee_Id': empIDToGet_ip,
        },
      });
```
DELETE:
- uriParamsパラメータは、削除するレコードのIDを指定するために使用されます。
  レコードを削除するDELETEエンドポイント・コールの例を次に示します。 empIDToDelete_ip変数は、このコールRESTコールを含むアクション・チェーンにレコードのIDを渡す入力パラメータです:
```
      const callRestBusinessObjectsDeleteEmployeeResult = await Actions.callRest(context, {
        endpoint: 'businessObjects/delete_Employee',
        uriParams: {
          'Employee_Id': empIDToDelete_ip,
        },
      });
```
PATCH:
- bodyパラメータは、更新されたデータを含むレコードを含む変数に設定されます。
- uriParamsパラメータは、更新するレコードのIDを指定するために使用されます。
PATCHエンドポイント・コールの例を次に示します:
```
      const updateEmployeeResult = await Actions.callRest(context, {
        endpoint: 'businessObjects/update_Employee',
        uriParams: {
          'Employee_Id': $variables.empID_pv,
        },
        body: $variables.EmpUpdatedData_pv,
      });
```

サービス定義

サービス接続の詳細が静的な場合、リクエストおよびレスポンスのサーバー、パス、スキーマなどの詳細が、サービス接続のopenapi3.jsonファイルに格納されます。

サービスの定義を表示または編集するには、「サービス」ペインでサービス接続を選択し、「ソース」タブを開きます。エディタでは、OpenAPI3仕様およびJSON形式が使用されます。
「
図jsac-service-connection-source-tab.jpgの説明」

変換

requestTransformOptions。 requestTransformFunctionsおよびresponseTransformFunctionsを使用して、リクエストとレスポンスを変更できます。一部の組込みサービス・エンドポイントには、'sort'、'filter'、'paginate'および'select'の組込み変換関数があり、これらの変換関数のオプションをrequestTransformOptionsプロパティを使用して同じ名前で定義できるように、これらの組込みサービス・エンドポイントがあります。サード・パーティ・サービスの場合、オプション・セットは、サポートされている変換関数のタイプに基づきます。

Restアクションを使用すると、変換名にセマンティックな意味がなく、すべてのリクエストおよびレスポンス変換がコールされます。

リクエストおよびレスポンス変換関数には、次のシグネチャがあります。

変換タイプパラメータ戻り値

変換タイプ	パラメータ	戻り値
リクエスト	`/** * configuration: { * url: * initConfig: { * method: // string with http method * body: // request body, if any * credentials: // string see (fetch) Request * headers: // object, map of strings * } * }, * * options: provided by the application * * context: an empty object, which exists for the * lifetime of one REST call, a set of * transforms share this. **/ mytransform(configuration, options, context)`	構成オブジェクト。パラメータを参照してください。通常は、渡されるオブジェクトと同じオブジェクトまたは変更されたオブジェクトを戻します。
レスポンス	`/** * response: { body, headers } * * context: an empty object, see "Request transforms" * */ myresponsetransform(response, context);`	この戻り値は、アプリケーションによって定義されます。この値はRESTコールの結果の'transformResults'として戻されます: `/** * { * response: The (fetch) Response object. Note that the body has already * been read, so the functions (ex. json()) cannot be called. * * body: the result of the json()/text()/etc. * * transformResults: a map of return values from Response Transforms * } */`

リクエスト

/**
 * configuration: {
 *  url:
 *   initConfig: {
 *     method: // string with http method
 *     body: // request body, if any
 *     credentials: // string see (fetch) Request
 *     headers: // object, map of strings
 *   }
 * },
 *
 * options: provided by the application
 *
 * context: an empty object, which exists for the
 *   lifetime of one REST call, a set of 
 *   transforms share this.
 **/
 
mytransform(configuration, options, context)

構成オブジェクト。パラメータを参照してください。

通常は、渡されるオブジェクトと同じオブジェクトまたは変更されたオブジェクトを戻します。

レスポンス

/**
 * response: { body, headers }
 *
 * context: an empty object, see "Request transforms"
 *
 */
myresponsetransform(response, context);

この戻り値は、アプリケーションによって定義されます。この値はRESTコールの結果の'transformResults'として戻されます:

/**
 * {
 *  response: The (fetch) Response object. Note that the body has already
 *     been read, so the functions (ex. json()) cannot be called.
 *
 *  body: the result of the json()/text()/etc.
 * 
 *  transformResults: a map of return values from Response Transforms
 * }
 */

例1-28 単純な変換機能

サード・パーティ・サービスと対話する場合、またはビジネス・オブジェクトの自動生成された変換(vb/BusinessObjectTransforms)をオーバーライドする必要がある場合は、リクエストおよびレスポンスの変換関数をコールRESTアクションに割り当てます。それ以外の場合は、変換関数をバックエンド、サービス接続またはエンドポイントに割り当てる必要があります。

この例では、変換関数はページ・モジュールで定義され、コールRESTアクションに割り当てられています。引数はモジュール関数に自動的に渡されます。
「
図jsac-callrest-transforms.pngの説明」

ページ・モジュールで定義された変換ファンクションは、ページのJavaScriptタブにあります:

class PageModule {
    transformCityNames(result) {
        let tr = {};
        if (result.body) {
            tr = result.body.items;
            for (let i = 0; i < tr.length; i++) {
              tr[i].cityName = tr[i].cityName + " (city)";
            }
        }
    }

    sort2(configuration, options) {
      configuration.url = configuration.url + options; 
      return configuration; 
    }
}

エラー処理と戻り値

基礎となるREST APIリクエストがステータス・コードを返す場合、エラーを自分で処理するためのエラー・オブジェクトが返されます。それ以外の場合は、自動生成されたエラー通知が表示されます。

REST呼出しアクションによって返されるオブジェクトは、次の結果を返します:

結果戻りオブジェクトの関連プロパティ返されたオブジェクト

結果	戻りオブジェクトの関連プロパティ	返されたオブジェクト
成功	返されたオブジェクトの`ok`プロパティがtrueに設定され、成功を示す場合、オブジェクトの関連プロパティは次のようになります: body: 呼び出しの結果を含むオブジェクト(スカラー、オブジェクト、配列など) headers: ヘッダーオブジェクト ok: boolean、trueに設定 status: number, 200に設定 statusText: string、'OK'に設定	`{ body {}, error: null, headers: Headers {}, message: {summary: â â}, ok: true, status: 200 statusText: "OK", }` *1つのレコードが返された場合、そのレコードは`body{}`オブジェクトに含まれます。複数のレコードが返された場合、レコードは`body{}`オブジェクトの`results`パラメータに含まれます。
エラー	返されたオブジェクトの`ok`プロパティがfalseに設定され、失敗を示す場合、オブジェクトの関連プロパティは次のとおりです: error: エラー・オブジェクトまたはnull message: エラー・サマリーのあるオブジェクト ok: boolean、falseに設定 status: number statusText: エラーのタイプを示す文字列	`{ body: null, error: null, headers: Headers {}, message: {summary: â<error summary>â}, ok: false, status: <status number>, statusText: â<error type>â }`

成功

返されたオブジェクトのokプロパティがtrueに設定され、成功を示す場合、オブジェクトの関連プロパティは次のようになります:

body: 呼び出しの結果を含むオブジェクト(スカラー、オブジェクト、配列など)
headers: ヘッダーオブジェクト
ok: boolean、trueに設定
status: number, 200に設定
statusText: string、'OK'に設定

{
  body {},
  error: null,
  headers: Headers {},
  message: {summary: â â},  
  ok: true,
  status: 200
  statusText: "OK",
}

*1つのレコードが返された場合、そのレコードはbody{}オブジェクトに含まれます。複数のレコードが返された場合、レコードはbody{}オブジェクトのresultsパラメータに含まれます。

エラー

返されたオブジェクトのokプロパティがfalseに設定され、失敗を示す場合、オブジェクトの関連プロパティは次のとおりです:

error: エラー・オブジェクトまたはnull
message: エラー・サマリーのあるオブジェクト
ok: boolean、falseに設定
status: number
statusText: エラーのタイプを示す文字列

{
  body: null,
  error: null,
  headers: Headers {},
  message: {summary: â<error summary>â},  
  ok: false,
  status: <status number>,
  statusText: â<error type>â
}

ビジネス・オブジェクトの操作の詳細は、「REST APIを使用したビジネス・オブジェクトへのアクセス」を参照してください。