外部 API external-api
説明 description
「External API」アクティビティでは、HTTP API 呼び出しを介して、外部システム からデータをワークフローに取り込みます。
外部システムのエンドポイントには、パブリック API エンドポイント、顧客管理システム、またはサーバーレスアプリケーションインスタンス（Adobe I/O Runtime など）、その他のカテゴリがあります。
このアクティビティの主な特徴は次のとおりです。
- JSON 形式のデータをサードパーティの REST API エンドポイントに渡す機能
- JSON からの応答を受け取り、それを出力テーブルにマッピングして、下流の他のワークフローアクティビティに渡す機能
- アウトバウンド固有のトランジションによる失敗の管理
後方互換性に関する注意事項 from-beta-to-ga
Campaign Standard 20.4 リリースでは、ベストプラクティスに合わせて、http 応答のデータサイズ制限と応答のタイムアウトガードレールの値が下げられました。 制限とガードレールを参照してください。 これらのガードレールの変更は、既存の外部 API アクティビティには影響しません。したがって、既存の外部 API アクティビティを、すべてのワークフローの新しいバージョンで置き換えることをお勧めします。
「外部 API」アクティビティを置き換える場合は、新しい「外部 API」アクティビティをワークフローに追加し、設定の詳細を手動でコピーしてから、古いアクティビティを削除します。
制限とガードレール guardrails
このアクティビティには、次のガードレールが適用されます。
- 5 MB HTTP 応答データサイズ制限（注：これは、前のリリースの 50 MB の制限からの変更です）
- 要求のタイムアウトは 1 分です（注：これは、前のリリースの 10 分のタイムアウトからの変更です）
- HTTP リダイレクト：禁止
- HTTPS 以外の URL：却下
- 「Accept: application/json」リクエストヘッダーと「Content-Type: application/json」の応答ヘッダー：許可
特定のガードレールが配置されました。
- JSON の最大深度：JSON のカスタムネストの処理可能な深さを最大 10 レベルに制限。
- JSON の最大キー長：生成される内部キーの最大長を 255 に制限。このキーは列 ID に関連付けられています。
- JSON 最大重複キーの許可：列 ID として使用される重複 JSON プロパティ名の合計数の上限は 150。
設定 configuration
ワークフローに「External API」アクティビティをドラッグ＆ドロップし、アクティビティを開いて設定を開始します。
「INBOUND MAPPING」タブ
インバウンドマッピングは、以前のインバウンドアクティビティによって生成された一時テーブルで、UI に JSON として送信され表示されます。
この一時テーブルに基づいて、ユーザーはインバウンドデータを変更できます。
Inbound resource ドロップダウンでは、一時テーブルを作成するクエリアクティビティを選択できます。
「Add count parameter」チェックボックスをオンにすると、行ごとに一時テーブルから得られるカウント値が追加されます。このチェックボックスは、インバウンドアクティビティが一時テーブルを生成している場合にのみ使用可能です。
「Inbound Columns」セクションでは、インバウンドトランジションテーブルから任意のフィールドを追加できます。選択した列は、データオブジェクトのキーになります。JSON 内のデータオブジェクトは、インバウンドトランジションテーブルの各行から選択した列のデータを含んだ配列リストになります。
「customize parameter」テキストボックスを使用すると、有効な JSON を「外部 API」で必要な追加データと共に追加できます。この追加データは、生成された JSON 内の params オブジェクトに追加されます。
「OUTBOUND MAPPING」タブ
このタブでは、API 呼び出しから返されるサンプル JSON 構造 を定義できます。
JSON パーサーは、標準の JSON 構造パターンタイプに対応するように設計されていますが、一部例外があります。標準パターンの例を次に示します。{“data”:[{“key”:“value”}, {“key”:“value”},...]}
サンプルの JSON 定義には 次の特性 が必要です。
- 配列要素 には、第 1 レベルのプロパティを含める必要があります（これより深いレベルはサポートされていません）。
プロパティ名 は、出力された一時テーブルの出力スキーマの列名になります。 - 取り込む JSON 要素 は、JSON 応答内のネストが 10 レベル以下であることが必要です。
- 列名 の定義は、「data」配列の最初の要素に基づいています。
列定義（追加／削除）とプロパティのタイプ値は、「COLUMN DEFINITION」タブで編集できます。
「Flatten」ェックボックス の動作：
「Flatten」チェックボックス（デフォルトではオフ）は、JSON をキー／値マップにフラット化するかどうかを指定するために用意されています。
-
この チェックボックスが無効（オフ）の場合、サンプル JSON は配列オブジェクトを探すために解析されます。使用したい配列を Adobe Campaign が正確に判断できるように、ユーザーは、API 応答のサンプル JSON 形式をトリミングしたバージョンを提供する必要があります。ワークフロー作成時に、ネストされた配列オブジェクトへのパスが決定されて記録されます。これにより、API 呼び出し実行時に受け取った JSON 応答本文からその配列オブジェクトにアクセスできるようになります。
-
この チェックボックスが有効（オン）の場合、サンプル JSON はフラット化され、提供されたサンプル JSON で指定されたすべてのプロパティが出力一時テーブルの列の作成に使用され、「COLUMN DEFINITION」タブに表示されます。サンプル JSON に配列オブジェクトがある場合は、それらの配列オブジェクトのすべての要素もフラット化されます。
解析が検証 されると、メッセージが表示され、「COLUMN DEFINITION」タブでデータマッピングをカスタマイズするように促されます。その他の場合は、エラーメッセージが表示されます。
「EXECUTION」タブ
このタブでは、接続エンドポイントを定義できます。URL フィールドでは、Campaign Standardがやり取りする HTTPS エンドポイント を定義できます。
エンドポイントで必要な場合、次の 2 種類の認証方法を使用できます。
-
基本認証：「Request Header(s)」セクションにユーザー名とパスワードの情報を入力します。
-
OAuth 認証：外部アカウントの Use connection parameters defined in an external account をクリックすると、OAuth 認証が定義されている外部アカウントを選択できます。 詳しくは、「外部アカウント」の節を参照してください。
「PROPERTIES」タブ
このタブを使用すると、UI に表示されるラベルなど、「外部 API」アクティビティの 一般的なプロパティ を調整できます。内部 ID はカスタマイズできません。
「COLUMN DEFINITION」タブ
「COLUMN DEFINITION」タブでは、エラーのないデータをインポートし、将来の操作に備えて Adobe Campaign データベースに既に存在するデータタイプと一致させるために、各列のデータ構造を正確に指定できます。
例えば、列のラベルを変更し、そのタイプ（文字列、整数、日付など）を選択したり、エラー処理を指定することもできます。
詳しくは、データの追加の節を参照してください。
「TRANSITION」タブ
このタブでは、アウトバウンドトランジション とそのラベルをアクティブ化できます。この特定のトランジションは、タイムアウト の場合、またはペイロードが データサイズ制限 を超える場合に役立ちます。
「EXECUTION OPTIONS」タブ
このタブは、ほとんどのワークフローアクティビティで使用できます。詳しくは、アクティビティのプロパティの節を参照してください。
テスト
シンプルなテストエンドポイントで外部 API 機能をテストするには、Postman Echo （https://docs.postman-echo.com）を使用できます。
トラブルシューティング
この新しいワークフローアクティビティには、情報とエラーの 2 種類のログメッセージが追加されています。これらは潜在的な問題のトラブルシューティングに役立ちます。
情報
このログメッセージは、ワークフローアクティビティの実行中に有用なチェックポイントに関する情報を記録するために使用されます。
エラー
このログメッセージは、最終的にワークフローアクティビティの失敗を招く可能性のある予期しないエラー状態に関する情報を記録するために使用されます。
API URL を解析できませんでした (エラー : 「2010」)。
注意：このエラーは、API URL が検証ルールに失敗した場合に記録されます。
API URL ホストは「localhost」または IP アドレスリテラル (URL ホスト : 「localhost」) でないことが必要です。
API URL ホストは「localhost」または IP アドレスリテラル (URL ホスト : 「192.168.0.5」) でないことが必要です。
API URL ホストは「localhost」または IP アドレスリテラル (URL ホスト : 「[2001]」) でないことが必要です。
JSON リクエスト本文を作成できませんでした。「params」を追加中にエラーが発生しました。
JSON リクエスト本文を作成できませんでした。「data」を追加中にエラーが発生しました。
HTTP ヘッダーキーが正しくありません (ヘッダーキー : 「%s」)。
注意：このエラーは、カスタムヘッダーキーが RFC に従った検証に失敗した場合に記録されます。
HTTP ヘッダー値が正しくありません (ヘッダー値 : 「%s」)。
注意：このエラーは、カスタムヘッダー値が RFC に従った検証に失敗した場合に記録されます。
無効な形式の JSON または受け入れられない形式です。
注意：このメッセージは、「外部 API」からの応答本文の解析にのみ適用され、応答本文がこのアクティビティで必須の JSON 形式に準拠しているかどうかを検証しようとしたときに記録されます。
HTTP 401 エラー応答が原因でアクティビティに失敗した場合：アクティビティに失敗しました (理由 : 「HTTP - 401」)。
内部呼び出しの失敗によりアクティビティが失敗した場合：アクティビティに失敗しました (理由 : 「iRc - -Nn」)。
Content-Type ヘッダーが無効なためアクティビティが失敗した場合：アクティビティに失敗しました (理由 : 「Content-Type - application/html」)。