Experience Platform API の認証とアクセス
このドキュメントでは、Experience PlatformAPI を呼び出すためにAdobe Experience Platform開発者アカウントにアクセスする、順を追ったチュートリアルを提供します。 このチュートリアルの最後では、すべての Platform API 呼び出しのヘッダーとして必要な、次の資格情報を生成または収集します。
{ACCESS_TOKEN}
{API_KEY}
{ORG_ID}
{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 をお持ちでない場合は、次の手順で作成できます。
- Adobe Developer Console に移動します。
- 新しいアカウントを作成 を選択します。
- 新規登録プロセスを完了します。
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
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 を追加 を選択します。
API の追加 画面が表示されます。 Adobe Experience Platformの製品アイコンを選択し、「Experience PlatformAPI」を選択してから「次へ」を選択します。
。
OAuth サーバー間 認証タイプを選択します select-oauth-server-to-server
次に、「OAuth サーバー間 認証タイプ」を選択してアクセストークンを生成し、Experience PlatformAPI にアクセスします。
統合用の製品プロファイルの選択 select-product-profiles
API の設定 画面で、「AEP-Default-All-Users」を選択します。
。
準備ができたら、「設定済み API を保存」を選択します。
Experience PlatformAPI との統合を設定するための上記の手順は、次のビデオチュートリアルでも参照できます。
資格情報の収集 gather-credentials
API がプロジェクトに追加されると、プロジェクトの Experience PlatformAPI ページに、Experience PlatformAPI へのすべての呼び出しで必要な次の資格情報が表示されます。
{API_KEY}
( クライアント ID){ORG_ID}
( 組織 ID)
アクセストークンの生成 generate-access-token
次の手順では、Platform API 呼び出しで使用する {ACCESS_TOKEN}
資格情報を生成します。 {API_KEY}
と {ORG_ID}
の値とは異なり、Platform API を引き続き使用するには、新しいトークンを 24 時間ごとに生成する必要があります。 「アクセストークンを生成」を選択します(下図を参照)。
[ 非推奨 ]{class="badge negative"} JSON web トークン(JWT)を生成 jwt
次の手順では、アカウントの資格情報に基づいて 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-data
の Content-Type
ヘッダーを指定する必要があります。
code language-shell |
---|
|
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 |
---|
|
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 に呼び出しを読み込んで実行します。
リクエスト
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"
}
]
}
必要な属性ベースのアクセス制御権限の取得 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
Adobe Developer Consoleで統合を作成する前に、アカウントがAdobe Admin ConsoleのExperience Platform製品プロファイルの開発者権限とユーザー権限を持っている必要があります。
製品プロファイルへの開発者の追加 add-developers-to-product-profile
Admin Console に移動し、Adobe IDでログインします。
商品 を選択して、商品のリストから 2}Adobe Experience Platform} を選択します。
「製品プロファイル」タブで、「AEP-Default-All-Users」を選択します。 または、検索バーを使用して名前を入力して製品プロファイルを検索します。
「開発者」タブを選択し、「開発者を追加」を選択します。
開発者の メールまたはユーザー名 を入力します。 有効な メールまたはユーザー名 には、開発者の詳細が表示されます。 「保存」を選択します。
開発者が正常に追加され、「 開発者 」タブに表示されます。
API を役割に割り当てる
システム管理者は、Experience PlatformUI で API をロールに割り当てることができます。
権限 と、API を追加する役割を選択します。 「API 資格情報」タブを選択し、「API 資格情報を追加」を選択します。
役割に追加する API を選択して、「保存」を選択します。
「API 資格情報 」タブに戻り、新しく追加された API が一覧表示されます。
その他のリソース additional-resources
Experience PlatformAPI の概要の詳細については、以下にリンクされているその他のリソースを参照してください
- Experience PlatformAPI の認証とアクセスビデオチュートリアルページ
- アクセストークンを生成するための Identity Management サービス Postman コレクション
- Experience PlatformAPI Postman コレクション
次の手順 next-steps
このドキュメントでは、Platform API のアクセス資格情報を収集し、正常にテストしました。 ドキュメント全体を通して提供される API 呼び出しの例に従うことができるようになりました。
このチュートリアルで収集した認証値に加えて、多くの Platform API では、有効な {SANDBOX_NAME}
をヘッダーとして指定する必要もあります。 詳しくは、サンドボックスの概要を参照してください。