Experience Platform API の認証とアクセス

このドキュメントでは、Experience PlatformAPI を呼び出すためにAdobe Experience Platform開発者アカウントにアクセスする、順を追ったチュートリアルを提供します。 このチュートリアルの最後では、すべての Platform API 呼び出しのヘッダーとして必要な、次の資格情報を生成または収集します。

  • {ACCESS_TOKEN}
  • {API_KEY}
  • {ORG_ID}
TIP
上記の 3 つの資格情報に加えて、多くの Platform API では、有効な {SANDBOX_NAME} をヘッダーとして指定する必要もあります。 サンドボックスについて詳しくは、 サンドボックスの概要を参照してください。また、組織で使用可能なサンドボックスの一覧表示について詳しくは、 サンドボックス管理エンドポイントのドキュメントを参照してください。

アプリケーションとユーザーのセキュリティを維持するには、Experience PlatformAPI へのすべてのリクエストが、OAuth などの標準を使用して認証および承認される必要があります。

このチュートリアルでは、以下のフローチャートに示すように、Platform API 呼び出しの認証に必要な資格情報の収集方法を説明します。 必要な資格情報のほとんどは、1 回限りの初期設定で収集できます。 ただし、アクセストークンは 24 時間ごとに更新する必要があります。

前提条件 prerequisites

Experience PlatformAPI を正常に呼び出すには、次の条件を満たす必要があります。

  • Adobe Experience Platformへのアクセス権を持つ組織。
  • Admin Consoleおよび製品プロファイルのユーザーとして追加できる開発管理者。
  • Experience Platformシステム管理者。API を使用してExperience Platformの様々な部分で読み取りまたは書き込み操作を実行するために必要な、属性ベースのアクセス制御をユーザーに付与できます。

このチュートリアルを完了するには、Adobe IDも必要です。 Adobe ID をお持ちでない場合は、次の手順で作成できます。

  1. Adobe Developer Console に移動します。
  2. 新しいアカウントを作成 を選択します。
  3. 新規登録プロセスを完了します。

Experience Platformのための開発者およびユーザーのアクセス権の取得 gain-developer-user-access

Adobe Developer Consoleで統合を作成する前に、アカウントがAdobe Admin ConsoleのExperience Platform製品プロファイルの開発者権限とユーザー権限を持っている必要があります。

開発者アクセス権の取得 gain-developer-access

Experience Platform Admin Console を使用して開発者向け製品プロファイルに自分を追加する場合は、組織内の Admin Console 管理者にお問い合わせください。 製品プロファイルの開発者アクセスの管理の方法について詳しくは、Admin Console のドキュメントを参照してください。

開発者として割り当てられたら、Adobe Developer Console で統合の作成を開始できます。 これらの統合は、外部のアプリやサービスからAdobeAPI へのパイプラインです。

ユーザーアクセスの取得 gain-user-access

また、Admin Console 管理者も、同じ製品プロファイルにユーザーとして追加する必要があります。 ユーザーアクセスを使用すると、実行する API 操作の結果を UI で確認できます。

詳しくは、 でのユーザーグループの管理 Admin Console のガイドを参照してください。

API キー(クライアント ID)と組織 ID の生成 generate-credentials

NOTE
Privacy ServiceAPI ガイドのこのドキュメントを読む場合は、ガイドに戻って、Privacy Service に固有のアクセス認証情報を生成することができます。

Admin Console を通じて開発者およびユーザーに Platform へのアクセス権を付与したら、次の手順は、Adobe Developer Consoleで {ORG_ID}{API_KEY} の資格情報を生成することです。 これらの資格情報は 1 回だけ生成する必要があり、今後の Platform API 呼び出しで再利用できます。

プロジェクトにExperience Platformを追加する add-platform-to-project

Adobe Developer Console に移動し 、Adobe ID を使用してログインします。次に、Adobe Developer Console のドキュメントの空のプロジェクトの作成チュートリアルで概説されている手順に従います。

新しいプロジェクトを作成したら、プロジェクトの概要 画面で API を追加 を選択します。

