REST API データ接続 - Automate_Evolve - Automate_Studio_Manager - 20.3

ステップ 1: グローバル スコープまたはアプリ スコープで REST API 接続を作成します

1. グローバル レベルまたはアプリ レベルで [接続 → データ ソース] に移動します。

2. 新しい REST API 接続を定義します。

3. API のベース URL と 認証の詳細を入力します。詳細については、「データベース接続の作成」を参照してください。

ステップ 2: ソリューション データ接続を作成する

以下の手順に従い、必要な操作 (作成、読み取り、更新、または削除) と API システムの必要なデータに応じて、データ接続を構成します。

1. 新規のフォーム ソリューション を作成するか、既存のフォーム ソリューションを開き、[ソリューション] リボン メニューから [データ接続の追加] をクリックします。

2. 名前を入力し、タイプ [REST API ] を選択します。これにより、現在のアプリ スコープまたはグローバル スコープのいずれかに存在する「REST API 」タイプのすべてのデータ ソースが表示されます。

3. API URL または REST API エンドポイントを設定します。

   1. デフォルトでは、データ接続の作成時に定義されたベース API URL が表示されます。特定のエンドポイントからデータを取得するには、要件に従ってこの URL を構成します。

   2. 3 つのドットをクリックして URL ビルダーを開き、URL 部分を追加します。

   3. [URL ビルダー] ダイアログで、必要に応じてこのソリューション データ接続の URL を追加します。固定値またはフォーム フィールド値、あるいはその両方である可能性があります。以下は、SAP HANA API から特定の製品の詳細を取得する例です。

      1. 接続で定義されたベース URL: https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap

      2. 製品 API へのアクセスを指定する最初のURL 部分: /API_PRODUCT_SRV/A_Product/

      3. フォーム フィールドから製品番号を指定する 2 番目の URL 部分: ('[/my:myFields/my:Search_Product_Id]') 注: この値は、SAP HANA API 仕様 (「<<Product Number>>」など) に準拠します。

      4. 最終的な URL は次のようになります。

         https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_PRODUCT_SRV/A_Product/('[/my:myFields/my:Search_Product_Id]')

   API-URL がコントロール (ルックアップ/クエリ/ドロップダウン) で定義されていない場合、データ接続ライブラリで定義された API URL への代用ラベルが機能します。

   データ接続ライブラリで API URL を変更すると、ランタイム ソリューションにも反映されます。

   データ接続ライブラリから追加されたデータ接続は、ソリューション データ接続レベルからは編集できません。ユーザーは、 ルックアップ/クエリ/ドロップダウン コントロールのフィルター プロパティ (Raw where 句) からのみ API URL を編集できます。

   以下の優先順位に従います。

   • データ接続ライブラリ接続の場合

     • クエリ/ルックアップ コントロールで定義された API URL が最初に尊重されます。

     • クエリ/Lookup で API URL が定義されていない場合、データ接続ライブラリ レベルで定義された API URL を代用ラベルとします。

   • ソリューション接続の場合

     • クエリ/ルックアップ コントロールで定義された API URL が最初に尊重されます。

     • クエリ/Lookup で API URL が定義されていない場合、ソリューション接続レベルで定義された API URL を代用ラベルとします。

4. HTTP 操作: REST API は、HTTP 動詞を使用して、リクエストが読み取り、更新、削除、または作成であることを指定します。現在の API 接続の使用に従ってこのフィールドを選択します。サポートされる操作は次のとおりです。

   1. GET: API からデータを取得します。

   2. Put / Patch: データを更新します。

   3. Post: データを作成します。

   4. Delete: データを削除します。

      注:

      南

      • 一部のシステムは標準の HTTP 動詞に準拠しない場合があるため、システムの API 仕様に従って上記の操作を選択します。Post 操作はデータの削除を行っている可能性があります。

      • データ接続アダプター プラグイン - ランナー ノードは、REST API データ接続でサポートされています。

