RESTリクエストステップ

説明

RESTリクエストステップは、ワークフローの1つのステップとしてREST APIを呼び出します。「構築 → 送信 → 確認」というサイクル全体を、Postmanのような1つのステップで行えます。エンドポイントを選択し（手入力、またはPostmanコレクション、OpenAPI/Swagger仕様、HARキャプチャーからのインポート）、ヘッダー、クエリパラメーター、本文を設定し、テストリクエストを送信してライブのレスポンスを確認してから、ステップを保存します。

レスポンスの保存先は選択できます。デフォルトでは、テーブルに解析されます。または、レスポンスをワークフロー変数に取り込み、後続のステップでステータスコードに応じて分岐したり、本文から値を読み取ったりすることもできます。

保存する前にブラウザーを閉じたり再読み込みしたりした場合、エディターはそのブラウザーにローカルの下書きを保持します。同じステップをもう一度開き、プロンプトが表示されたら復元を選択すると、未保存のリクエスト設定を復元できます。

始める前に

通常は、サービスのベースURLと認証を保持する、RESTタイプの接続が必要です。接続なしで、完全修飾URLをステップから直接呼び出すこともできます。REST接続を参照してください。

RESTリクエストステップを追加する

ワークフローを開き、任意の位置にステップを追加します。
ステップタイプとして（RESTステップの下にある）REST Request (unified) を選択します。エディターが開き、リクエストタブ、レスポンスタブ、テーブルデータの選択タブが表示されます。

リクエストを構築する

リクエストタブで操作します。

エンドポイントソース

エンドポイントの指定方法を選択すると、PlaidCloudがリクエストを自動的に入力します。

手動 — メソッドとURLを自分で入力します。
接続のAPI定義から — 選択した接続に保存されているOpenAPI/Swagger定義を使用するため、ステップごとに指定し直す必要がありません。下の接続のAPI定義を再利用するを参照してください。
Postmanコレクション（ファイル） / Postmanコレクション（URL） — Postmanコレクションからインポートします。
OpenAPI / Swagger（URL） / OpenAPI / Swagger（ファイル） — API仕様からインポートします。
HARアーカイブ（ファイル） — ブラウザーのネットワークログからキャプチャーしたリクエストをインポートします。

インポートしたソースの場合は、カタログをロードを選択して利用可能なエンドポイントを一覧表示し、エンドポイントでいずれかを選びます。ステップが、メソッド、URL、ヘッダー、クエリパラメーター、本文を、各パラメーターの例またはデフォルト値を使って入力します。例もデフォルト値もない任意のパラメーターは、オフの状態で始まります。リクエストにすでに入力した内容がある場合は、置き換える前にステップが確認します。フィールドに入力していないときに Ctrl+Z（Macでは Cmd+Z）を押すか、置換を元に戻すを選択すると、以前のリクエストに戻せます。

大きなカタログも簡単に絞り込めます。メソッド、パス、名前でフィルター… に入力すると、一致するエンドポイントだけが一覧表示されます。カタログには、保持しているエンドポイント数（フィルター中は 12 of 340）とロードされた日時が表示され、非常に大きな定義がプレビューの上限で切り詰められた場合は、ステップがそのことを知らせます。

ファイルを選択する代わりにコレクションまたは仕様を貼り付ける

ファイルベースの3つのソース（Postmanコレクション、OpenAPI/Swagger、HARアーカイブ）には、いずれもファイルピッカーの横に貼り付け… ボタンがあります。内容は手元にあるが、Documentに保存していない場合に使用します。JSONを貼り付けてこれを使用を選択します。カタログがすぐにロードされるため、そのあとでカタログをロードをクリックする必要はありません。

貼り付けた内容はファイルピッカーの代わりに使用され、ステップを開いている間だけ保持されます。ステップとともには保存されないため、ステップを開き直して、その内容からカタログを再ロードしたい場合は、もう一度貼り付けてください。同じソースにファイルを指定すると、ファイルが優先され、貼り付けた内容は破棄されます。その場合は、ステップがお知らせします。

.json ファイルをソースピッカーにドロップすることもできます。ステップは、内容を選択したソースと照合し、問題があれば知らせます。たとえば、OpenAPI仕様を想定している場所にPostmanコレクションを貼り付けた場合や、JSONではないファイルの場合です。各ソースには How do I get a …? リンクがあり、Postmanコレクション、OpenAPI仕様、HARファイルのエクスポート方法を説明しています。