TIP
複数の組織用にプロビジョニングされている場合は、インターフェイスの右上隅にある組織セレクターを使用して、必要な組織に属していることを確認します。

「API を追加」オプションがハイライト表示されたDeveloper Console画面

API の追加 ​画面が表示されます。 Adobe Experience Platformの製品アイコンを選択し、「Experience PlatformAPI」を選択してから「次へ」を選択します。

Experience PlatformAPI を選択します

TIP
ドキュメントを表示 オプションを選択して、別のブラウザーウィンドウに移動し、Experience PlatformAPI リファレンスドキュメントを参照します。

OAuth サーバー間 ​ 認証タイプを選択します select-oauth-server-to-server

次に、「OAuth サーバー間 ​ 認証タイプ」を選択してアクセストークンを生成し、Experience PlatformAPI にアクセスします。

IMPORTANT
今後サポートされるトークン生成方法は、OAuth サーバー間 メソッドのみです。 以前サポートされていた サービスアカウント(JWT) メソッドは非推奨となり、新しい統合用に選択することはできません。 JWT 認証方法を使用した既存の統合は 2025 年 1 月 1 日(PT)まで引き続き機能しますが、Adobeでは、その日までに既存の統合を新しい OAuth サーバー間認証方法 ​ に移行することを強くお勧めします。 詳しくは、「[​ 非推奨 ​]{class="badge informative"}」の節を参照してください。{type=negative}JSON web トークン(JWT)を生成ます。

認証 API の OAuth サーバー間Experience Platform方式を選択します。

統合用の製品プロファイルの選択 select-product-profiles

API の設定 画面で、「AEP-Default-All-Users」を選択します。

IMPORTANT
Platform の特定の機能にアクセスするには、必要な属性ベースのアクセス制御権限を付与するシステム管理者も必要です。 詳しくは、 必要な属性ベースのアクセス制御権限の取得の節を参照してください。

統合用の製品プロファイルを選択します

準備ができたら、「設定済み API を保存」を選択します。

Experience PlatformAPI との統合を設定するための上記の手順は、次のビデオチュートリアルでも参照できます。

資格情報の収集 gather-credentials

API がプロジェクトに追加されると、プロジェクトの Experience PlatformAPI ページに、Experience PlatformAPI へのすべての呼び出しで必要な次の資格情報が表示されます。

Developer Console で API を追加した後の統合情報

  • {API_KEY} (​ クライアント ID)
  • {ORG_ID} (​ 組織 ID)

アクセストークンの生成 generate-access-token

次の手順では、Platform API 呼び出しで使用する {ACCESS_TOKEN} 資格情報を生成します。 {API_KEY}{ORG_ID} の値とは異なり、Platform API を引き続き使用するには、新しいトークンを 24 時間ごとに生成する必要があります。 「アクセストークンを生成」を選択します(下図を参照)。

アクセストークンの生成方法を表示

TIP
また、Postman環境とコレクションを使用してアクセストークンを生成することもできます。 詳しくは、Postmanを使用した API 呼び出しの認証とテストに関する節を参照してください。

[​ 非推奨 ​]{class="badge negative"} JSON web トークン(JWT)を生成 jwt

WARNING
アクセストークンを生成する JWT メソッドは非推奨(廃止予定)になりました。 すべての新しい統合は、OAuth サーバー間認証方法を使用して作成する必要があります。 また、Adobeを引き続き機能させるには、2025 年 1 月 1 日(PT)までに既存の統合環境を OAuth 方式に移行する必要があります。 以下の重要なドキュメントをお読みください。
非推奨(廃止予定)の情報の表示

次の手順では、アカウントの資格情報に基づいて JSON web トークン(JWT)を生成します。 この値は、Platform API 呼び出しで使用する {ACCESS_TOKEN} 認証情報を生成するために使用され、24 時間ごとに再生成する必要があります。

