API 定義からのコネクタの構築

新しいコネクタを作成する

1. [API 定義から開始] を選択した場合、API 定義を指定する必要があります。

   • ローカル ファイルから – Postman または Swagger コレクションをアップロードします。
   • URL から – ファイルの URL を入力します。例: https://petstore.swagger.io/v2/swagger.json
     
     

     

     
     
2. [続行] をクリックします。

コネクタを構成する

1. [インポートを確認] ウィンドウでは次の操作を行えます。

   • [プロバイダー名]、[アプリケーション名]、[コネクタ名] を変更できます。

   • カスタム コネクタで使用するリソースを変更できます。利用可能なすべてのリソースが自動的に有効化されるので、除外するオプションを無効化します。

     • [検索] バーを使用して特定のリソースを検索します。

   • [作成] をクリックします。
     
     

     

     
     
2. [設定] ウィンドウが表示されます。

3. [情報] タブでは、次のフィールドを設定できます。

   • 名前 - コネクタ キーに反映されます。
   • API の種類 – 現在サポートされている API は REST のみであるため、このフィールドは既定で無効化されています。
   • カテゴリ - 人工知能やマーケティングなどの利用可能なカテゴリから選択するか、オンを作成できます。
   • 説明 – コネクタの説明を入力します。
   • アイコン – [ 参照 ] をクリックして、コンピューターから画像をアップロードします。 すべての画像タイプがサポートされていますが、正方形のSVGを使用することをお勧めします。
4. [カタログ プレビュー] では、カスタム コネクタが Integration Service のコネクタ カタログにどのように表示されるかが表示されます。
5. [保存] を選択します。

   
   

   

   
   

ベース API を設定する

[ ベース API ] タブで、アプリケーション API のベース URL とページネーションを設定します。

• ベース URL – コネクタの作成時に宣言された値が自動的に入力されます。
• ページネーションの種類 – ドロップダウンで使用できるオプションは、[ページ番号を 1 から開始]、[ページ番号を 0 から開始]、[オフセット]、[カスタム]、[なし] です。 ベンダーのドキュメントにページネーションの詳細の記載がない場合は、既定値のままにします。 詳しくは、「 ページネーション 」セクションをご覧ください。
• ページネーションの最大値 – 既定値は 100 です。ベンダーのドキュメントにページネーションの詳細の記載がない場合は、既定値のままにします。
• Content-Type ヘッダー – このフィールドは既定では無効になっています。 現在サポートされているのは、 application/json のみです。
• Accept ヘッダー – このフィールドは既定で無効化されています。 現在サポートされているのは、 application/json のみです。
  
  

  

  
  

ページネーション

ページネーションを使用すると、ベンダーアプリケーションは応答の一部を一度にすべてではなく段階的に返すことができるため、応答時間が最適化されます。

ページネーションはさまざまな方法で実装できます。 UiPath コネクタでは、標準化されたページネーション設定が使用されるため、すべてのコネクタが同じように動作します。

[ページ ネーションの種類 ] フィールドと [ ページネーションの最大数 ] フィールドを定義することで、ページネーションの設定をコネクタ レベルで [ 設定] > ベース API で構成できます。リストベースのアクティビティの場合は、リソース レベルでページネーションをさらに設定できます。

ページネーションの種類

[ ページネーションの種類 ] フィールドには、さまざまなプロバイダーの仕様に合わせて複数のオプションが用意されています。

• ページ番号を 1 から開始

• ページは 0 から開始します

• オフセット

• カーソル

• None

カスタム コネクタのアクティビティは、選択した ページネーションの種類に関係なく、Studio 環境で機能します。 ただし、完全な応答を確実に受信するには、正しいページネーションの種類を指定して構成することが重要です。

ページは 1 から始まり、ページは 0 から始まる

ページベースの改ページ位置の自動修正の種類は、プロバイダーに渡されるクエリ パラメーターに依存して、結果のどのページを返すか、およびページあたりの結果の数を示します。

たとえば、GitHub では、「 REST API でのページネーションの使用」で説明されているように、ページベースのページネーションが使用されます。 実装を容易にするために応答ヘッダーに次ページの URL が含まれていますが、基になるメカニズムは Page と per_page クエリ パラメーターに基づいています。

コネクタ ビルダーでは、次のいずれかのオプションを選択できます。

• 「1 で始まるページ 」は、結果の最初のページのインデックスが 1 のページネーションを指します (例: page=1)。
• 「0 で始まるページ 」は、結果の最初のページが 0 のインデックスにあるページネーションを指します (例: page=0)。

