REST APIs快速入門

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

API 需求與建議

使用Audience Manager APIs時，您必須且應該執行的操作。

使用Audience ManagerAPI程式碼時，請注意下列事項：

• 請求參數： 除非另有指定，否則所有請求參數都為必要。
• 要求標題:使用 AdobeI/ Otoken時，您必須提供標 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 I/O。Adobe I/O 是Adobe的開發人員生態系統和社群。其中包含適用於所有Adobe產品🔗的Adobe I/O開發工具和API及API。 這是設定和使用Adobe APIs的建議方法。
• OAuth驗證（已淘汰）。雖然此方法已遭取代，但現有OAuth整合的客戶可繼續使用此方法。

JWT (Service Account)使用Adobe I/O進行驗證

Adobe I/O概述

Adobe I/O 是Adobe的開發人員生態系統和社群。其中包含適用於所有Adobe產品🔗的Adobe I/O開發工具和API及API。

這是設定和使用Adobe APIs的建議方法。

必要條件

在配置JWT身份驗證之前，請確保您有權訪問Adobe I/O中的Adobe開發人員控制台。 如需存取請求，請聯絡貴組織的管理員。

驗證

請依照下列步驟使用Adobe I/O配置JWT (Service Account)身份驗證：

1. 登入Adobe開發人員控制台。
2. 按照服務帳戶連接中的步驟操作。
   • 在步驟2:使用服務帳戶驗證新增API至您的專案，選擇Audience Manager API選項。
3. 根據步驟3中的指示發出第一個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的一般使用者帳戶。

密碼驗證工作流

密碼身份驗證安全訪問我們的REST API。 以下步驟概述瀏覽器中JSON用戶端的密碼驗證工作流程。

步驟1:請求API訪問

請連絡您的合作夥伴解決方案經理。 它們會提供您API用戶端ID和密碼。 ID和機密會驗證您API。

注意：如果要接收刷新令牌，請在請求API訪問時指定。

步驟2:要求Token

使用您慣用的JSON用戶端傳遞Token要求。 建置請求時：

• 使用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金鑰代表存取權杖過期前的秒數。 最佳作法是，如果代號曾公開，請使用短的到期時間來限制曝光。

重新整理Token

在原始Token過期後，重新整理Token會續訂API存取權。 如果請求，密碼工作流中的響應JSON將包括刷新令牌。 如果您未收到重新整理Token，請透過密碼驗證程式建立新Token。

您也可以使用重新整理Token，在現有存取Token過期之前產生新Token。

如果您的存取權杖已過期，您會在回應中收到401 Status Code和下列標題：

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

下列步驟概述使用重新整理Token，從瀏覽器的JSON用戶端建立新存取Token的工作流程。

步驟1:請求新代號

使用您偏好的JSON用戶端傳遞重新整理Token請求。 建置請求時：

• 使用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 ，並傳入您先前存取要求中收到的重新整理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請求

在收到驗證Token後呼叫API方法的需求。

要對可用的API方法進行呼叫：

• 在HTTP標題中，設定Authorization: Bearer <token>。
• 使用JWT（服務帳戶）Authentication時，您需要提供x-api-key標題，該標題與client_id相同。 您可以從Adobe I/O整合頁面取得client_id。
• 呼叫所需的API方法。

可選API查詢參數

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

您可以將這些可選參數與API方法搭配使用，這些方法會傳回物件的​all​屬性。 將查詢傳遞至API時，請在要求字串中設定這些選項。

關於頁面選項的附註

當頁面資訊​未指定​時，要求會傳回純JSON，結果為陣列。 如果指定了頁資訊​**，則返回的清單將包裝在JSON對象中，該對象包含有關總結果和當前頁的資訊。 使用頁面選項的範例請求看起來可能類似這樣：

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

API URLs

URLs 適用於請求、測試和生產環境及版本。

請求 URLs

下表列出用於傳遞API請求的請求URLs，依方法分列。

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

JWT驗證的請求URLs

OAuth驗證的請求URLs（已廢止）

環境

Audience Manager APIs提供對不同工作環境的訪問。 這些環境可協助您針對個別資料庫測試程式碼，而不會影響即時的生產資料。 下表列出可用的API環境和相應的資源主機名。

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

版本

這些APIs的新版本會定期發行。 新版本會增加API版本號碼。 請求URL中參考的版本號碼為v<version number>，如下列範例所示：

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

定義的響應代碼

HTTP 狀態代碼和由傳回的回應文 Audience Manager REST API字。