外部 API

説明

「External API」アクティビティでは、HTTP API 呼び出しを介して、外部システム​からデータをワークフローに取り込みます。

外部システムのエンドポイントには、パブリック API エンドポイント、顧客管理システム、またはサーバーレスアプリケーションインスタンス（Adobe I/O Runtime など）、その他のカテゴリがあります。

このアクティビティの主な特徴は次のとおりです。

• JSON 形式のデータをサードパーティの REST API エンドポイントに渡す機能
• JSON からの応答を受け取り、それを出力テーブルにマッピングして、下流の他のワークフローアクティビティに渡す機能
• アウトバウンド固有のトランジションによる失敗の管理

下位互換性に関する注意

Campaign Standard20.4リリースでは、HTTP応答データのサイズ制限と応答タイムアウトのガードレールが下がり、ベストプラクティスに合わせて調整されました。制限事項とガードレールを参照してください。 これらのガードレールの変更は、既存の外部 API アクティビティには影響しません。したがって、既存の外部 API アクティビティを、すべてのワークフローの新しいバージョンで置き換えることをお勧めします。

「外部 API」アクティビティを置き換える場合は、新しい「外部 API」アクティビティをワークフローに追加し、設定の詳細を手動でコピーしてから、古いアクティビティを削除します。

制限事項とガードレール

このアクティビティには、次のガードレールが適用されます。

• 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。

設定

ワークフローに「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 種類のログメッセージが追加されています。これらは潜在的な問題のトラブルシューティングに役立ちます。

情報

このログメッセージは、ワークフローアクティビティの実行中に有用なチェックポイントに関する情報を記録するために使用されます。

エラー

このログメッセージは、最終的にワークフローアクティビティの失敗を招く可能性のある予期しないエラー状態に関する情報を記録するために使用されます。