REST API
|
|
RESTful APIにデータの取得、変更、または削除のリクエストを送信し、レスポンスで返されたデータをスクリプト内の他の場所で使用できるように格納します。 |
例えば、個人情報やメンバーシップの詳細など、顧客のメンバーシップデータを提供するAPI Webサービスに接続できます。その後、このデータを格納し、一部または全部を発信側に再生または送信できます。
アクションセルは、HTTPリクエストボディのオブジェクト変数を介して（フラットJSONデータよりも）複雑なデータをAPIに渡すことによって、[Webサービス]アクションセルで提供されるREST接続方式を拡張します。データは自動的にJSON形式に変換されます。アクションセルは、返されたデータを変数（オブジェクト変数タイプなど）に格納し、サービスの他の部分で使用できます。
メモ：ネットワークのホワイトリストがconnect storm展開で有効になっている場合は、Content Guru社がホワイトリストに含まれていることを確認してください。
プロパティ
「REST API」セクション
このセクションでは、変数を使用しHTTPリクエストボディを設定してください。
メモ：HTTPS経由のリクエストには、CA（認証局）署名付き証明書が必要です。Content Guru社は自己署名証明書に対応していません。
|
オプション |
内容 |
|
エンドポイント |
呼び出すAPIの完全修飾エンドポイントアドレスを入力してください（先頭に「=」を付けたリテラル値、または文字列変数）。 例えば、「=https://api.servicing.com/customers/portfolios」 |
|
HTTP Verb |
下記のHTTPリクエストメソッドのいずれかを選択してください。 APIエンドポイントからデータを取得するにはGETを使用。 「リクエストボディ」のデータをAPIエンドポイントに送信するにはPOSTを使用。 APIエンドポイントのデータを削除するにはDELETEを使用。 「リクエストボディ」のデータを使用し、APIエンドポイントでデータを作成または更新するには、PUTを使用。 リクエストボディのデータを使用し、APIエンドポイントでデータを部分的に変更するにはPATCHを使用。 |
|
リクエストボディ |
POST、PUT、およびPATCHリクエストメソッドにのみ適用されます。 （オプション）APIのリクエストボディ。20KBを超えないようにしてください。 =で始まるリテラル値か、適切な変数にしてください。 オブジェクト変数を指定する場合は、他のアクションセルを使用し、オブジェクトメンバーに適切な値が入力されていることを確認してください。 [REST API]アクションセルは、実行時にオブジェクトのJSON文字列の表現を作成します。 |
|
タイムアウト |
HTTPリクエストへのレスポンスを待つ時間を選択してください。この値は1～60秒の範囲で指定する必要があります。この時間内にレスポンスがない場合、設定されたエンドポイントへのリクエストはキャンセルされ、「タイムアウト」遷移ルートに進みます。 |
「認証」セクション
APIへのアクセスに認証が必要な場合は、このセクションを使用してください。単純なベアラートークン認証方式を使用できます。「OAuth」と「JSON Webトークン」認証を使用する場合は、お客様の組織に対してプロファイルを設定する必要があります。この作業はContent Guru社でないと行えませんので、ご注意ください。
この他にも、独自のカスタム認証方法も使用できます。カスタム認証方式は、Content Guru社によるカスタム開発が必要で、追加の費用がかかる場合があります。
|
オプション |
内容 |
|
認証を有効にする |
APIが認証を必要とする場合は、このチェックボックスを選択します。 |
|
認証方法 |
認証方式を、ベアラートークン、OAuth、JSON Webトークン、またはカスタム認証方法から選択してください。 |
|
ベアラートークン |
選択した認証方式が「ベアラートークン」の場合に表示されます。 ベアラートークンを指定します。=で始まるリテラル値か、文字列変数にしてください。 |
|
OAuthプロファイル |
認証方式に「OAuth」を選択されている場合に表示されます。 あらかじめ設定されているOAuthプロファイルを指定してください。Oauthの時は必ず、クライアント認証情報の付与型（client credentials grant type）を使用してください。 |
|
JSON Webトークン |
認証方式に「JSON Webトークン」を選択されている場合に表示されます。 あらかじめ設定されているJSON Webトークンプロファイルを指定してください。 |
「リクエストヘッダー」セクション
リクエストコンテキストに関する追加情報を提供する（API応答を調整する場合など）場合は、このセクションを使用してください。
「名前」フィールドには、渡すパラメータのラベルを記入してください。値フィールドに、=で始まるリテラル値か、文字列変数で渡す値を入力してください。
「追加」をクリックすると、名前と値のペアが下のリストに追加されます。
メモ：Content-Lengthなどの一部のヘッダーは自動的に設定されますが、Cookie、Origin、Feature-Policyなどの他のヘッダーはセキュリティのため保護され、上書きできません。これらは無視されるため、このセクションに入力するために使用しないでください。https://developer.mozilla.org/en-US/docs/Glossary/Forbidden_header_nameを参照してください。
「出力」セクション
このセクションでは、APIから返された結果を格納してください。
|
オプション |
内容 |
|
HTTPステータスコード |
APIで返された結果のコードを格納する整数型変数です。このコードはHTTPリクエストが成功したか失敗したか（失敗原因を含む）を示すため、特定の失敗ケースに対して特別な処理を提供できます。 |
|
サクセスレスポンスボディ |
（オプション）HTTPステータスコード2xxが受信されて、HTTPリクエストが成功した場合に、APIのリスポンスボディが格納されます。そのための適切な型の変数を指定してください。制限は20KBです。 変数を指定する場合、アクションセルは、APIレスポンスのパラメータ値を解析し、FLOWの正しい変数タイプへ入力します。 例えば、パラメータ値”5”（引用符で囲み）が受信され、FLOW変数が整数型の場合は、アクションセルは値を整数として解析します。この表の下にあるオブジェクト変数に関するメモのうち、一番目もご参照ください。 パラメータ値を解析できない場合は、「無効なレスポンス」遷移ルートに沿って実行が続行されます。 |
|
エラーレスポンスボディ |
（オプション）HTTPリクエストが失敗した場合（返って来たHTTPステータスコードが2xx以外）のAPIのリスポンスボディを格納します。適切な型の変数を指定してください。制限は20KBです。 変数を指定する場合、アクションセルは、APIレスポンスのパラメータ値を解析し、FLOWの正しい変数タイプへ入力します。 この表の下にあるオブジェクト変数に関するメモのうち、一番目もご参照ください。 パラメータ値を解析できない場合は、「無効なレスポンス」遷移ルートに沿って実行が続行されます。 |
メモ：オブジェクト変数を使用してレスポンスを格納する場合は、オブジェクト内のメンバーの数が、レスポンスボディで返されたパラメータの数と一致することを確認する必要があります。一致しない場合は、オブジェクトメンバーのない返されたパラメータ値が、アクションセルで無視されます。また、オブジェクトメンバーが想定しているパラメータがレスポンスにない場合は、これらのオブジェクトメンバーはデフォルト値が入力されます（例えば、整数の場合は0）。
メモ：日付/時刻変数（ISO 8601形式）は、connect stormの日付/時刻形式に変換されます。例えば、英国夏時間（BST）のプラットフォームでは、日付/時刻「2021-06-20T10:00+06:00」は「2021-06-20T05:00:00」に変換されます。
遷移点
|
遷移点 |
内容 |
|
成功 |
HTTPリクエストが送信され、HTTPステータスコード2xx（201、201、205など）が受信された場合。 |
|
エラーレスポンス |
HTTPリクエストが送信され、（4xxないし5xxなど）2xx以外のHTTPステータスコードが受信された場合。 |
|
無効な応答 |
「サクセスレスポンスボディ」または「エラーレスポンスボディ」で指定された変数型が、返されたデータ型と一致しない場合。例えば、いずれかのプロパティに文字列変数型を指定したが、APIがオブジェクト型を返した場合など。 |
|
タイムアウト |
「タイムアウト」に指定されたタイムアウト期間内に応答が受信できなかった場合。 |
|
エラー |
ネットワーク障害や内部エラーなどの一般的なエラーが発生した場合。 |
例
|
|
|
 |
左側の設定例では、下記のようなHTTPリクエストが作成されます。 オブジェクト変数objRequestObjectには、リクエストのJSON形式のセクションに示されるように、データメンバーが含まれています。
|
メモ：ヘッダーには、「Host」、「Content-Type」、「Content-Length」が自動生成され、常に存在します。
POST/HTTP/1.1
Host: www.google.com
Content-Type: application/json; charset=UTF-8
Authorization: Bearer abc
Content-Length: 595
X-Custom-Header: def
[Content Guru社の内部的な目的のために自動生成された追加のヘッダー]{
"szString": "value",
"lInteger": 3,
"bBoolean": true,
"fFloat": 67.89,
"dtDateTime": "2020-12-18T12:00:00",
"objObject2": {
"arrintIntegerArray": [1, 2, 3],
"arrszStringArray": ["value1", "value2", "value3"],
"arrbBooleanArray": [true, false, true],
"arrfFloatArray": [10.1, 15.42, 7.0],
"arrdtDateArray": ["2020-12-18T12:00:00", "2020-12-19T12:00:00", "2020-12-20T12:00:00"]
},
"arrobjObject3Array": [{
"szString": "value1"
}, {
"szString": "value2"
}, {
"szString": "value3"
}]
}