リソース構成

既定では、ページベースのページネーションでは、ページング パラメーターとして Page と pageSize が割り当てられます。 これらをプロバイダーの仕様にオーバーライドするには、次のようにします。

1. リソースを選択します。
2. [ ページネーション ] タブを選択します。
3. ページネーションを有効化し、プロバイダーのパラメーターと一致するようにパラメーター名を更新します。

カーソルのページネーション

カーソル ベースの改ページ位置の自動修正は、結果の次のページを返すために後続の呼び出しに渡すことができるページ番号またはオフセット番号ではなく、プロバイダーから返されるページ トークンに依存します。

カーソルベースのページネーションを使用するコネクタをコネクタ ビルダーで要求した場合、返される結果は自動的にページネーションされません。 したがって、後続の呼び出しに次のカーソルを手動で含めない限り、すべての結果が返されるわけではありません。

他のページネーションの種類と同様に、カーソルベースのページネーションには通常、ページごとの結果数を指定する値が含まれます。

リソース構成

カーソルベースの改ページネーションでは、カーソルとページ サイズ (nextPage と pageSize) の既定の名前が提供され、プロバイダーの仕様に合わせてオーバーライドできます。

ページ・トークン・パスの識別

次ページカーソルは、多くの場合、API 応答フィールドに入れ子になっています。 したがって、Integration Service がページ トークン値を抽出して後続の応答で使用できるように、応答スキーマでのカーソルの場所を指定することが重要です。

応答フィールドでの場所は、次のように指定できます。

1. 応答内のどこにあるか (本文またはヘッダー) を特定します。

2. 各レベルをピリオドで区切ってフィールド パスを特定します。

カーソルが URL 内で入れ子になっている場合は、疑問符記号 (?) を使用して、プルするクエリ パラメーターを表すことができます。

例

Meta Graph APIは、コネクタビルダーでカーソルベースのページネーションを使用する良い例です。 メタページネーションのドキュメントでは、各リクエストのどこに次のページトークンがあるかを指定し、トークンまたは完全なURLへの直接参照を含めます。これらの例を使用して、Meta Graph APIのリソースページネーションを構築できます。

1. 選択したリソースで、 nextPage トークン名と pageSize 名をプロバイダー API と一致するように更新します。 Meta Graph APIのドキュメントによると、 nextPage トークン名は after で、 pageSize は limitです。

2. 次に、各要求で nextPage トークンを使用できる場所を特定します。 ドキュメントには、場所をマップする次の JSON が記載されています。

   {
     "data": [
        ... Endpoint data is here
     ],
     "paging": {
       "cursors": {
         "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
         "before": "NDMyNzQyODI3OTQw"
       },
       "previous": "https://graph.facebook.com/{your-user-id}/albums?limit=25&before=NDMyNzQyODI3OTQw"
       "next": "https://graph.facebook.com/{your-user-id}/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
     }
   }

これは応答本文の一部であるため、 nextPage トークンは次の 2 つの 方法で構成できます。

1. ページ トークンへの直接マップ (推奨): body.paging.cursors.after
2. 次の URL を使用します: body.paging.next?after。

どちらのパスでも、 nextPage トークンの値を取得するための正しい場所がコネクタに提供されます。

オフセット ページネーション

オフセットページネーションでは、レコード番号を使用して、すべての応答オブジェクトでページネーションを許可します。 Offset パラメーターは、結果の返却を開始する前にスキップする項目の数を指定します。

オフセットページネーションでは、多くの場合、次の 2 つのパラメーターを使用します (正確な名前は異なる場合があります)

• オフセット - 結果の返却を開始するレコードを指定します。

• 制限 - ページごとの結果の数を示します。

リソース構成

既定では、ページベースのページネーションでは、ページング パラメーターとして Page と pageSize が割り当てられます。 これらをプロバイダーの仕様にオーバーライドするには、次のようにします。

1. リソースを選択します。
2. [ ページネーション ] タブを選択します。
3. ページネーションを有効化し、プロバイダーのパラメーターと一致するようにパラメーター名を更新します。

ページネーションの種類: なし

プロバイダー API でページネーションを使用しない場合は、[ ページネーションの種類 ] を [なし] に設定します。

リソース構成

[ページネーションの種類] を [ なし] に設定すると、[ ページネーション ] タブが [リスト ] アクティビティ リソースから削除されます。

ページネーションの最大値