接続のAPI定義を再利用する

特定のサービス向けに作られたコネクターは、そのエンドポイントをすでに把握しています。汎用RESTとMuleSoftの接続は任意のAPIを指せるため把握しておらず、APIの定義を接続自体に添付できるようになっています。

接続に一度設定すれば（汎用REST接続を参照）、その接続を使用する任意のステップで次のようにします。

接続で接続を選択します。
エンドポイントソースを接続のAPI定義からに設定します。
カタログをロードを選択して、エンドポイントを選びます。

その接続を共有するすべてのステップで同じエンドポイントリストが利用でき、接続の定義を更新すると、すべてのステップに反映されます。

接続のサマリーと環境

接続ピッカーの下のサマリー行に、ステップが使用する内容が表示されます。認証タイプ、ホスト、接続がすべてのリクエストで送信するデフォルトヘッダーの数です。接続を変更したあとは、ピッカーの横の更新ボタンを選択すると、ステップを開き直さずに、認証、ホスト、デフォルトヘッダーが再ロードされます。接続が環境を定義している場合は、環境ピッカーで、ステップが実行される環境を選択します。

接続、メソッド、エンドポイント

接続 — 認証に使用するREST接続です。未設定のままにすると、完全修飾URLを直接呼び出します。ピッカーの横の編集ショートカットを使うと、リクエストエディターを離れずに、選択した接続を表示または編集できます。
メソッド — GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS のいずれかです。
エンドポイント — パス（接続を設定している場合）または完全なURLです。

ヘッダー、クエリパラメーター、本文

ヘッダーとクエリパラメーターは、名前と値の行を編集できるテーブルで、それぞれに有効トグルと説明があります。行は追加で追加し、削除で削除します。
本文には、リクエストのペイロード（JSON、フォーム、または未加工）をコードエディターで入力します。

JSONを整形は本文にインデントを付け、JSONを検証は本文を検査して、エラーの行と列を報告します。どちらも {{…}} 変数を値として扱うため、変数は記述したとおりに保持されます。変数リファレンス… には、リクエストで使用できるすべての変数が一覧表示され、挿入 {{…}} はカーソル位置に変数を挿入します。

編集中、ステップはリクエストの下に問題を表示します。

2回出現するヘッダー名またはクエリパラメーター名。どちらかの値が失われます。
入力ミスと思われるヘッダー名。Did you mean… の候補が表示されます（たとえば Authorization に対する Authorisation）。
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文字列にしたもの。ネストされたフィールドにアクセスするには、後続のステップで解析します）です。手動実行またはスケジュール実行では、これらは空の文字列に解決されます。

リクエストをテストする

テストリクエストを送信は、現在の設定でリクエストを送信し、ライブのレスポンスをインラインで表示するため、保存前に呼び出しが機能することを確認できます。フォーム内のどこからでも Ctrl+Enter（Macでは Cmd+Enter）を押して送信できます。ステータス行にHTTPステータスと応答時間が表示され、リクエストの処理中はタイマーがカウントアップします。（これは単一のリクエストを送信します。ページングは、ステップの実行時にのみ動作します。）
ページングのテストは、設定されたページングに従って、ページをまたいで返されるレコード数（プレビューの上限まで）を報告します。これにより、フルランの前に、ページングモードとそのパラメーターやパスが正しく連鎖するかを確認できます。上限に達するのに必要なページ数だけが送信されます。
curlとしてコピーは、共有やデバッグのために、同等のcurlコマンドをクリップボードにコピーします（シークレットはマスクされます）。
curlからインポートはその逆で、curlコマンド（たとえばブラウザーの「Copy as cURL」）を貼り付けると、そのメソッド、URL、ヘッダー、本文が現在のリクエストを置き換えます。Basic認証（-u）はAuthorizationヘッダーになります。サポートされていないオプションは、黙って破棄されずに報告されます。置換を元に戻すを使うと、以前の値を復元できます。

レスポンスは、整形とコンパクトのビューを持つビューアーで開きます。ステップを開いている間は直近5件のテスト結果が保持され、選択して再表示したり、再実行したりできます。レスポンスにレコードのリストが含まれている場合、候補を表示は、最初に見つかったリストを項目パスに設定します。

リクエストプレビューグループには、変数を解決し、シークレットをマスクした状態で、実行時に送信されるとおりのリクエストが、実際には何も送信せずに表示されます。編集したあとは、プレビューを更新を選択してください。