5. API スキーマを設定します。

   1. 入力スキーマ: 入力スキーマは、API に送信されるデータ用です (つまり、JSON のリクエスト ペイロードです)。ファイルから JSON スキーマを入力するか、テキスト フィールドに直接コピーします。

   2. 出力スキーマ: 出力スキーマは、API から受信するデータ用です (つまり、JSON のレスポンス ペイロードです)。ファイルから JSON スキーマを入力するか、テキスト フィールドに直接コピーします。

      詳細については、REST API 接続の入力/出力スキーマを更新する手順を参照してください。

   3. エラースキーマ: エラーまたは例外が発生した場合、一部の API は異なる JSON スキーマでデータを返します。つまり、HTTP ステータスコード (4xxx または 5xxx) はエラー/ API 呼び出しの例外と見なされます。ファイルから JSON スキーマを入力するか、テキスト フィールドに直接コピーします。

   4. リクエスト ヘッダー: これは、キーと値のペア形式のヘッダー データです。リクエスト ヘッダーは、リクエスト ヘッダー セクションで API に送信されるデータです。API 仕様に従って、予想されるリクエスト ヘッダーを指定します。また、キーと値の両方を、フォーム フィールドか固定値、または両方から読み取るように構成できます。

      例: リクエスト ヘッダー承認が値 – ベアラー [FormFieldName] 付きで設定されている場合、FormFieldName の値が 1234 の場合の実行時に、リクエスト ヘッダー認証値はベアラー 1234 になります。

      ここでのベアラーは固定値で、FormFieldName はフォーム フィールドです。

   5. レスポンス ヘッダー: これは、キーと値のペア形式のヘッダーです。レスポンス ヘッダーは、ヘッダー セクションのレスポンスとして API から受信されるデータです。API 仕様に従って、予想されるリクエスト ヘッダーを指定します。キー名は、ソリューションの設計時に入力された固定値または静的な値です。この値はフォーム フィールドになり、このフォーム フィールドは、API から受信したデータに従って値で更新されます。レスポンス ヘッダーは、Web サービスの実行 (Web サービス制御またはデータ接続アダプター) でのみ機能します。

      リクエスト ヘッダーに関する注意

      以下は、フォーム フィールドを介したヘッダーのサポートの詳細です。

      1. 非同期データ接続: [フォームを開いたときにデータを自動的に取得する] はチェックされていません。これはサポートされていません。

      2. 同期データ接続: [フォームを開いたときにデータを自動的に取得する] はチェックされています。これは、繰り返しなしのフィールドでのみサポートされます。

      注:

      • REST API データ接続 (Sync/Async) フィルタが定義されたドロップダウンで使用され、ユーザーがデータ接続を変更すると、警告メッセージが表示されます。選択に基づいて、データ接続モードが変更され、フィルターがクリアされます。Rest API データ接続が消費される場所について、それぞれのフィルター ダイアログ (同期フィルターまたは REST API URL フィルター) が開きます。

      • ドロップダウンで使用されるフィルターなしの REST API データ接続が定義されている場合、警告メッセージが表示されます。

      JSON ペイロードフィールドのデータ型:

      入力 / 出力 / エラー スキーマに指定された JSON スキーマが値のデータ型名を指定している場合、アプリケーションは JSON フィールドのデータ型を判別できます。フィールド CityName を文字列型として指定するには { “CityName”:”string”} とします。または、フィールド CreatedOn を日付型として指定するには {“CreatedOn”:”date”} とします。以下は、参照用のフィールド タイプ マッピング テーブルです。

      データ型	フィールド タイプ
      int、bigint	番号フィールドの場合。
      文字列	文字列またはテキスト フィールドの場合。
      decimal	10 進数フィールドの場合。
      bit、bool、true	Boolean フィールドの場合。
      date、datetime	日付フィールドの場合。

      データ型が指定されていない場合、アプリケーションは指定された値に基づいてデータ型を予測しようとします。Number 値から int (つまり、0 または 12 など)、Decimal 値から double (つまり、12.4 または 9.1 も 0.0 は int と見なされます)、Date 値から日付。より明確な結果を得るには、データ型を指定することをお勧めします。

      配列のサポート

      配列型のプロパティもサポートされています。以下は、配列プロパティとそのデータ型表記の例です。配列型プロパティの場合、フォーム スキーマは単一列テーブルとして生成されます (つまり、単一フォームのフィールドを含む繰り返しセクション)

      [{ "id": "int", "name": "string", "productType": "string", "sizes": ["string"], "otherDetails": { "colors": ["string"], "versions": ["int"] }}]

      フィールド生成での日付型の不一致

      ペイロードで指定された API フィールドがフォーム フィールド タイプと一致しない場合 (主に日付と数値のユースケース)、つまり、API フィールド タイプは文字列ですが、日付タイプのフォーム フィールドまたはその逆にマップされるような場合、データのやりとりが正しくない可能性があります。アプリケーションは API サーバーから受信したデータを文字列と見なし、フォームはそれを日付のように扱うため、データの不一致や不明なエラーが発生する可能性があります。

      送信された JSON ペイロードは大文字と小文字を区別して処理され、提供されたすべてのキー名は指定されたものと同じ大文字と小文字で処理されます。すなわち “id”:”int” アプリケーションは、大文字と小文字が「id」の正確な名前のキーを探し、「Id」や「ID」などのデータを受信した場合は処理できません。

   6. 接続を保存すると、ソリューションの データ接続に表示されます。