note important
IMPORTANT
このチュートリアルを目的として、次の手順ではDeveloper Console内で JWT を生成する方法の概要を説明します。 ただし、この生成方法は、テストおよび評価の目的でのみ使用してください。
通常の使用では、JWT を自動的に生成する必要があります。 プログラムによる JWT の生成方法について詳しくは、Adobe Developerの サービスアカウント認証ガイドを参照してください。

左側のナビゲーションで「サービスアカウント (JWT)」を選択し、「JWT を生成」を選択します。

カスタム JWT を生成」の下にあるテキストボックスに、Platform API をサービスアカウントに追加する際に以前に生成した秘密鍵の内容を貼り付けます。 次に、「トークンを生成」を選択します。

ページが更新され、生成された JWT と、アクセストークンを生成できるサンプル cURL コマンドが表示されます。 このチュートリアルでは、「生成された JWT」の横にある「コピー を選択して、トークンをクリップボードにコピーします。

アクセストークンの生成

JWT を生成したら、API 呼び出しで JWT を使用して {ACCESS_TOKEN} を生成できます。 {API_KEY}{ORG_ID} の値とは異なり、Platform API を引き続き使用するには、新しいトークンを 24 時間ごとに生成する必要があります。

リクエスト

次のリクエストは、ペイロードで指定された資格情報に基づいて新しい {ACCESS_TOKEN} を生成します。 このエンドポイントは、フォームデータのみをペイロードとして受け入れるので、multipart/form-dataContent-Type ヘッダーを指定する必要があります。

code language-shell
curl -X POST https://ims-na1.adobelogin.com/ims/exchange/jwt \
  -H 'Content-Type: multipart/form-data' \
  -F 'client_id={API_KEY}' \
  -F 'client_secret={SECRET}' \
  -F 'jwt_token={JWT}'
table 0-row-2 1-row-2 2-row-2 3-row-2
プロパティ 説明
{API_KEY} [ 前の手順 ] で取得した {API_KEY} ール(​ クライアント ID
{SECRET} 前の手順で取得したクライアント秘密鍵。
{JWT} 前の手順で生成した JWT。
note note
NOTE
同じ API キー、クライアントの秘密鍵、JWT を使用して、セッションごとに新しいアクセストークンを生成できます。 これにより、アプリケーションでのアクセストークンの生成を自動化できます。

応答

code language-json
{
  "token_type": "bearer",
  "access_token": "{ACCESS_TOKEN}",
  "expires_in": 86399992
}
table 0-row-2 1-row-2 2-row-2 3-row-2
プロパティ 説明
token_type タイプ of 返されるトークン。 アクセストークンの場合、この値は常に bearer です。
access_token 生成された {ACCESS_TOKEN}。 この値(先頭に Bearer という単語が付く)は、すべての Platform API 呼び出しの Authentication ヘッダーとして必要です。
expires_in アクセストークンの有効期限が切れるまでの残り時間(ミリ秒)。 この値が 0 に達したら、Platform API の使用を続行するために、新しいアクセストークンを生成する必要があります。

アクセス資格情報のテスト test-credentials

アクセストークン、API キー、組織 ID の 3 つの必要な資格情報をすべて収集したら、次の API 呼び出しを行うことができます。 この呼び出しでは、組織で使用可能なすべての標準 Experience Data Model (XDM)クラスを一覧表示します。 Postman に呼び出しを読み込んで実行します。

recommendation-more-help

リクエスト

curl -X GET https://platform.adobe.io/data/foundation/schemaregistry/global/classes \
  -H 'Accept: application/vnd.adobe.xed-id+json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'x-api-key: {{API_KEY}}' \
  -H 'x-gw-ims-org-id: {{ORG_ID}}'

応答

応答が以下に示すものに類似している場合、資格情報は有効であり、機能します。 (スペース節約のために応答は部分的に表示されています。)

{
  "results": [
    {
        "title": "XDM ExperienceEvent",
        "$id": "https://ns.adobe.com/xdm/context/experienceevent",
        "meta:altId": "_xdm.context.experienceevent",
        "version": "1"
    },
    {
        "title": "XDM Individual Profile",
        "$id": "https://ns.adobe.com/xdm/context/profile",
        "meta:altId": "_xdm.context.profile",
        "version": "1"
    }
  ]
}
IMPORTANT
上記の呼び出しはアクセス資格情報をテストするには十分ですが、属性ベースの適切なアクセス制御権限がないと、複数のリソースにアクセスして変更することができません。 詳しくは、以下の 必要な属性ベースのアクセス制御権限の取得 節を参照してください。

必要な属性ベースのアクセス制御権限の取得 get-abac-permissions

Experience Platform内の複数のリソースにアクセスしたり、変更したりするには、適切なアクセス制御権限が必要です。 システム管理者から 必要な権限を付与できます。 詳しくは、「役割の API 資格情報の管理 に関する節を参照しください。

システム管理者が API を使用して Platform リソースへのアクセスに必要な権限を付与する方法について詳しくは、以下のビデオチュートリアルも参照してください。

Postmanを使用した API 呼び出しの認証とテスト use-postman

Postman は、開発者が RESTful API を参照およびテストできる一般的なツールです。 Experience PlatformのPostman コレクションおよび環境を使用して、Experience PlatformAPI の作業を高速化できます。 詳しくは、 環境でのPostmanの使用およびコレクションとExperience Platformの基本を学ぶを参照してください。

Experience Platformコレクションおよび環境でのPostmanの使用について詳しくは、以下のビデオチュートリアルも参照してください。

Experience PlatformAPI で使用するPostman環境のダウンロードと読み込み

Postman コレクションを使用してアクセストークンを生成する

Identity Management サービス Postman コレクションをダウンロードし以下のビデオを視聴してアクセストークンの生成方法を確認してください。

Experience PlatformAPI Postman コレクションをダウンロードして API とやり取りする

システム管理者:Experience Platform権限を使用して開発者と API のアクセス制御を付与します grant-developer-and-api-access-control

NOTE
システム管理者のみが、権限の API 資格情報を表示および管理できます。

Adobe Developer Consoleで統合を作成する前に、アカウントがAdobe Admin ConsoleのExperience Platform製品プロファイルの開発者権限とユーザー権限を持っている必要があります。

製品プロファイルへの開発者の追加 add-developers-to-product-profile

Admin Console に移動し、Adobe IDでログインします。

商品 を選択して、商品のリストから 2}Adobe Experience Platform} を選択します。