送信するリクエストのフィールドを変更し、テストリクエストを送信が成功する前に保存すると、PlaidCloudはテストが成功していない状態で保存しますか？ と確認します。そのまま保存を選択するか、戻ります。ファンアウトモードでは、保存前に最初のドライバー行をテストするには、行1のテストを使用します。

レスポンスをルーティングする

レスポンスタブで、レスポンスの保存先を設定します。

テーブル（デフォルト）

レスポンスはターゲットテーブルに解析されます。このモードでは必須です。既存のテーブルを選択するか、ピッカーから作成してください。ビューは選択できません。ページングと解析グループで、その方法を制御します。

行の形式 — 各レコードが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"}`	`{}`	`rel` で指定された関係を持つ、`Link` レスポンスヘッダーをたどります。

オフセットとページ番号では、モードパラメーターでさらに次のキーを使用できます。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分）だけ待機してからリトライします。

テーブルデータの選択タブでは、レスポンスのフィールドをターゲットテーブルの列にマッピングします。ソースを検査 → Populate は、ライブのレスポンスからマッピングを入力します。実行時と同じように、ステップのリクエストを接続経由で送信します。接続が必要で、メソッドがGET、HEAD、OPTIONS以外の場合は、最初に確認します。ステップは解析したレスポンスをターゲットテーブルに直接書き込むため、ここでは集計と重複排除は選択できません。

ワークフロー変数

宛先をワークフロー変数に設定し、変数プレフィックス（my_call のような単純な名前）を指定します。ステップは1回のリクエストを送信し、4つのワークフロー変数を書き込みます。

変数	内容
`{prefix}_status`	HTTPステータスコード（例: `200`）。
`{prefix}_body`	文字列としてのレスポンス本文（JSONレスポンスはJSONテキストとして保存されます）。
`{prefix}_headers`	JSONテキストとしてのレスポンスヘッダー。
`{prefix}_elapsed_ms`	リクエストにかかった時間（ミリ秒）。

ほかのワークフロー変数と同様に、下流で参照します（例: {my_call_status}）。これは、「1つのリクエストを送信し、その結果で分岐する」パターンの基本要素です。

テーブルの行ごとに1回のリクエストを送信する

デフォルトでは、ステップは1回のリクエストを送信します。テーブルの行ごとにAPIを1回ずつ呼び出すには（たとえば、テーブル内のすべての顧客IDを検索する、各行をレコードとしてPOSTするなど）、（リクエストタブの）送信をテーブルの行ごとに1回のリクエストに設定します。すると、ドライバーテーブルのフィールドが表示されます。

ドライバーテーブル — 行がリクエストを駆動するテーブルを選択します。ピッカーでワークフローのテーブルから選択するか、テーブル名を入力します。各行の列は {{row.column}} トークンとして使用できます。
ドライバーフィルター (任意) — 使用する行を制限するSQLの WHERE 句です。
キー列 (任意) — すべての出力行に引き継ぐドライバー列をカンマ区切りで指定します。これにより、結果をドライバーに結合し直せます。
行数の上限と同時実行数 — 処理する最大行数と、同時に実行するリクエストの数です。
最大リクエスト数/秒 (任意) — すべてのワーカーでリクエストの開始速度に上限を設けて、バーストによってAPIのレート制限に引っかからないようにします（0 = 制限なし）。値には小数も指定できます。0.5は2秒ごとに1リクエストを開始します。1000を超える値は、警告とともに1000として実行されます。これは同時実行数とは独立しています。同時実行数は同時に実行される数を制限し、最大リクエスト数/秒は新しいリクエストを開始する頻度を調整します。
Add Idempotency-Key header (任意) — 行ごとに単一の（ページングなしの）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}} のようにします。クエリパラメーターの値はURLエンコードが1回だけ行われるため、サーバーは入力されたとおりの 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}} の値を解決し、解決されたリクエストを送信せずに表示します。

ステップを実行する

RESTリクエストステップは、ほかのステップと同じように、ワークフロー全体の実行の一部として、または単独で実行されます（ワークフロー内の1つのステップを実行するを参照）。テーブルモードでは、解析された（または未加工の）レスポンスをターゲットテーブルに書き込みます。変数モードでは、後続のステップが読み取れるように、4つの変数を設定します。

次のステップ

RESTリクエストステップのリファレンス — フィールドの簡潔な一覧
ワークフロー変数の管理 — ステップ間で変数を読み取り、設定する
REST接続 — 認証付きのAPI接続を設定する