入門 REST APIs

有關一般要求、驗證、可選查詢參數、請求的資訊 URLs、和其他引用。

API 需求與建議

與 Audience Manager APIs

使用時請注意以下事項 Audience ManagerAPI 代碼：

• 請求參數： 除非另有指定，否則所有請求參數都是必需的。
• 請求標題:使用 Adobe Developer 令牌，必須提供 x-api-key 標題。 你可以 API 按照 服務帳戶整合 的子菜單。
• JSON內容類型： 指定 content-type: application/json 和 accept: application/json 你的密碼。
• 請求和響應： 以格式正確的方式發送請求 JSON 的雙曲餘切值。 Audience Manager 響應 JSON 格式化資料。 伺服器響應可以包含請求的資料、狀態代碼或兩者。
• 訪問： 您 Audience Manager 顧問將為您提供客戶端ID和密鑰，以便您 API 請求。
• 文檔和代碼示例： 文本 斜體 表示在生成或接收時提供或傳遞的變數 API 資料。 替換 斜體 包含您自己的代碼、參數或其他必需資訊的文本。

驗證

的 Audience Manager REST APIs 支援兩種驗證方法。

• JWT（服務帳戶）身份驗證 使用 Adobe Developer。 Adobe Developer 是Adobe的開發者生態系統和社區。 包括 所有Adobe產品的API。 這是設定和使用的推薦方法 Adobe APIs。
• OAuth身份驗證（不建議使用）。 雖然此方法已棄用，但現有客戶 OAuth 整合可以繼續使用此方法。

JWT (Service Account)使用Adobe Developer進行身份驗證

Adobe Developer概述

Adobe Developer 是Adobe的開發者生態系統和社區。 包括 所有Adobe產品的API。

這是設定和使用的推薦方法 Adobe APIs。

必要條件

在配置之前 JWT 驗證，確保您有權訪問 Adobe Developer控制台 在 Adobe Developer。 請與組織管理員聯繫以獲取訪問請求。

驗證

按照以下步驟配置 JWT (Service Account) 驗證 Adobe Developer:

1. 登錄到 Adobe Developer控制台。
2. 按照中的步驟操作 服務帳戶連接。
   • 期間 步驟2:使用服務帳戶驗證將API添加到項目的子菜單。 Audience Manager API 的雙曲餘切值。
3. 首先嘗試連接 API 根據來自 步驟3。

技術帳戶RBAC權限

如果您的Audience Manager帳戶使用 基於角色的訪問控制，您必須建立Audience Manager技術用戶帳戶，並將其添加到Audience ManagerRBAC組中，該組將調用API。

按照以下步驟建立技術用戶帳戶並將其添加到RBAC組：

1. 製作 GET 呼叫 https://aam.adobe.io/v1/users/self。 該呼叫將建立您可以在 Admin Console，也請參見Wiki頁。 Users 的子菜單。

   

2. 登錄到您的Audience Manager帳戶 添加技術用戶帳戶 調用API的用戶組。

OAuth 身份驗證（不建議使用）

的 Audience Manager REST API 如下 OAuth 2.0 令牌驗證和續訂標準。 以下各節介紹如何驗證和開始使用 APIs

建立泛型 API 用戶

我們建議您建立一個單獨的技術用戶帳戶，以便使用 Audience Manager APIs這是一個普通帳戶，它不與組織中的特定用戶關聯或關聯。 此類型 API 用戶帳戶可幫助您完成以下兩項任務：

• 確定呼叫的服務 API (例如，來自使用我們 API或來自其他工具 API 請求)。
• 提供對 APIs與特定人員關聯的帳戶在離開公司時可能會被刪除。 這將阻止您使用可用 API 代碼。 不與特定員工關聯的通用帳戶有助於您避免此問題。

作為此類帳戶的示例或使用案例，假設您要同時使用 批量管理工具。 為此，您的用戶帳戶需要 API 訪問。 不是向特定用戶添加權限，而是建立非特定用戶， API 具有相應憑據、密鑰和機密的用戶帳戶 API 呼叫。 如果您開發自己的應用程式，並使用 Audience Manager APIs

與 Audience Manager 建立泛型， API-only用戶帳戶。

密碼驗證工作流

密碼身份驗證安全訪問我們的 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 key表示在訪問令牌過期之前的秒數。 最佳做法是，在令牌暴露時使用較短的過期時間來限制暴露。

刷新令牌

刷新令牌續訂 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"
}

授權碼與隱式認證

的 Audience Manager REST API 支援授權碼和隱式身份驗證。 要使用這些訪問方法，您的用戶需要登錄到 https://api.demdex.com/oauth/authorize 獲取訪問和刷新令牌。

驗證 API 請求

呼叫要求 API 方法。

針對可用的呼叫 API 方法：

• 在 HTTP 標題，設定 Authorization: Bearer <token>。
• 使用時 JWT（服務帳戶）身份驗證，您需要提供 x-api-key 標題，與 client_id。 你可以 client_id 從 Adobe Developer整合 的子菜單。
• 呼叫所需 API 的雙曲餘切值。

可選 API 查詢參數

設定可用於返回對象所有屬性的方法的可選參數。

可將這些可選參數與 API 返回的方法 全部 對象的屬性。 將查詢傳遞到 API。

關於頁面選項的注釋

頁面資訊 不是 指定，請求返回純 JSON 結果。 如果頁面資訊 是 指定，則返回的清單將包裝在 JSON 包含有關總結果和當前頁面的資訊的對象。 使用頁面選項的示例請求可能與以下內容類似：

GET https://aam.adobe.io/v1/models/?page=1&pageSize=2&search=Test

API URLs

URLs 請求、轉移和生產環境以及版本。

請求 URLs

下表列出了請求 URLs 過去 API 請求，按方法。

根據您使用的驗證方法，您需要調整請求 URLs 按下表列出。

請求 URLs 為 JWT 驗證

請求 URLs 為 OAuth 身份驗證（不建議使用）

環境

的 Audience Manager API提供對不同工作環境的訪問。 這些環境可幫助您針對不同的資料庫test代碼，而不會影響即時生產資料。 下表列出了 API 環境和相應的資源主機名。

根據您使用的驗證方法，您需要調整環境 URLs 下表所示。

版本

這些版本的新版本 API定期發放。 新版本將增加 API 版本號。 請求中引用了版本號 URL 如 v<version number> 如下例所示：

https://<host>/v1/...

已定義響應代碼

HTTP 狀態代碼和由返回的響應文本 Audience Manager REST API。