一般的な要件、認証、オプションのクエリパラメーター、リクエスト URLs およびその他の参考資料についての情報です。
Audience Manager API を使用する際に留意すべき事項の説明です。
Audience Manager API コードを操作する場合は、以下の点に注意してください。
x-api-key
ヘッダーを指定する必要があります。API キーは、サービスアカウント統合ページの手順に従って取得できます。content-type: application/json
および accept: application/json
を指定してください。Audience Manager REST APIs では、2 とおりの認証方法をサポートしています。
認証方法に応じて、リクエスト URLs を調整する必要があります。使用すべきホスト名について詳しくは、環境の節を参照してください。
Adobe Developer は、アドビの開発者エコシステムおよびコミュニティです。これにはすべてのアドビ製品の API が含まれます。
Adobe APIs を設定および使用する場合は、この方法をお勧めします。
JWT 認証を設定する前に、Adobe Developer で Adobe Developer Console にアクセスできることを確認します。アクセスリクエストについては、組織の管理者にお問い合わせください。
次の手順に従って、Adobe Developer を使用して JWT (Service Account) 認証を設定します。
Audience Manager REST APIs を自動的に設定および操作するため、プログラムによって JWT を生成できます。詳しい手順については、JWT(サービスアカウント)認証を参照してください。
Audience Manager アカウントで役割ベースのアクセス制御を使用する場合は、Audience Manager のテクニカルユーザーアカウントを作成し、API 呼び出しをおこなう Audience Manager の RBAC グループに追加する必要があります。
以下の手順に従って、テクニカルユーザーアカウントを作成し、RBAC グループに追加します。
https://aam.adobe.io/v1/users/self
に対して GET
呼び出しを実行します。この呼び出しにより、Admin Console の Users ページに表示されるテクニカルユーザーアカウントが作成されます。
Audience Manager アカウントにログインし、API 呼び出しをおこなうユーザーグループにテクニカルユーザーアカウントを追加します。
Audience Manager REST API トークン認証および OAuth 2.0 を使用した更新は、非推奨(廃止予定)となりました。
代わりに、JWT(サービスアカウント)認証を使用してください。
Audience Manager REST API では、OAuth 2.0 標準規格に従って、トークンの認証と更新をおこないます。以下のセクションでは、API を認証し、使用を開始する方法について説明します。
Audience Manager APIを使用するための個別の技術的なユーザーアカウントを作成することをお勧めします。これは、組織の特定ユーザーに関連していない、または関連付けられていない一般的なアカウントです。このような API ユーザーアカウントによって 2 つのことが可能になります。
このようなアカウントのユースケースとして、一括管理ツールを参照してください。これをおこなうためには、ユーザーアカウントに API へのアクセス権が付与されている必要があります。特定のユーザーに対して権限を追加するのではなく、適切な資格情報、キー、および API 呼び出し用の暗号鍵を持つ汎用の API ユーザーアカウントを作成します。これは、Audience Manager API を使用する独自のアプリケーションを開発する場合にも便利です。
担当の Audience Manager コンサルタントにご相談のうえ、API 専用のユーザーアカウントの設定をおこなってください。
パスワード認証により、 REST API へのアクセスが保護されます。以下の手順は、ブラウザーで JSON クライアントからパスワードを認証する際のワークフローの概要を示しています。
更新トークンをデータベースに保存する場合は、アクセスと更新トークンを暗号化します。
パートナーソリューションソリューションに問い合わせます。API クライアント ID と暗号鍵が通知されます。この ID と暗号鍵により、API での認証をおこないます。
注意:更新トークンを受け取る場合は、API アクセスをリクエストする際にその旨を申告してください。
JSON クライアントでトークンのリクエストを渡します。リクエストをおこなうには、次の手順に従います。
POST
メソッドを使用して https://api.demdex.com/oauth/token
を呼び出します。testId : testSecret
は dGVzdElkOnRlc3RTZWNyZXQ=
に変換されます。Authorization:Basic <base-64 clientID:clientSecret>
および Content-Type: application/x-www-form-urlencoded
で渡します。ヘッダーの例を次に示します。Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=<your-AudienceManager-user-name>&password=<your-AudienceManager-password>
JSON応答にはアクセストークンが含まれています。応答は次のようになっています。
{
"access_token": "28fed402-eafd-456c-9341-ac753f25bbbc",
"token_type": "bearer",
"refresh_token": "b27122c0-b0c7-4b39-a71b-1547a3b3b88e",
"expires_in": 21922,
"scope": "read write"
}
expires_in
キーは、アクセストークンの有効期間を秒単位で表しています。トークンが公開される場合、ベストプラクティスとして、有効期間を短く設定し、公開時間を制限します。
更新トークンは、元のトークンの有効期間が終了した後、API アクセスを更新します。リクエストがあれば、パスワードワークフローの応答 JSON に更新トークンが含まれます。更新トークンを受け取らない場合、パスワード認証プロセスにより新しいトークンを作成します。
また、更新トークンを使用して、既存のアクセストークンの有効期間が終了する前に新しいトークンを作成することもできます。
アクセストークンの有効期間が終了している場合、401 Status Code
が生成され、応答のヘッダーが次のようになります。
WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"
次の表は、更新トークンを使用してブラウザーの JSON クライアントから新しいアクセストークンを作成するワークフローを示しています。
優先 JSON クライアントで更新トークンのリクエストを渡します。リクエストをおこなうには、次の手順に従います。
POST
メソッドを使用して https://api.demdex.com/oauth/token
を呼び出します。testId : testSecret
は dGVzdElkOnRlc3RTZWNyZXQ=
に変換されます。Authorization:Basic <base-64 clientID:clientSecret>
と Content-Type: application/x-www-form-urlencoded
を渡します。ヘッダーの例を次に示します。Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
grant_type:refresh_token
を指定し、前のアクセスリクエストで受け取った更新トークンを渡します。リクエストは次のようになっています。grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e
JSON 応答に新しいアクセストークンが含まれます。応答は次のようになっています。
{
"access_token": "4fdfc261-2ffc-4fb7-8dbd-64221714c45f",
"token_type": "bearer",
"refresh_token": "295fa487-1825-4caa-a715-80b81ac17dae",
"expires_in": 21922,
"scope": "read write"
}
Audience Manager は、認証コードを暗黙的な認証をサポートしています。REST APIこれらのアクセス方法を利用するには、ユーザーが https://api.demdex.com/oauth/authorize
にログインし、アクセス権と更新トークンを取得する必要があります。
認証トークン受信後の API メソッドの呼び出しの要件。
使用可能な API メソッドに対する呼び出しをおこなうには:
HTTP
ヘッダーで Authorization: Bearer <token>
を設定します。x-api-key
ヘッダー(client_id
と同じ)を提供する必要があります。client_id
については、Adobe Developer 統合ページから取得できます。オブジェクトのすべてのプロパティを返すメソッドに使用可能なオプションのパラメーターを設定します。
オブジェクトのAPIすべてのプロパティを返す メソッドで、これらのオプションパラメーターを使用できます。そのクエリを API に渡す際に、リクエスト文字列にこれらのオプションを設定します。
パラメーター | 説明 |
---|---|
page |
ページ番号を返します。番号は 0 から始まります。 |
pageSize |
リクエストによって返された応答結果の番号を設定します(10 がデフォルト)。 |
sortBy |
指定された JSON プロパティに従って、結果を並べ替えて返します。 |
descending |
結果を降順で並べ替えて返します。ascending がデフォルトです。 |
search |
検索パラメーターとして使用する指定文字列に基づいて結果を返します。例えば、項目の任意のフィールドに「Test」という語があるすべてのモデルの結果を探したい場合は、サンプルリクエストは次のようになります。 GET https://aam.adobe.io/v1/models/?search=Test 「get all」メソッドで返されるすべての値を検索できます。 |
folderId |
指定されたフォルダー内のtraitsのすべての ID を返します。すべてのメソッドに対して使用できるわけではありません。 |
permissions |
指定された権限に基づいて、セグメントのリストを返します。READ がデフォルトです。権限には以下のものがあります。
複数の権限を個別のキーと値のペアで指定します。例えば、 READ および WRITE 権限だけを持っているセグメントのリストを返すには、"permissions":"READ" 、"permissions":"WRITE" を渡します。 |
includePermissions |
(Boolean)true に設定して、セグメントの権限を返します。初期設定は false です。 |
ページ情報が指定されていない場合、リクエストは、プレーンな JSON 結果を配列で返します。ページ情報が指定されている場合、返されるリストは、合計結果と現在のページに関する情報を含んだ JSON オブジェクトにラッピングされます。ページオプションを使用したサンプルリクエストは次のようになります。
GET https://aam.adobe.io/v1/models/?page=1&pageSize=2&search=Test
リクエストの URLs、ステージング環境および実稼動環境、バージョンの説明です。
次の表は、API リクエストを渡すためのリクエスト URLs のリストを、メソッド別に示しています。
使用する認証方法に応じて、次の表に従ってリクエスト URLs を調整する必要があります。
API メソッド | リクエスト URL |
---|---|
Algorithmic Modeling | https://aam.adobe.io/v1/models/ |
Data Source | https://aam.adobe.io/v1/datasources/ |
Derived Signals | https://aam.adobe.io/v1/signals/derived/ |
Destinations | https://aam.adobe.io/v1/destinations/ |
Domains | https://aam.adobe.io/v1/partner-sites/ |
Folders | 特性:https://aam.adobe.io/v1/folders/traits / セグメント: https://aam.adobe.io/v1/folders/segments / |
Schema | https://aam.adobe.io/v1/schemas/ |
Segments | https://aam.adobe.io/v1/segments/ |
Traits | https://aam.adobe.io/v1/traits/ |
Trait Types | https://aam.adobe.io/v1/customer-trait-types |
Taxonomy | https://aam.adobe.io/v1/taxonomies/0/ |
API メソッド | リクエスト URL |
---|---|
Algorithmic Modeling | https://api.demdex.com/v1/models/ |
Data Source | https://api.demdex.com/v1/datasources/ |
Derived Signals | https://api.demdex.com/v1/signals/derived/ |
Destinations | https://api.demdex.com/v1/destinations/ |
Domains | https://api.demdex.com/v1/partner-sites/ |
Folders | 特性:https://api.demdex.com/v1/folders/traits / セグメント: https://api.demdex.com/v1/folders/segments / |
Schema | https://api.demdex.com/v1/schemas/ |
Segments | https://api.demdex.com/v1/segments/ |
Traits | https://api.demdex.com/v1/traits/ |
Trait Types | https://api.demdex.com/v1/customer-trait-types |
Taxonomy | https://api.demdex.com/v1/taxonomies/0/ |
Audience Manager API では、複数の作業環境にアクセスできます。これらの環境では、使用中の実稼動データに影響することなく、個別のデータベースについてコードをテストすることができます。次の表は、使用可能な API 環境と、対応するリソースホスト名のリストです。
使用する認証方法に応じて、次の表に従って環境 URLs を調整する必要があります。
環境 | ホスト名(JWT 認証) | ホスト名(OAuth 認証) |
---|---|---|
実稼動 | https://aam.adobe.io/... |
https://api.demdex.com/... |
ベータ | https://aam-beta.adobe.io/... |
https://api-beta.demdex.com/... |
Audience Manager ベータ環境は、実稼動環境の小規模なスタンドアロンバージョンです。テストするデータはすべてこの環境で入力および収集する必要があります。
これらの API では、新しいバージョンが定期的にリリースされています。新しいリリースでは、API バージョン番号が増加しています。リクエスト URL では、バージョン番号は次の例のように v<version number>
として参照されます。
https://<host>/v1/...
Audience Manager REST API によって返される HTTP
ステータスコードおよび応答テキスト。
レスポンスコード ID | レスポンスのテキスト | 定義 |
---|---|---|
200 |
OK |
リクエストは正常に処理されました。必要があれば、予期されたコンテンツまたはデータを返します。 |
201 |
Created |
リソースが作成されました。PUT および POST リクエストに対して返されます。 |
204 |
No Content |
リソースが削除されました。レスポンス本文は空白になります。 |
400 |
Bad Request |
サーバーがリクエストを理解できませんでした。通常は、構文が正しくないことが原因です。リクエストを確認して、再試行してください。 |
403 |
Forbidden |
このリソースへのアクセス権がありません。 |
404 |
Not Found |
指定されたパスでリソースが見つかりません。 |
409 |
Conflict |
リソースの状態に競合が発生しているので、リクエストを完了できません。 |
500 |
Server Error |
サーバーで予期しないエラーが発生し、リクエストを完了できません。 |