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ごとの クエリ パラメーターに基づいています。

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

• ページ番号が 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. 選択したリソースで、プロバイダー API と一致するように nextPage トークン名と pageSize 名を更新します。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="  }}{  "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="  }}

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

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 メソッドの場合、[Parameters]、[Request Fields]、および [Response Fields] の各タブのみが表示されます。

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

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

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

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

注:

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

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

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

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

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

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

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

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

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

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

ページネーション

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

検索

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

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