このページ： サードパーティ REST APIに接続して認証を設定し、条件とパーソナライゼーションのために外部データをジャーニーに取り込めるようにします。
外部データソースの操作 gs-ext-data-sources
外部データソースを使用すると、サードパーティシステムへの接続を定義できます。例えば、ホテルの予約システムを使用して、部屋が登録されたかどうかを確認する場合などです。 組み込みのAdobe Experience Platform データソースとは異なり、必要な数の外部データソースを作成できます。
-
外部システムを操作する際のガードレールについて詳しくは、このページを参照してください。
-
応答がサポートされるようになったので、外部データソースのユースケースでは、データソースの代わりにカスタムアクションを使用する必要があります。 応答について詳しくは、 カスタムアクション応答を参照してください。 データレイクの永続性を持たないカスタムアクションは、データがジャーニー内でのみ有効で、API エンドポイントを介して外部システムにアクセスできる場合に適した選択肢です。 すべてのデータ アクセス オプションの比較については、 データ アクセス戦略の選択を参照してください。
POST または GET を使用して JSON を返す REST API がサポートされています。 API キー、基本およびカスタム認証モードがサポートされています。
リアルタイムの天気データに応じて、ジャーニーの動作をカスタマイズするために使用する、天気 API サービスの例を見てみましょう。
以下に API 呼び出しの例を 2 つ示します。
- https://api.adobeweather.org/weather?city=London,uk&appid=1234
- https://api.adobeweather.org/weather?lat=35&lon=139&appid=1234
呼び出しにはメイン URL（https://api.adobeweather.org/weather）、2 つのパラメーターセット（都市の場合は「city」、緯度と経度の場合は「lat/long」）、および API キー（appid）が含まれます。
cacheDuration 設定の間に 1 分以上のバッファーを残すことをお勧めします。外部データソースの作成と設定 create-ext-data-sources
新しい外部データソースを作成して設定する主な手順は次のとおりです。
-
データソースのリストから、「データSourceを作成」をクリックして、新しい外部データソースを作成します。
画面の右側にデータソース設定ペインが開きます。
-
データソースの名前を入力します。
英数字とアンダースコアのみが使用できます。 最大長は 30 文字です。
-
データソースに説明を追加します。 この手順はオプションです。
-
外部サービスの URL を追加します。 この例では、次のようになります。https://api.adobeweather.org/weather。
note caution CAUTION セキュリティ上の理由から、HTTPS の使用を強くお勧めします。 また、アドビの非公開アドレスや IP アドレスの使用は許可されていません。 
-
外部サービスの設定に応じて認証を認証なし、基本、カスタムまたは API キーに設定します。
基本認証モードの場合は、ユーザー名とパスワードを入力する必要があります。
note NOTE -
認証呼び出しを実行すると、base64 でエンコードされた
<username>:<password>文字列が認証ヘッダーに追加されます。 -
Adobe Journey Optimizerは、カスタムアクションで定義されたシークレットを自動的に暗号化します。 各組織の暗号化キーは、その組織に関連付けられた専用のコンテナで安全に管理されます。 資格情報をインターフェイスに表示する際、誤って公開されないように、デフォルトではマスクされます。
カスタム認証モードについて詳しくは、 カスタム認証モードの節を参照してください。 この例では、以下のように API キー認証モードを選択します。
-
タイプ：API キー
-
名前：“appid”（API キーのパラメーター名）
-
値：“1234”（API キーの値）
-
位置：「クエリパラメーター」（API キーは URL 内にあります）
-
-
「新しいフィールドグループを追加」をクリックして、API パラメーターセットごとに新しいフィールドグループを追加します。 フィールドグループ名には、英数字とアンダースコアのみを使用できます。 最大長は 30 文字です。 この例では、各パラメーターセット（都市と経度／緯度）ごとに 1 つずつ、2 つのフィールドグループを作成する必要があります。
「long/lat」パラメーターセットの場合、次の情報を含むフィールドグループを作成します。
- 使用場所：フィールドグループを使用するジャーニーの数を表示します。 ジャーニーを表示アイコンをクリックし、このフィールドグループを使用するジャーニーのリストを表示できます。
- メソッド：POST または GET メソッドを選択します。 この場合は、GET メソッドを選択します。
- 動的な値：この例では、「long,lat」というコンマで区切られた異なるパラメーターを入力します。 パラメーター値は実行コンテキストに依存するので、ジャーニーで定義されます。 式について詳しく見る
- 応答ペイロード：ペイロードフィールド内でクリックし、呼び出しによって返されたペイロードの例をペーストします。 この例では、天気 API の web サイトにあるペイロードを使用しました。 フィールドタイプが正しいことを確認します。 API が呼び出されるたびに、ペイロードの例に含まれるすべてのフィールドが取得されます。 現在渡されているペイロードを変更する場合、「新しいペイロードをペースト」をクリックします。
- 送信済みペイロード：このフィールドは、この例では表示されません。 POST メソッドを選択した場合にのみ使用できます。 サードパーティシステムに送信されるペイロードをペーストします。
GET 呼び出しにパラメーターが必要な場合は、「 動的な値」フィールドにパラメーターを入力すると、呼び出しの最後に自動的に追加されます。 POST 呼び出しの場合は、次の操作が必要です。
- 呼び出し時に渡すパラメーターを「動的な値」フィールドにリストします（以下の例では「identifier」）。
- また、送信済みペイロードの本文で同じ構文を使用して指定します。 そのためには、「“param”: “パラメーター名”」（以下の例では「identifier」）を追加する必要があります。 次の構文に従います。
{"id":{"param":"identifier"}}
動的な値と応答ペイロード フィールドを含む
変更を保存すると、データソースが設定され、ジャーニーで使用できる状態になります。これで、状況に応じて、メールをパーソナライズできます。 温度が 30°C を超える場合、特定のコミュニケーションを送信するようにできます。
カスタム認証モード custom-authentication-mode
カスタム認証モードは、複雑な認証に使用され、OAuth2 などの API ラッピングプロトコルの呼び出しに頻繁に使用されます。これにより、アクションの実際の HTTP リクエストに挿入するアクセストークンが取得されます。
カスタム認証を設定する場合は、「クリックして認証を確認」ボタンを使用して、カスタム認証ペイロードが正しく設定されているかどうかを制御します。
テストに成功すると、ボタンが緑色に変わります。
この認証モードでは、アクションの実行は次の 2 つの手順で構成されます。
- エンドポイントを呼び出して、アクセストークンを生成します。
- アクセストークンを適切な方法で挿入して、REST API を呼び出します。
アクセストークンの生成時に呼び出されるエンドポイントの定義 custom-authentication-endpoint
-
endpoint：エンドポイントの生成に使用する URL -
エンドポイントでの HTTP リクエストのメソッド（
GETまたはPOST） -
headers：必要に応じて、この呼び出しにヘッダーとして挿入されるキーと値のペア -
body：メソッドが POST の場合の呼び出しの本文を説明します。 bodyParams（キーと値のペア）で定義された限定的な本文構造をサポートしています。 bodyType は、呼び出しでの本文の形式とエンコーディングを記述します。form：コンテンツタイプが application/x-www-form-urlencoded（文字セット UTF-8）で、キーと値のペアが key1=value1&key2=value2&… のようにシリアル化されることを意味します。json：コンテンツタイプが application/json（文字セット UTF-8）で、キーと値のペアが JSON オブジェクトとして { “key1”: “value1”, “key2”: “value2”, …} のようにシリアル化されることを意味します。
アクションの HTTP リクエストにアクセストークンを挿入する方法の定義 custom-authentication-access-token
-
authorizationType：生成されたアクセストークンをアクションの HTTP 呼び出しに挿入する方法を定義します。 使用可能な値は次のとおりです。
bearer：Authorization: Bearer <access token> のように、アクセストークンを Authorization ヘッダーに挿入する必要があることを示します。header：プロパティtokenTargetで定義されたヘッダー名のヘッダーとして、アクセストークンを挿入する必要があることを示します。 例えば、tokenTargetがmyHeaderの場合、アクセストークンは myHeader: <access token> のようにヘッダーとして挿入されます。queryParam：プロパティ tokenTarget で定義されたクエリパラメーター名である queryParam として、アクセストークンを挿入する必要があることを示します。 例えば、tokenTarget が myQueryParam の場合、アクション呼び出しの URL は <url>?myQueryParam=<access token> のようになります。
-
tokenInResponse：認証呼び出しからアクセストークンを抽出する方法を示します。 このプロパティには次のようなものがあります。
response：HTTP 応答がアクセストークンであることを示します。- JSON 内のセレクター（応答が JSON であると仮定し、XML などの他の形式はサポートされません）。 このセレクターの形式は json://<path to the access token property> です。 例えば、呼び出しの応答が { "access token": “theToken”, “timestamp”: 12323445656 }の場合、tokenInResponse は json: //access_token_ のようになります。
この認証の形式は次のとおりです。
{
"type": "customAuthorization",
"endpoint": "<URL of the authentication endpoint>",
"method": "<HTTP method to call the authentication endpoint, in 'GET' or 'POST'>",
(optional) "headers": {
"<header name>": "<header value>",
...
},
(optional, mandatory if method is 'POST') "body": {
"bodyType": "<'form'or 'json'>,
"bodyParams": {
"param1": value1,
...
}
},
"tokenInResponse": "<'response' or json selector in format 'json://<field path to access token>'",
"cacheDuration": {
(optional, mutually exclusive with 'duration') "expiryInResponse": "<json selector in format 'json://<field path to expiry>'",
(optional, mutually exclusive with 'expiryInResponse') "duration": <integer value>,
"timeUnit": "<unit in 'milliseconds', 'seconds', 'minutes', 'hours', 'days', 'months', 'years'>"
},
"authorizationType": "<value in 'bearer', 'header' or 'queryParam'>",
(optional, mandatory if authorizationType is 'header' or 'queryParam') "tokenTarget": "<name of the header or queryParam if the authorizationType is 'header' or 'queryParam'>",
}
カスタム認証データソース用のトークンのキャッシュ時間を変更できます。 次に、カスタム認証ペイロードの例を示します。 キャッシュ時間は、cacheDuration パラメーターで定義されます。 キャッシュ内の生成されたトークンの保持期間を指定します。 単位はミリ秒、秒、分、時間、日、月、年です。
Bearer 認証タイプの例を次に示します。
{
"type": "customAuthorization",
"endpoint": "https://<your_auth_endpoint>/epsilon/oauth2/access_token",
"method": "POST",
"headers": {
"Authorization": "Basic EncodeBase64(<epsilon Client Id>:<epsilon Client Secret>)"
},
"body": {
"bodyType": "form",
"bodyParams": {
"scope": "cn mail givenname uid employeeNumber",
"grant_type": "password",
"username": "<epsilon User Name>",
"password": "<epsilon User Password>"
}
},
"tokenInResponse": "json://access_token",
"cacheDuration": {
"duration": 5,
"timeUnit": "minutes"
},
},
-
認証トークンはジャーニーごとにキャッシュされます。2つのジャーニーが同じカスタムアクションを使用している場合、各ジャーニーには独自のトークンがキャッシュされます。 そのトークンは、これらのジャーニー間で共有されません。
-
キャッシュ時間を使用すると、認証エンドポイントへの呼び出しが多くなりすぎないようにすることができます。 認証トークンの保持はサービスにキャッシュされ、永続性はありません。 サービスを再起動した場合は、キャッシュがクリーンアップされた状態でサービスが開始されます。 デフォルトのキャッシュ時間は 1 時間です。 カスタム認証ペイロードでは、別の保持時間を指定することで調整することができます。
証明書ベースのカスタム認証 certificate-credential
Microsoft Entra IDなど、証明書ベースのID確認を強制するエンタープライズ APIの場合、カスタム認証ペイロードに"subType": "certificateCredential"を追加することで、証明書ベースのカスタム認証を設定できます。 Journey Optimizerは、Adobeのマネージド証明書を使用してJWT クライアントアサーションに署名し、アクセストークンと交換します。 クライアントシークレットは必要ありません。
このオプションは、標準customAuthorization スキーマに2つの必須フィールド subTypeとaudを追加します。 その他のすべてのフィールド （endpoint、method、本文パラメーター、tokenInResponse）は変更されません。 subTypeが存在しない場合、動作は標準のカスタム認証と同じです。既存の設定は影響を受けません。
subType：証明書ベースの認証を有効にするには、"certificateCredential"に設定します。aud: JWT クライアントアサーションに含まれるオーディエンス値。 Microsoft Entra IDの場合、これはendpointURLと同じですが、常に明示的に設定する必要があります。
client_assertionおよびclient_assertion_type フィールドは、ユーザーが作成したことはありません。 これらは、トークンエンドポイント呼び出しの直前に、実行時にプラットフォームによって自動的に挿入されます。
仕組み certificate-credential-how-it-works
証明書ベースのカスタム認証は、RFC 7523で定義されているように、JWT クライアントアサーションを使用してOAuth 2.0 クライアント資格情報を実装します。これは、Microsoft Entra IDとOktaでサポートされているのと同じ標準です。 Journey Optimizerは、クライアントの秘密鍵の代わりに、Adobeのマネージド秘密鍵で署名されたJWTを使用してIDを証明します。 ID プロバイダーは、ID プロバイダーに一度登録したAdobeの公開証明書を使用して署名を検証します。
トークン交換は次の手順に従います。
- Journey Optimizerは、Adobeの秘密鍵で署名されたJWT クライアントアサーションを構築します。
- アサーションは、
client_id、grant_type、scopeと共にトークンエンドポイントに送信されます。 - ID プロバイダーは、Adobeの登録済み公開証明書に対してJWT署名を検証します。
- ID プロバイダーがベアラートークンを返します。
- Journey Optimizerはそのトークンを使用して、カスタムアクションエンドポイントを呼び出します。
Adobe証明書の詳細 certificate-credential-details
Adobeは、証明書とその関連する秘密鍵を管理します。 次の表に、主なプロパティの概要を示します。
expiryDateを確認し、古い証明書が失効する前にIDPを再設定してください。Adobeは、有効期限の60日前に証明書を自動的にローテーションします。 以前の証明書は、有効期限の30日前まで有効です。 お客様には現在は通知されていません。プログラムでローテーションを監視する方法については、以下の証明書のローテーション ガードレール を参照してください。
JWT アサーション構造 certificate-credential-jwt
JWT クライアントアサーションは作成しません。Journey Optimizerが生成し、署名します。 ここに、ID プロバイダーチームが要求を検証できるように、想定される構造が提供されます。
ヘッダー：
{
"alg": "RS256",
"x5t": "<base64url SHA-1 thumbprint of Adobe's leaf certificate>"
}
ペイロード：
{
"iss": "<client_id>",
"sub": "<client_id>",
"aud": "<token endpoint URL>",
"iat": "<current unix timestamp>",
"exp": "<iat + 600 seconds>",
"jti": "<unique UUID per request>"
}
次のことに注意してください。
exp−iatは、OktaとEntra IDの要件と一致して、常に10分≤で完了します。- 各アサーションは一意の
jtiを使用するため、リプレイ攻撃を安全に行うことができます。 client_assertionとclient_assertion_typeはプラットフォームによって自動的に挿入され、作成されることはありません。
Microsoft Entra IDの証明書資格情報認証タイプの例を次に示します。
{
"type": "customAuthorization",
"subType": "certificateCredential",
"aud": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
"authorizationType": "Bearer",
"endpoint": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
"method": "POST",
"body": {
"bodyType": "form",
"bodyParams": {
"client_id": "<your-client-id>",
"grant_type": "client_credentials",
"scope": "https://api.example.com/.default"
}
},
"tokenInResponse": "json://access_token"
}
Oktaの同じ証明書資格情報認証タイプの例を次に示します。
{
"type": "customAuthorization",
"subType": "certificateCredential",
"authorizationType": "bearer",
"endpoint": "https://<your-okta-domain>/oauth2/v1/token",
"aud": "https://<your-okta-domain>/oauth2/v1/token",
"method": "POST",
"body": {
"bodyType": "form",
"bodyParams": {
"client_id": "<your-okta-app-client-id>",
"grant_type": "client_credentials",
"scope": "<your-api-scope>"
}
},
"tokenInResponse": "json://access_token"
}
- トークンエンドポイント URL: HTTPSである必要があります。
?を含むURLを避けます。これは、認証エンドポイントがトークンエンドポイントの代わりに貼り付けられたサインです。 method:POSTでなければなりません。 OAuth トークンエンドポイントは、POST リクエストのみを受け入れます。client_id：空白にしないでください。先頭または末尾に空白を含めないでください。 空白の値を指定すると、ID プロバイダーが不透明なエラーで拒否する有効な外観のJWTが生成されます。scope:bodyParamsでスペース区切りの単一の文字列として表されます。 合計1000文字以内。- 証明書: Adobeは証明書と秘密鍵を管理します。証明書をアップロードしたり入力したりすることはありません。 ライブジャーニーでカスタムアクションを使用する前に、ID プロバイダーに Adobeのリーフ証明書 を登録する必要があります。 取得するには、mTLS公開証明書APIを呼び出し、
certCommonNameがajo-journeys.aep-mtls.adobe.comのエントリを探します。 そのエントリからpublicCertificate値を登録します。中間またはルート CA証明書は使用しないでください。 現在、証明書のローテーションが通知されていないため、古い証明書が失効する30日前にIDPで登録済み証明書を更新する前に、mTLS公開証明書APIを定期的に呼び出してexpiryDateを確認し、IDPで登録済み証明書を更新する必要があります。
ヘッダー認証タイプの例を次に示します。
{
"type": "customAuthorization",
"endpoint": "https://myapidomain.com/v2/user/login",
"method": "POST",
"headers": {
"x-retailer": "any value"
},
"body": {
"bodyType": "form",
"bodyParams": {
"secret": "any value",
"username": "any value"
}
},
"tokenInResponse": "json://token",
"cacheDuration": {
"expiryInResponse": "json://expiryDuration",
"timeUnit": "minutes"
},
"authorizationType": "header",
"tokenTarget": "x-auth-token"
}
ログイン API 呼び出しの応答の例を次に示します。
{
"token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S",
"expiryDuration" : 5
}
bodyParams 内のサブオブジェクト）が サポート されます。