データ接続の編集 (REST API):

データ接続が使用中の場合、次のプロパティのみが編集可能になります。

• URL

• 要求/応答ヘッダー

ステップ 3: フォーム フィールドを使用した API ソリューション データ接続のマッピング

この手順は、API ソリューションのデータ接続のデータ フィールドをフォーム フィールドにマッピングするためのものです。これは、[Web サービス]または [リファレンス データ接続] フィールドとフォーム フィールドのマッピングと同じです。

以下は、フォーム フィールドを使用した API ソリューション データ接続のマッピングの手順です。

1. [ソリューション データ接続] を右クリックし、[フォーム フィールドの作成] オプションを選択します。

2. [フィールド マッピング] ダイアログで、以下の詳細を入力します。

   1. 説明: このマッピングのテキスト注釈。

   2. グループ名: フォーム スキーマ フィールドのグループ名。すべてのフォーム フィールドは、このグループ内でのみ作成されます。

   3. Web サービス名: フォーム コントロールまたはプラグインで使用されるマッピング名。

   4. このダイアログで [次へ] をクリックします。

3. [フィールド マッピング パラメータ] ダイアログには、Web サービスのフィールド マッピング ダイアログに表示されるものと同様に、すべての API ソリューション データ接続フィールドとフォーム フィールドが表示されます。

4. 要件に応じて、フォーム フィールド タイプまたは最大長を確認または変更します。

5. [OK] をクリックしてマッピングを完了します。

スキーマ フィールドと異なるタイプのフォーム フィールドのマッピングは、[フィールド マッピング] ダイアログで行う必要があります。プロパティからフォーム フィールド タイプを変更しても、WSDL のデータ タイプは変更されません。

次に例を示します。

一部の GET API メソッドの場合、出力スキーマに 日付フィールド があり、その データ型 は文字列です。ユーザーは、[フィールド マッピング] ダイアログで [日付タイプ] を選択する必要があります。

ステップ 4: フォームを設計する

作成済みの、API ソリューション データ接続にマッピングされたフィールドを使用してフォームを設計します。また、フォーム コントロールを配置します (つまり、Web サービス、ルックアップ、クエリ、またはドロップダウン)。これらが API データ接続を実行します。

1. フォーム ビューでフォーム フィールドを設計します。

2. Web サービスとボタン コントロールをフォーム ビューに配置します。このボタンをクリックしたときに API ソリューションのデータ接続を実行するように、Web サービス コントロールとボタン コントロールを構成します。

3. ソリューションを展開します。

ステップ 5: API ソリューション データ接続をテストする

フォームを起動し、API ソリューション データ接続を実行します。

1. フォームを起動します。

2. 構成されたボタンをクリックして、API ソリューション データ接続を実行します。

3. フォームは API を実行し、マップされたフォーム フィールドにレスポンス データを表示します。

   フォーム ソリューションのデータ接続機能を使用して Evolve フォームにデータをダウンロードする場合、次のいずれかを行うことができます。

   • フォームでのユーザー アクションに関するデータをダウンロードします。
   • データ接続アダプター プラグインを使用して、バックグラウンドでデータをダウンロードします。

   ソリューションでは、大量 (1000 件以上のレコード) のデータをフォームにダウンロードしない設計をお勧めします。このような大量のデータをフォームに保存すると、RAM または CPU のリソース使用率が高くなる可能性があります。これは、アプリケーションの他の機能に影響を与え、応答が遅くなったり、ジョブの処理が遅れたりする可能性があります。

   たとえば、クエリの入力パラメータであるフォーム フィールドは、クエリが 1000 を超えるレコードを返さないように設定する必要があります。これを行うには、入力パラメータを必須にすることができます。REST API を使用していて、その API が任意のクエリまたはフィルタで返されるレコードの最大数をサポートしている場合 (OData API には通常カウントまたは $count パラメータ)、そのようなパラメータは、ソリューションの設計時に制限値 (1000 未満) で設定する必要があります。そのため、フォームのエンド ユーザーが意図せずに間違ったフィルターや入力を提供しても、何千ものレコードが返されないようにする必要があります。

[  { "id": 1, "name": "100-100", "productType": "A1", "weightUnit": "W1", "netWeight": 90, "grossWeight": 100, "validityStartDate": "2020-10-03T10:28:45.892275+05:30" }, { "id": 2, "name": "100-200", "productType": "A1", "weightUnit": "W1", "netWeight": 100, "grossWeight": 150, "validityStartDate": "2019-08-30T10:28:46.3904638+05:30" } ]