REST APIs の使用の手引き getting-started-with-rest-apis

Adobe Developer の概要 adobeio

Adobe Developer は、アドビの開発者エコシステムおよびコミュニティです。これにはすべてのアドビ製品の API が含まれます。

Adobe APIs を設定および使用する場合は、この方法をお勧めします。

前提条件 prerequisites

JWT 認証を設定する前に、Adobe Developer で Adobe Developer Console にアクセスできることを確認します。アクセスリクエストについては、組織の管理者にお問い合わせください。

認証 auth

次の手順に従って、Adobe Developer を使用して JWT (Service Account) 認証を設定します。

1. Adobe Developer Console にログインします。
2. サービスアカウント接続の手順に従います。
   • 手順 2：サービスアカウント認証を使用してプロジェクトに API を追加するで、Audience Manager API オプションを選択します。
3. 手順 3 の指示に基づいて最初の API 呼び出しをおこない、接続を試します。

テクニカルアカウントの RBAC 権限

Audience Manager アカウントで役割ベースのアクセス制御を使用する場合は、Audience Manager のテクニカルユーザーアカウントを作成し、API 呼び出しをおこなう Audience Manager の RBAC グループに追加する必要があります。

以下の手順に従って、テクニカルユーザーアカウントを作成し、RBAC グループに追加します。

1. https://aam.adobe.io/v1/users/self に対して GET 呼び出しを実行します。この呼び出しにより、Admin Console の Users ページに表示されるテクニカルユーザーアカウントが作成されます。

   

2. Audience Manager アカウントにログインし、API 呼び出しをおこなうユーザーグループにテクニカルユーザーアカウントを追加します。

Audience Manager REST API では、OAuth 2.0 標準規格に従って、トークンの認証と更新をおこないます。以下のセクションでは、API を認証し、使用を開始する方法について説明します。

汎用の API ユーザーの作成 requirements

Audience Manager APIを使用するための個別の技術的なユーザーアカウントを作成することをお勧めします。これは、組織の特定ユーザーに関連していない、または関連付けられていない一般的なアカウントです。このような API ユーザーアカウントによって 2 つのことが可能になります。

• API の呼び出し元のサービスを特定する（アドビの API を使用するアプリケーションからの呼び出し、または API 要求をおこなう他のツールからの呼び出しなど）。
• API への妨げられることのないアクセスを提供する。特定ユーザーが退社すると、そのユーザーに関連するアカウントが無効になることがあります。すると、利用可能な API コードを使用できなくなってしまいます。特定の従業員に関連付けられていない汎用のアカウントを使用することで、この問題を回避できます。

このタイプのアカウントの例やユースケースとして、 一括管理ツールを使用して一度に多くのセグメントを変更するとします。 これをおこなうためには、ユーザーアカウントに API へのアクセス権が付与されている必要があります。特定のユーザーに対して権限を追加するのではなく、適切な資格情報、キー、および API 呼び出し用の暗号鍵を持つ汎用の API ユーザーアカウントを作成します。これは、Audience Manager API を使用する独自のアプリケーションを開発する場合にも便利です。

担当の Audience Manager コンサルタントにご相談のうえ、API 専用のユーザーアカウントの設定をおこなってください。

パスワード認証ワークフロー password-authentication-workflow

パスワード認証により、 REST API へのアクセスが保護されます。以下の手順は、ブラウザーで JSON クライアントからパスワードを認証する際のワークフローの概要を示しています。

手順 1：API アクセスのリクエスト

パートナーソリューションソリューションに問い合わせます。API クライアント ID と暗号鍵が通知されます。この ID と暗号鍵により、API での認証をおこないます。

注意：更新トークンを受け取る場合は、API アクセスをリクエストする際にその旨を申告してください。

ステップ 2：トークンのリクエスト

JSON クライアントでトークンのリクエストを渡します。リクエストをおこなうには、次の手順に従います。

• POST メソッドを使用して https://api.demdex.com/oauth/token を呼び出します。
• クライアント ID と暗号鍵を、base-64 でエンコードされた文字列に変換します。この変換では、ID と暗号鍵はコロンで区切ります。例えば、資格情報 testId : testSecret は dGVzdElkOnRlc3RTZWNyZXQ= に変換されます。
• HTTP headers 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>

ステップ 3：トークンの受け取り

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 キーは、アクセストークンの有効期間を秒単位で表しています。トークンが公開される場合、ベストプラクティスとして、有効期間を短く設定し、公開時間を制限します。

更新トークン refresh-token

更新トークンは、元のトークンの有効期間が終了した後、API アクセスを更新します。リクエストがあれば、パスワードワークフローの応答 JSON に更新トークンが含まれます。更新トークンを受け取らない場合、パスワード認証プロセスにより新しいトークンを作成します。

また、更新トークンを使用して、既存のアクセストークンの有効期間が終了する前に新しいトークンを作成することもできます。

アクセストークンの有効期間が終了している場合、401 Status Code が生成され、応答のヘッダーが次のようになります。

WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"

次の表は、更新トークンを使用してブラウザーの JSON クライアントから新しいアクセストークンを作成するワークフローを示しています。

ステップ 1：新しいトークンのリクエスト

優先 JSON クライアントで更新トークンのリクエストを渡します。リクエストをおこなうには、次の手順に従います。

• POST メソッドを使用して https://api.demdex.com/oauth/token を呼び出します。
• クライアント ID と暗号鍵を、base-64 でエンコードされた文字列に変換します。この変換では、ID と暗号鍵はコロンで区切ります。例えば、資格情報 testId : testSecret は dGVzdElkOnRlc3RTZWNyZXQ= に変換されます。
• HTTP ヘッダー 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

ステップ 2：新しいトークンの受け取り

JSON 応答に新しいアクセストークンが含まれます。応答は次のようになっています。

{
    "access_token": "4fdfc261-2ffc-4fb7-8dbd-64221714c45f",
    "token_type": "bearer",
    "refresh_token": "295fa487-1825-4caa-a715-80b81ac17dae",
    "expires_in": 21922,
    "scope": "read write"
}

認証コードと暗黙的な認証 authentication-code-implicit

Audience Manager は、認証コードを暗黙的な認証をサポートしています。REST APIこれらのアクセス方法を利用するには、ユーザーが https://api.demdex.com/oauth/authorize にログインし、アクセス権と更新トークンを取得する必要があります。