Admin Consoleに掲載されている製品リスト

製品プロファイル」タブで、「AEP-Default-All-Users」を選択します。 または、検索バーを使用して名前を入力して製品プロファイルを検索します。

製品プロファイルの検索

開発者」タブを選択し、「開発者を追加」を選択します。

「開発者」タブから開発者を追加

開発者の メールまたはユーザー名 を入力します。 有効な ​ メールまたはユーザー名 ​ には、開発者の詳細が表示されます。 「保存」を選択します。

メールまたはユーザー名を使用して開発者を追加する

開発者が正常に追加され、「​ 開発者 ​」タブに表示されます。

「開発者」タブに開発者が表示されます

API を役割に割り当てる

システム管理者は、Experience PlatformUI で API をロールに割り当てることができます。

権限 と、API を追加する役割を選択します。 「API 資格情報」タブを選択し、「API 資格情報を追加」を選択します。

選択した役割の「API 資格情報」タブ

役割に追加する API を選択して、「保存」を選択します。

選択可能な API のリスト

「API 資格情報 ​」タブに戻り、新しく追加された API が一覧表示されます。

新しく追加された API が表示された「API 資格情報」タブ

その他のリソース additional-resources

Experience PlatformAPI の概要の詳細については、以下にリンクされているその他のリソースを参照してください

次の手順 next-steps

このドキュメントでは、Platform API のアクセス資格情報を収集し、正常にテストしました。 ドキュメント全体を通して提供される API 呼び出しの例に従うことができるようになりました。

このチュートリアルで収集した認証値に加えて、多くの Platform API では、有効な {SANDBOX_NAME} をヘッダーとして指定する必要もあります。 詳しくは、サンドボックスの概要を参照してください。

5741548a-2e07-44b3-9157-9c181502d0c5