有關一般需求、驗證、可選查詢參數、請求URLs和其他參考的資訊。
使用Audience Manager API時,您必須且應該執行的操作。
使用Audience Manager API程式碼時,請注意下列事項:
x-api-key
首。您可依照服務帳戶整合頁面中的指示,取得API金鑰。content-type: application/json
** accept: application/json
並在程式碼中。Audience Manager REST APIs支援兩種驗證方法。
根據您的驗證方法,您需要相應調整請求URLs。 有關您應使用的主機名的詳細資訊,請參見Environments部分。
Adobe I/O 是Adobe的開發人員生態系統和社群。它包含所有Adobe產品的Adobe I/O開發人員工具和API和 API。
這是設定和使用Adobe APIs的建議方式。
在設定JWT驗證之前,請務必存取Adobe I/O中的Adobe Developer Console。 請洽詢您的組織管理員以取得存取要求。
請遵循下列步驟,使用Adobe I/O配置JWT (Service Account)驗證:
要以自動方式配置和使用Audience Manager REST APIs,可以寫程式生成JWT。 有關詳細說明,請參見JWT(服務帳戶)Authentication。
Audience Manager REST API 現在已不建議使用Token驗 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用戶端的密碼驗證工作流程。
如果將存取和重新整理Token儲存在資料庫中,請加密這些Token。
請洽詢您的合作夥伴解決方案經理。 他們會提供您API用戶端ID和密碼。 ID和密碼會將您驗證給API。
注意:如果您想要收到重新整理Token,請在您要求API存取時指定。
將Token請求傳入您偏好的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回應包含您的存取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過期後續約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的工作流程。
將重新整理Token請求傳入您偏好的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
並傳遞您在先前存取請求中收到的重新整理Token。 請求應如下所示:grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e
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。
在您收到驗證Token後呼叫API方法的需求。
要對可用API方法進行調用,請執行以下操作:
HTTP
標題中,設定Authorization: Bearer <token>
。x-api-key
標題,該標題與您的client_id
相同。 您可從Adobe I/O整合頁面取得client_id
。設定可用於返回對象所有屬性的方法的可選參數。
您可以將這些可選參數與返回對象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
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/...
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 |
伺服器遇到意外錯誤,無法完成請求。 |