- Audience Manager 指南
- 概述
- 功能
- 報表
- API 和 SDK 程式碼
- Data Integration Library (DIL) API
- 實作與整合指南
- 參考
- 常見問題解答
- 協助與法律
- 常見客戶支援問題
- 文件更新
- 字彙表
開始使用REST APIs
有關一般需求、驗證、可選查詢參數、請求URLs和其他參考的資訊。
API 需求與建議
使用Audience Manager API時，您必須且應該執行的操作。
使用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 I/O開發人員工具，以及所有Adobe產品的和API。 這是設定和使用Adobe APIs的建議方式。
- OAuth驗證（已過時）。雖然此方法已不再提倡，但具有現有OAuth整合的客戶仍可繼續使用此方法。
根據您的驗證方法，您需要相應調整請求URLs。 有關您應使用的主機名的詳細資訊，請參見Environments部分。
JWT (Service Account)使用Adobe I/O的驗證
Adobe I/O概述
Adobe I/O 是Adobe的開發人員生態系統和社群。它包含Adobe I/O開發人員工具，以及所有Adobe產品的和API。
這是設定和使用Adobe APIs的建議方式。
必要條件
在配置JWT驗證之前，請務必存取Adobe中的Adobe I/O開發人員控制台。 請洽詢您的組織管理員以取得存取要求。
驗證
請遵循下列步驟，使用Adobe I/O配置JWT (Service Account)驗證：
- 登入Adobe開發人員主控台。
- 按照服務帳戶連接中的步驟操作。
- 在步驟2:使用服務帳戶驗證將API新增至您的專案，請選擇Audience Manager API選項。
- 根據步驟3中的指示進行第一個API呼叫，以嘗試連接。
要以自動方式配置和使用Audience Manager REST APIs，可以寫程式生成JWT。 有關詳細說明，請參見JWT（服務帳戶）Authentication。
OAuth 驗證（已過時）
Audience Manager REST API 現在已不建議使用Token驗 OAuth 2.0 證和續約方式。
請改用JWT（服務帳戶）驗證。
Audience Manager REST API遵循代號驗證和續約的OAuth 2.0標準。 以下各節將說明如何驗證和開始使用API。
建立一般API用戶
我們建議您建立個別的技術使用者帳戶，以搭配Audience Manager API使用。這是一般帳戶，不會系結至您組織中的特定使用者或與其關聯。 此類API使用者帳戶可協助您完成下列2項工作：
- 識別呼叫API的服務（例如，來自使用我們API的應用程式或來自發出API請求的其他工具的呼叫）。
- 不間斷地訪問API。當系結至特定人員的帳戶離開您的公司時，可能會將其刪除。 這會使您無法使用可用的API程式碼。 未系結至特定員工的一般帳戶可協助您避免此問題。
舉例來說，假設您想要使用大量管理工具一次變更許多區段，做為此類帳戶的使用案例。 為此，您的使用者帳戶需要API存取權。 請建立非特定的API使用者帳戶，該帳戶具有適當的認證、金鑰和機密，以進行API呼叫，而不是新增權限給特定使用者。 如果您開發使用Audience Manager API的自己應用程式，這也很有用。
與您的Audience Manager顧問合作，以設定一般API僅限使用者帳戶。
密碼驗證工作流
密碼驗證安全訪問我們的REST API。 以下步驟概述瀏覽器中JSON用戶端的密碼驗證工作流程。
如果將存取和重新整理Token儲存在資料庫中，請加密這些Token。
步驟1:請求API訪問
請洽詢您的合作夥伴解決方案經理。 他們會提供您API用戶端ID和密碼。 ID和密碼會將您驗證給API。
注意：如果您想要收到重新整理Token，請在您要求API存取時指定。
步驟2:請求代號
將Token請求傳入您偏好的JSON用戶端。 建立請求時：
- 使用
POST方法調用https://api.demdex.com/oauth/token。 - 將您的用戶端ID和密碼轉換為基本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:接收Token
JSON回應包含您的存取Token。 回應應如下所示：
{
"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會在原始Token過期後續約API存取權。 如果請求，密碼工作流中的響應JSON包括刷新標籤。 如果您未收到重新整理Token，請透過密碼驗證程式建立新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:請求新Token
將重新整理Token請求傳入您偏好的JSON用戶端。 建立請求時：
- 使用
POST方法調用https://api.demdex.com/oauth/token。 - 將您的用戶端ID和密碼轉換為基本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:接收新Token
JSON回應包含您的新存取Token。 回應應如下所示：
{
"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才能取得存取和重新整理Token。
進行驗證API請求
在您收到驗證Token後呼叫API方法的需求。
要對可用API方法進行調用，請執行以下操作：
- 在
HTTP標題中，設定Authorization: Bearer <token>。 - 使用JWT（服務帳戶）Authentication時，您需要提供
x-api-key標題，該標題與您的client_id相同。 您可從Adobe I/O整合頁面取得client_id。 - 呼叫所需的API方法。
可選API查詢參數
設定可用於返回對象所有屬性的方法的可選參數。
您可以將這些可選參數與返回對象all屬性的API方法一起使用。 將查詢傳入API時，請在請求字串中設定這些選項。
| 參數 | 說明 |
|---|---|
page |
依頁碼傳回結果。 編號從0開始。 |
pageSize |
設定請求傳回的回應結果數目（預設值為10）。 |
sortBy |
根據指定的JSON屬性排序並返回結果。 |
descending |
以遞減順序排序和傳回結果。 ascending 為預設值。 |
search |
根據您要用作搜尋參數的指定字串傳回結果。 例如，假設您想要在該項目的任何值欄位中，尋找具有「測試」字詞的所有模型的結果。 您的範例要求可能如下所示： 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
API URLs
URLs 請求、測試和生產環境以及版本。
請求 URLs
下表按方法列出用於傳入API請求的請求URLs。
根據您使用的驗證方法，您需要根據下表調整您的請求URLs。
JWT驗證的請求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/ |
要求OAuth驗證URLs（已過時）
| 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/...
已定義的響應代碼
HTTP 狀態代碼和由返回的響應文本 Audience Manager REST API。
| 回應碼ID | 回應文字 | 定義 |
|---|---|---|
200 |
OK |
請求已成功處理。 將視需要傳回預期的內容或資料。 |
201 |
Created |
已建立資源。 傳回PUT和POST請求。 |
204 |
No Content |
已刪除資源。 回應主體將為空。 |
400 |
Bad Request |
伺服器不瞭解請求。 通常是由於語法格式錯誤所致。 請檢查您的要求，然後再試一次。 |
403 |
Forbidden |
您沒有資源的存取權。 |
404 |
Not Found |
找不到指定路徑的資源。 |
409 |
Conflict |
由於資源狀態衝突，無法完成請求。 |
500 |
Server Error |
伺服器遇到意外錯誤，無法完成請求。 |
本頁內容