[ ページネーションの最大値 ] フィールドは、プロバイダーが返すことができる結果の最大数を示します。

Integration Service の結果の上限しきい値は 2,000 です。 効率を向上させるには、小さい数値を使用することをお勧めします。

認証方法を設定する

[認証] タブで、コネクタの認証の種類を設定します。サポートされるオプションについて詳しくは、「認証の種類」をご覧ください。

コネクションをテストする

認証設定が完了したら、ドロップダウン メニューから [コネクションを追加] を選択します。

接続に成功すると、ステータスは [接続済み] に更新されます。

リソース

コネクタ ビルダーは、指定された API 定義に基づいてリソースのリストを生成します。左側のメニューには、グループ別に整理された、利用可能なリソースのリストが表示されます。

1. [その他のオプション] ボタンのメニューをクリックして、各メソッドの詳細な設定を行います。以下を実行できます。
   • メソッドを追加 – [新しいリソースを作成] ウィンドウが開きます。
   • メソッドの削除を許可 – グループの各リソースに対して削除アイコンを有効化します。
   • 編集パス – リソースのパスを編集します。たとえば、[BASE URL]/pet = https://petstore.swagger.io/v2/pet と指定します。
   • 削除 – リソース グループを削除します。この操作は元に戻せないことを示すメッセージが表示されます。
   • 複製 – [リソースを複製] ウィンドウが開きます。このウィンドウではパスの編集、表示名の選択、メソッドの選択ができます。
     
     

     

     
     

2. 次の 2 つの方法で新しいリソース グループを作成することもできます。

   • 空白: 次のフィールドを構成します。
     • パス - [Base URL]/[path]
     • 表示名
     • メソッドを選択 - GET、GETBYID、POST、PUT、PATCH、DELETE
       
       

       

       
       
   • cURL から: cURL コマンドを入力します。

リソースの設定

リソースを選択すると、次のウィンドウが表示されます。

選択したリソース メソッドに応じて、設定タブ ([パラメーター]、[応答フィールド]、[要求フィールド]、[ページネーション]、[検索]) が表示されます。

パラメーター

たとえば、GET メソッドの場合は 4 つのタブすべてが利用可能です。POST メソッドでは、[パラメーター]、[要求フィールド]、および [応答フィールド] タブのみ表示されます。

[ パラメーター] タブでは、選択したリソースで利用可能なパラメーターのリストを確認したり、新しいパラメーターを追加したり、既存のリソースからパラメーターをインポートしたりできます。

この表に一覧表示されているパラメーターは、カスタム コネクタを使用してオートメーションを構築するときに Studio で使用するパラメーターです。

Pet オブジェクトは Pet リソース グループに対応しており、利用可能なフィールドは GETBYID リソース用に設定されたフィールドです。

[応答フィールド] と [要求フィールド]

注:

入れ子になった配列オブジェクトは、現在サポートされていません。

各リソースの [応答フィールド] および [要求フィールド] は、要求を送信する際に自動的に生成されます。

各タブでは、任意のフィールドを編集または削除できます。[編集] アイコンをクリックすると、次の設定ウィンドウが表示されます。

[応答フィールド] と [要求フィールド] タブでは、次のオプションも利用可能です。

• 要求送信時に上書き チェックボックス - オンの場合、 要求の送信の実行時にフィールド リストが再生成されます。 リソースに新しいフィールドを追加した場合は、このオプションを選択しないでください。

• その他のオプション ボタン

  オプション	機能
  応答のルート キーを更新	応答内の入れ子になった配列を処理する場合の応答キーを定義します。
  メソッドのフィールドをすべて削除	選択したメソッドのフィールドをすべて削除します。
  ペイロードから生成	サービス ドキュメントからのサンプル ペイロードまたは API 呼び出しを使用して、リソース フィールドを生成します。

• 行を追加 ボタン - リソースに新しいフィールドを追加します。

[表示する列] アイコンをクリックして、フィールド表内の列を追加または削除します。

[メソッド] 列の各色は、特定のメソッド (GET、GETBYID、POST、PUT、PATCH、DELETE) に対応しています。

ページネーション

要求が一覧で帰ってくることが予想されるリソースの場合は、[ページネーション] を有効化します。また、入れ子になったリストの場合、ページネーションを有効化する時は、[設定] タブで 応答のルート キーを定義する必要があります。

検索

リソースの検索設定を許可するには、[検索を有効化] チェックボックスをオンにします。

必要な構成がすべて完了したら、「構成ファイルを使用する」に進むことができます。