RESTリクエストステップ
RESTリクエストステップは、ワークフローの1ステップとしてREST APIを呼び出します。「構築→送信→確認」の流れ全体を、Postmanのような1つのステップで行えます。エンドポイント(手入力、またはPostmanコレクション、OpenAPI/Swagger仕様、HARキャプチャからインポート)を選択し、ヘッダー、クエリパラメーター、本文を設定し、テストリクエストを送信してライブのレスポンスを確認してから、ステップを保存します。
レスポンスの出力先は選択できます。デフォルトでは、テーブルに解析されます。または、レスポンスをワークフロー変数に取り込み、後続のステップでステータスコードによって分岐したり、本文から値を読み取ったりすることもできます。
保存する前にブラウザーを閉じたり再読み込みしたりした場合、エディターはそのブラウザーにローカルの下書きを保持します。同じステップを再度開き、プロンプトが表示されたら復元を選択すると、未保存のリクエスト設定を回復できます。
開始する前に
Section titled “開始する前に”通常は、サービスのベースURLと認証を保持する、REST種別の接続が必要です。このステップは、接続なしで完全修飾URLを直接呼び出すこともできます。REST接続を参照してください。
RESTリクエストステップを追加する
Section titled “RESTリクエストステップを追加する”- ワークフローを開き、任意の位置にステップを追加します。
- ステップタイプとしてRESTリクエスト(統合) を選択します(RESTステップの下にあります)。エディターが開き、リクエストタブ、レスポンスタブ、テーブルデータの選択タブが表示されます。
リクエストを構築する
Section titled “リクエストを構築する”リクエストタブで次を行います。
エンドポイントソース
Section titled “エンドポイントソース”エンドポイントの指定方法を選択すると、PlaidCloudがリクエストを自動的に入力します。
- 手動 — メソッドとURLを自分で入力します。
- 接続のAPI定義から — 選択した接続に保存されているOpenAPI/Swagger定義を使用するため、ステップごとに指定し直す必要がありません。後述の接続のAPI定義を再利用するを参照してください。
- Postmanコレクション(ファイル) / Postmanコレクション(URL) — Postmanコレクションからインポートします。
- OpenAPI / Swagger(URL) / OpenAPI / Swagger(ファイル) — API仕様からインポートします。
- HARアーカイブ(ファイル) — ブラウザーのネットワークログからキャプチャしたリクエストをインポートします。
インポートしたソースの場合は、カタログをロードを選択して利用可能なエンドポイントを一覧表示し、エンドポイントで1つを選択します。ステップは、各パラメーターの例またはデフォルト値を使用して、そのメソッド、URL、ヘッダー、クエリパラメーター、本文を入力します。どちらもない任意のパラメーターは、オフの状態で始まります。リクエストにすでに入力した内容がある場合、ステップは置き換える前に確認します。以前のリクエストに戻すには、フィールドに入力していないときにCtrl+Z(MacではCmd+Z)を押すか、置換を元に戻すを選択します。
大きなカタログは簡単に絞り込めます。メソッド、パス、名前でフィルター… に入力すると、一致するエンドポイントだけが表示されます。カタログには、保持しているエンドポイントの数(フィルター中は12 / 340)と、ロードされた日時が表示されます。非常に大きな定義がプレビューの上限で切り詰められた場合は、ステップがそのことを通知します。
ファイルを選択する代わりにコレクションや仕様を貼り付ける
Section titled “ファイルを選択する代わりにコレクションや仕様を貼り付ける”ファイルベースの3つのソース(Postmanコレクション、OpenAPI/Swagger、HARアーカイブ)には、いずれもファイルピッカーの横に貼り付け… ボタンがあります。内容は手元にあるものの、ドキュメントに保存していない場合に使用します。JSONを貼り付けて、これを使用を選択します。カタログがすぐにロードされるため、その後でカタログをロードをクリックする必要はありません。
貼り付けた内容はファイルピッカーの代わりに使用され、ステップを開いている間だけ保持されます。ステップとともに保存されないため、ステップを再度開いてその内容からカタログを再ロードしたい場合は、もう一度貼り付けてください。同じソースにファイルも選択した場合は、ファイルが優先され、貼り付けた内容は破棄されます。その場合は、ステップがその旨を通知します。
.jsonファイルをソースピッカーにドロップすることもできます。ステップは、選択したソースに対して内容をチェックし、問題を通知します。たとえば、OpenAPI仕様が必要な場所にPostmanコレクションが貼り付けられている場合や、JSONではないファイルの場合です。また、各ソースにはHow do I get a …? リンクがあり、Postmanコレクション、OpenAPI仕様、HARファイルのエクスポート方法を説明しています。
接続のAPI定義を再利用する
Section titled “接続のAPI定義を再利用する”特定のサービス向けに作られたコネクターは、すでにそのエンドポイントを把握しています。汎用のRESTおよびMuleSoft接続は、任意のAPIを指せるため把握していません。そのため、APIの定義を接続自体に添付できます。
接続に一度設定すれば(汎用REST接続を参照)、その接続を使用する任意のステップで次の手順を行います。
- 接続でその接続を選択します。
- エンドポイントソースを接続のAPI定義からに設定します。
- カタログをロードを選択し、エンドポイントを選択します。
その接続を共有するすべてのステップに同じエンドポイントの一覧が表示され、接続の定義を更新すると、すべてのステップが更新されます。
接続の概要と環境
Section titled “接続の概要と環境”接続ピッカーの下の概要行には、ステップが使用する内容が表示されます。認証タイプ、ホスト、接続がすべてのリクエストで送信するデフォルトヘッダーの数です。接続を変更した後は、ピッカーの横の更新ボタンを選択すると、ステップを開き直さずに、認証、ホスト、デフォルトヘッダーを再ロードできます。接続が環境を定義している場合は、環境ピッカーで、ステップの実行対象を選択します。
接続、メソッド、エンドポイント
Section titled “接続、メソッド、エンドポイント”- 接続 — 認証に使用するREST接続です。未設定のままにすると、完全修飾URLを直接呼び出します。ピッカーの横の編集ショートカットを使用すると、リクエストエディターを離れずに、選択した接続を表示または編集できます。
- メソッド —
GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONSのいずれかです。 - エンドポイント — パス(接続が設定されている場合)、または完全なURLです。
ヘッダー、クエリパラメーター、本文
Section titled “ヘッダー、クエリパラメーター、本文”- ヘッダーとクエリパラメーターは、名前と値の行を持つ編集可能なテーブルで、各行に有効トグルと説明があります。行は追加で追加し、削除で削除します。
- 本文には、リクエストのペイロード(JSON、フォーム、または生のデータ)をコードエディターで入力します。
JSONを整形は本文をインデントし、JSONを検証は本文をチェックして、エラーの行と列を報告します。どちらも、各{{…}}変数を値として読み取るため、変数は書いたとおりに保持されます。変数リファレンス… には、リクエストで使用できるすべての変数が一覧表示され、挿入 {{…}} はカーソル位置に変数を挿入します。
編集中、ステップはリクエストの下に問題を表示します。
- 2回出現するヘッダー名またはクエリパラメーター名。一方の値が失われます。
- 誤入力のように見えるヘッダー名。
Authorizationに対するAuthorisationのように、Did you mean… の候補が表示されます。 AuthorizationやX-API-Keyの値など、プレーンテキストで入力されたシークレット。プロジェクト変数に保持して{{project_var.NAME}}と記述すると、シークレットがステップに保存されません。Content-Type: application/jsonヘッダーのないJSON本文。一部のサーバーはHTTP 415で拒否します。- スキームの誤入力、パス内の二重スラッシュ、末尾のスラッシュ、または余分なスペースのあるURL。
エンドポイント、ヘッダー、クエリの値、本文のどこでも、変数名を二重の中かっこで囲んで{{name}}と記述すると、実行時に変数を挿入できます。ワークフロー実行の変数には{{var.name}}、プロジェクト変数には{{project_var.name}}と記述することもできます。プレフィックスは省略可能で、どちらも同じ名前に解決されます。
エディターは、エンドポイント、ヘッダーとクエリのテーブル、本文エディターで検出された{{...}}トークンを強調表示するため、テストや保存の前に置換を簡単に確認できます。
置換されるのは二重の中かっこだけなので、JSON本文内の単独の{や}は書いたままになります。たとえば{"id": "{{var.order_id}}", "qty": 1}のように、JSONに変数を自由に混在させることができます。不明な変数名はステップを失敗させるため、入力ミスはすぐに判明します。
ワークフローがセンサーまたはWebhookによって開始された場合は、4つのトリガー変数も使用できます。{{trigger_sensor_id}}、{{trigger_sensor_type}}、{{trigger_fired_at}}、{{trigger_payload_json}}(受信したペイロードをJSON文字列にしたもの。ネストされたフィールドにアクセスするには、後続のステップで解析します)です。手動実行またはスケジュール実行では、これらは空の文字列に解決されます。
リクエストをテストする
Section titled “リクエストをテストする”- テストリクエストを送信は、現在の設定でリクエストを送信し、ライブのレスポンスをインラインで表示するため、保存する前に呼び出しが機能することを確認できます。フォームのどこからでもCtrl+Enter(MacではCmd+Enter)を押して送信できます。ステータス行にはHTTPステータスと応答時間が表示され、リクエストの処理中はタイマーがカウントアップします。(これは1つのリクエストを送信します。ページングは、ステップの実行時にのみ動作します。)
- ページングのテストは、設定されたページングに従って、ページをまたいで返されるレコード数(プレビューの上限まで)を報告するため、完全な実行の前に、ページングモードとそのパラメーター/パスが正しく連鎖していることを確認できます。上限に達するのに必要なページ数だけが送信されます。
- curlとしてコピーは、共有やデバッグのために、同等のcurlコマンドをクリップボードにコピーします(シークレットはマスクされます)。
- curlからインポートはその逆の操作です。curlコマンド(たとえば、ブラウザーの「Copy as cURL」)を貼り付けると、そのメソッド、URL、ヘッダー、本文が現在のリクエストを置き換えます。Basic認証(
-u)はAuthorizationヘッダーになり、サポートされていないオプションは、黙って破棄されることなく報告されます。置換を元に戻すを使用すると、以前の値を復元できます。
レスポンスは、整形ビューとコンパクトビューのあるビューアーで開きます。直近5件のテスト結果は、ステップを開いている間保持され、1つを選択して再度表示したり再実行したりできます。レスポンスにレコードのリストが含まれる場合、候補を表示は、最初に見つかったリストを項目パスに設定します。
リクエストプレビューグループには、実行時に送信されるリクエストが、変数が解決され、シークレットがマスクされた状態で、何も送信せずに表示されます。編集後はプレビューを更新を選択します。
送信するリクエストのフィールドを変更し、テストリクエストを送信が成功する前に保存した場合、PlaidCloudはテストが成功していない状態で保存しますか? と確認します。そのまま保存を選択するか、戻ることができます。ファンアウトモードでは、保存する前に行1のテストを使用して、最初のドライバー行をテストします。
レスポンスをルーティングする
Section titled “レスポンスをルーティングする”レスポンスタブで、レスポンスの保存先を設定します。
テーブル(デフォルト)
Section titled “テーブル(デフォルト)”レスポンスはターゲットテーブルに解析されます。このモードでは、ターゲットテーブルは必須です。既存のテーブルを選択するか、ピッカーから作成します。ビューは選択できません。ページングと解析グループで、その方法を制御します。
-
行の形式 — 各レコードがJSONオブジェクトの場合はオブジェクト(デフォルト)、各レコードが値のリストの場合は配列です。テーブルの行ごとに1回のリクエストでは、配列は使用できません。項目パスは、レスポンス内のレコードの場所を指定します。
-
ページングモード — ページングなし(デフォルト)、オフセットページング、ページ番号ページング、次ページURLページング、カーソルページング、Linkヘッダーページング(RFC 5988) のいずれかです。モードパラメーターとモードパスは、ページングを制御するパラメーターとレスポンスのフィールドを指定します。これらは、ページングモードを選択した場合にのみ使用できます。モードを選択すると、両方にそのデフォルトが入力され、編集できます。
モード モードパラメーターのデフォルト モードパスのデフォルト ページングの方法 オフセット {"offset": "offset", "limit": "limit"}{"has_more": ["has_more"]}オフセットとリミットのクエリパラメーターを送信し、レスポンスの has_moreがtrueの間、読み取りを続けます。ページ番号 {"offset": "page"}{"has_more": ["has_more"]}pageパラメーターでページ番号を送信し、リミットは送信しません。次ページURL {}{"next": ["next"]}各レスポンスの nextパスにあるURLをリクエストします。相対URLは、取得元のページを基準に解釈されます。カーソル {"cursor": "after"}{"has_more": ["has_more"], "cursor": ["next_cursor"]}前のレスポンスのカーソルを afterパラメーターで送信します。モードパラメーターに"send_as": "header"または"send_as": "body_field"を追加すると、リクエストヘッダーまたは本文フィールドとして送信します。Azure Cosmos DBが送信するx-ms-continuationヘッダーのように、レスポンスヘッダーからカーソルを読み取るには、モードパスのhas_moreとcursorの代わりに"token_header": "x-ms-continuation"を指定します。最後のページは、そのヘッダーのないページです。Linkヘッダー {"rel": "next"}{}Linkレスポンスヘッダーのうち、relで指定された関係に従います。オフセットとページ番号は、モードパラメーターでさらに多くのキーを受け付けます。
startは最初のオフセットまたはページ番号(デフォルトは0)、stop_on_emptyは項目パスにレコードがない最初のページで停止するため、レスポンスにhas_moreフィールドは不要です。send_limitはlimitパラメーターを送信するかどうかを指定します(デフォルトはオフセットではtrue、ページ番号ではfalseです)。 -
行を解析せずに生のJSONをダンプ — ペイロードを列に解析せず、生のまま保存します。
-
リトライ(0〜100)とタイムアウト(秒)(1〜600)— 失敗時のリクエストの動作と、実行できる時間です。実行では、設定したタイムアウトまで待機します。テストリクエストを送信、行1のテスト、ページングのテストは、最大でも300秒しか待機しません。リトライの対象は、冪等なメソッド(GET、HEAD、OPTIONS、DELETE)での接続障害、サーバーエラー(5xx)、レート制限(HTTP 429)です。POST、PUT、PATCHは、レート制限(HTTP 429)のレスポンスの後でのみリトライされます。これはサーバーが何も処理しなかったことを示しており、サーバーエラーの後には決してリトライされないため、サーバーが処理した可能性のある冪等でないリクエスト本文が2回送信されることはありません。APIが
Retry-Afterヘッダーを返す場合、ステップは要求された間隔(最大2分)待機してからリトライします。
テーブルデータの選択タブは、レスポンスのフィールドをターゲットテーブルの列にマッピングします。ソースを検査 → 入力は、ライブのレスポンスからマッピングを入力します。実行時と同様に、接続を通じてステップのリクエストを送信します。接続が必要で、メソッドがGET、HEAD、OPTIONS以外の場合は、最初に確認します。ステップは解析したレスポンスをターゲットテーブルに直接書き込むため、ここでは集計と重複排除は使用できません。
ワークフロー変数
Section titled “ワークフロー変数”宛先をワークフロー変数に設定し、変数プレフィックス(my_callのような単純な名前)を指定します。ステップは1つのリクエストを送信し、4つのワークフロー変数を書き込みます。
| 変数 | 内容 |
|---|---|
{prefix}_status |
HTTPステータスコード(例: 200)。 |
{prefix}_body |
文字列としてのレスポンス本文(JSONレスポンスはJSONテキストとして保存されます)。 |
{prefix}_headers |
JSONテキストとしてのレスポンスヘッダー。 |
{prefix}_elapsed_ms |
リクエストにかかった時間(ミリ秒)。 |
後続のステップでは、ほかのワークフロー変数と同様に参照します。たとえば{my_call_status}です。これは、「1つのリクエストを送信して、結果で分岐する」パターンの基本要素です。
テーブルの行ごとに1回のリクエストを送信する
Section titled “テーブルの行ごとに1回のリクエストを送信する”デフォルトでは、ステップは1つのリクエストを送信します。テーブルの行ごとにAPIを1回ずつ呼び出すには(たとえば、テーブル内のすべての顧客IDを検索する、または各行をレコードとしてPOSTする場合)、リクエストタブの送信をテーブルの行ごとに1回のリクエストに設定します。これにより、ドライバーテーブルのフィールドが表示されます。
- ドライバーテーブル — リクエストの基になる行を持つテーブルを選択します。ピッカーでワークフローのテーブルから選択するか、テーブル名を入力します。各行の列は、
{{row.column}}トークンとして使用できます。 - ドライバーフィルター (任意) — 使用する行を制限するSQLの
WHERE句です。 - キー列 (任意) — すべての出力行に引き継ぐドライバー列をカンマ区切りで指定します。結果をドライバーに結合し直せます。
- 行数の上限と同時実行数 — 処理する最大行数と、同時に実行するリクエスト数です。
- 最大リクエスト数/秒 (任意) — すべてのワーカーでリクエストの開始速度を制限し、バーストがAPIのレート制限に達しないようにします(0 = 制限なし)。値には小数も指定でき、0.5は2秒ごとに1つのリクエストを開始します。1000を超える値は、警告とともに1000として実行されます。これは同時実行数とは独立しています。同時実行数は同時に実行される数を制限し、最大リクエスト数/秒は新しいリクエストを開始する頻度を調整します。
- Add Idempotency-Key header (任意) — 行ごとに1つの(ページングなしの)POST、PUT、PATCHリクエストの場合、各行から導出した安定した
Idempotency-Keyヘッダーを送信します。これにより、ステップを再実行しても、冪等性に対応したAPIでレコードが二重に作成されません(同じ行は常に同じキーを送信するため、APIが繰り返しを重複排除します)。GET/HEAD/DELETEの場合や、ページングモードがオンの場合は、警告とともに無視されます。すでに独自のIdempotency-Keyを設定しているリクエストは、それを保持します。 - レスポンス — 各レスポンスを行にする方法です。解析済みレコード(デフォルト)は、各レスポンスのレコードを1行として書き込みます。テキスト(リクエストごとに1行) は、
DownloadData列とDownloadHeaders列を持つ、リクエストごとに1行を書き込みます。失敗したリクエストは破棄されます。未加工テキスト(エラーも行として保持) もリクエストごとに1行を書き込みますが、本文をサーバーが送信したとおりに保持し、DownloadStatus列を追加し、HTTPエラーまたはトランスポートエラーを、そのエラー本文とステータスとともに行として保持します。認証情報は、すべての未加工行の本文、ヘッダー、エラーテキストでマスクされ、認証情報を含むリクエストでは、別のオリジンへのリダイレクトは追跡されません。ページングはテキストモードには適用されません。テキスト(リクエストごとに1行) では、Keep error response(keep_error_response)を使用すると、HTTP 400以上のレスポンスの本文を、成功時と同様に行に書き込み、行を失敗させません。また、出力に DownloadStatus、DownloadReason、DownloadUrl を追加する(response_meta)を使用すると、レスポンスのステータス、理由、最終URLを保持するDownloadStatus、DownloadReason、DownloadUrl列が追加されます。どちらもデフォルトではオフです。ステップのフォームには出力に DownloadStatus、DownloadReason、DownloadUrl を追加するオプションがあります。keep_error_responseは、AIアシスタントまたはREST APIで設定してください。 - Continue on error — オンにすると、失敗した行が記録され、最初の失敗で中止する代わりに、ステップは警告付きで終了します。実行ログには、失敗した最初のいくつかの行(キー列で識別)と、それぞれで発生したエラーが記載されるため、どの行がなぜ失敗したかを確認できます。
エンドポイント、クエリ、ヘッダー、本文のどこでも{{row.column}}トークンを使用すると、その行の値に置換されます。たとえばGET /customers/{{row.customer_id}}です。クエリパラメーターの値は1回だけURLエンコードされるため、サーバーはA 1とa/bを入力したとおりに受け取ります。以前のバージョンでは2回エンコードされ、サーバーはA%201とa%2Fbを受け取っていました。POST、PUT、PATCHのステップでAdd Idempotency-Key headerがオンで、クエリにエンコードが必要な行の値がある場合、リクエストが変わったため、アップグレード後に一度だけキーが変わります。アップグレードをまたぐ再実行では、そのような行ごとに1回、繰り返しのリクエストが送信される可能性があります。英字、数字、-._~のみで構成される値は変わりません。各行のレスポンスレコードはターゲットテーブルに解析されます(キー列が先頭に付加されます)。生のJSONをダンプがオンの場合は、代わりにリクエストごとに1行になります。
挿入 {{row.column}} メニューには、選択したドライバーテーブルの列が一覧表示されるため、列名を手で入力する代わりに、最後に編集したフィールド(エンドポイントまたは本文)に{{row.customer_id}}のようなトークンを挿入できます。編集中、フォームには使用した{{row.column}}トークンも一覧表示され、ドライバーテーブルの列ではないものは赤で強調表示されるため、実行前に入力ミスに気付くことができます。
行1のテストは、最初のドライバー行を読み取り(ドライバーフィルターを適用)、その値をエンドポイント、クエリ、ヘッダー、本文に置換して、その1つのリクエストを送信します。そのため、すべての行で実行する前に、ファンアウトが正しく設定されていることを確認できます。レスポンスはテストリクエストを送信と同様にインラインで表示され、使用されたドライバー行の値も表示されます。Preview Row 1も同様に、最初のドライバー行の{{row.column}}値を解決し、リクエストを送信せずに、解決後のリクエストを表示します。
ステップを実行する
Section titled “ステップを実行する”RESTリクエストステップは、ほかのステップと同様に、完全な実行の一部として、または単独で実行されます(ワークフロー内の1つのステップを実行するを参照)。テーブルモードでは、解析した(または未加工の)レスポンスをターゲットテーブルに書き込みます。変数モードでは、後続のステップが読み取る4つの変数を設定します。
次のステップ
Section titled “次のステップ”- RESTリクエストステップリファレンス — フィールド一覧の簡易版
- ワークフロー変数を管理する — ステップ間で変数を読み取り、設定します
- REST接続 — 認証付きAPI接続を設定します