開始使用REST APIs getting-started-with-rest-apis
關於一般需求、驗證、選擇性查詢引數、要求URLs和其他參考的資訊。
API需求與Recommendations api-requirements-recommendations
使用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資料時提供或傳入的變數。 將 斜體的 文字取代為您自己的程式碼、引數或其他必要資訊。
驗證 authentication
Audience Manager REST APIs支援三種驗證方法。
- [建議]{class="badge positive"}OAuth伺服器對伺服器驗證使用Adobe開發人員主控台。 Adobe Developer是Adobe的開發人員生態系統和社群。 它包含所有Adobe產品🔗的API。 這是設定及使用Adobe APIs的建議方式。 在Adobe開發人員檔案中進一步瞭解OAuth伺服器對伺服器驗證。
- [已棄用]{class="badge negative"}JWT (服務帳戶)驗證使用Adobe開發人員主控台。 Adobe Developer是Adobe的開發人員生態系統和社群。 它包含所有Adobe產品🔗的API。
- [已棄用]{class="badge negative"}舊版OAuth驗證。 雖然此方法已過時,但擁有現有OAuth整合的客戶可以繼續使用此方法。
使用Adobe Developer的OAuth伺服器對伺服器驗證 oauth-adobe-developer
本節說明如何收集驗證Audience ManagerAPI呼叫所需的認證,如下方流程圖所述。 您可以在初始的一次性設定中收集大部分必要的認證。 然而,存取權杖必須每24小時重新整理一次。
Adobe Developer概觀 developer-overview
Adobe Developer是Adobe的開發人員生態系統和社群。 它包含所有Adobe產品🔗的API。
這是設定及使用Adobe APIs的建議方式。
必備條件 prerequisites-server-to-server
設定OAuth Server-to-Server驗證之前,請確定您擁有Adobe Developer中Adobe Developer Console的存取權。 如需存取要求,請聯絡您的組織管理員。
驗證 oauth
請依照下列步驟,使用Adobe Developer設定OAuth Server-to-Server驗證:
- 登入Adobe Developer Console。
- 請依照OAuth伺服器對伺服器認證實作指南中的步驟操作。
- 在步驟2:使用服務帳戶驗證新增API至您的專案,請選擇Audience Manager API選項。
- 根據步驟3的指示,進行您的第一個API呼叫以嘗試連線。
將Audience Manager API新增至專案 add-aam-api-to-project
移至Adobe Developer Console並使用您的Adobe ID登入。 接下來,請依照教學課程中概述的步驟,在Adobe Developer Console檔案中建立空白專案。
建立新專案後,請在 Project Overview 畫面上選取 Add API。
Add an API 畫面會出現。 選取Adobe Experience Cloud的產品圖示,然後選擇 Audience Manager API 再選取 Next。
選取OAuth伺服器對伺服器驗證型別 select-oauth-server-to-server
接著,選取驗證型別以產生存取權杖並存取Audience ManagerAPI。
選取要整合的產品設定檔 select-product-profiles
在 Configure API 畫面中,選取所需的產品設定檔。 您整合的服務帳戶可透過此處選取的產品設定檔存取精細功能。
準備好後選取 Save configured API。
收集認證 gather-credentials
將API新增至專案後,專案的 Audience Manager API 頁面會顯示所有呼叫Audience ManagerAPI時所需的下列認證:
在Developer Console中新增API後的
{API_KEY}
(Client ID){ORG_ID}
(Organization ID)
產生存取權杖 generate-access-token
下一個步驟是產生{ACCESS_TOKEN}
認證以用於Audience ManagerAPI呼叫。 不像{API_KEY}
和{ORG_ID}
的值,必須每24小時產生一次新Token,才能繼續使用Audience ManagerAPI。 選取 Generate access token,如下所示。
測試API呼叫 test-api-call
取得驗證持有人權杖後,請執行API呼叫以測試您現在可以存取Audience ManagerAPI。
code language-shell |
---|
|
使用有效的存取Token時,API端點會傳回200回應,以及包含您的組織有權存取之所有全域資料來源的回應主體。
code language-json |
---|
|
[已棄用]{class="badge negative"}使用Adobe Developer的JWT (Service Account)驗證 jwt
Adobe Developer概觀 adobeio
Adobe Developer是Adobe的開發人員生態系統和社群。 它包含所有Adobe產品🔗的API。
這是設定及使用Adobe APIs的建議方式。
必備條件 prerequisites
設定JWT驗證之前,請確定您擁有Adobe Developer中Adobe Developer Console的存取權。 如需存取要求,請聯絡您的組織管理員。
驗證 auth
請依照下列步驟,使用Adobe Developer設定JWT (Service Account)驗證:
- 登入Adobe Developer Console。
- 請依照服務帳戶連線中的步驟操作。
- 在步驟2:使用服務帳戶驗證新增API至您的專案,請選擇Audience Manager API選項。
- 根據步驟3的指示,進行您的第一個API呼叫以嘗試連線。
note note |
---|
NOTE |
若要以自動方式設定及使用Audience Manager REST APIs,您可以以程式設計方式產生JWT。 如需詳細指示,請參閱JWT (服務帳戶)驗證。 |
技術帳戶RBAC許可權
如果您的Audience Manager帳戶使用角色型存取控制,您必須建立Audience Manager技術使用者帳戶,並將其新增至將進行API呼叫的Audience ManagerRBAC群組。
請依照下列步驟建立技術使用者帳戶,並將其新增至RBAC群組:
-
對
https://aam.adobe.io/v1/users/self
進行GET
呼叫。 通話將會建立您可以在Users頁面的Admin Console中看到的技術使用者帳戶。 -
登入您的Audience Manager帳戶,然後將技術使用者帳戶新增到將進行API呼叫的使用者群組。
[已棄用]{class="badge negative"}OAuth驗證(已棄用) oauth-deprecated
note warning |
---|
WARNING |
Audience Manager REST API權杖驗證和透過OAuth 2.0的續約現在已被取代。 |
請改用JWT (服務帳戶)驗證。 |
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使用者端的密碼驗證工作流程。
note tip |
---|
TIP |
如果您將Token儲存在資料庫中,請加密存取並重新整理Token。 |
步驟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回應包含您的存取權杖。 回應應如下所示:
code language-json |
---|
|
expires_in
金鑰代表存取Token到期前的秒數。 如果代號公開時,最佳做法就是使用較短的到期時間來限制曝光。
重新整理Token refresh-token
重新整理Token在原始的Token過期後更新API存取權。 若有要求,密碼工作流程中的回應JSON會包含重新整理權杖。 如果您沒有收到重新整理權杖,請透過密碼驗證程式建立新的權杖。
您也可以使用重新整理權杖,在現有存取權杖過期之前產生新權杖。
如果您的存取Token已過期,您會在回應中收到401 Status Code
和下列標頭:
WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"
下列步驟概述使用重新整理權杖從瀏覽器中的JSON使用者端建立新存取權杖的工作流程。
步驟1:要求新Token
傳入重新整理Token要求給您偏好的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:接收新Token
JSON回應包含您的新存取權杖。 回應應如下所示:
code language-json |
---|
|
授權代碼和隱含驗證 authentication-code-implicit
Audience Manager REST API支援授權碼與隱含驗證。 若要使用這些存取方法,您的使用者需要登入https://api.demdex.com/oauth/authorize
才能取得存取權杖並重新整理。
提出已驗證的API要求 authenticated-api-requests
收到驗證Token後呼叫API方法的需求。
若要對可用的API方法進行呼叫:
- 在
HTTP
標頭中,設定Authorization: Bearer <token>
。 - 使用JWT (服務帳戶)驗證時,您需要提供
x-api-key
標頭,此標頭將與您的client_id
相同。 您可以從Adobe Developer整合頁面取得您的client_id
。 - 呼叫必要的API方法。
選用的API查詢引數 optional-api-query-parameters
設定傳回物件所有屬性的方法可用的選用引數。
您可以使用這些選擇性引數搭配API方法,傳回物件的 所有 屬性。 將該查詢傳入API時,在要求字串中設定這些選項。
page
pageSize
sortBy
descending
ascending
為預設值。search
GET https://aam.adobe.io/v1/models/?search=Test
。 您可以搜尋"get all"方法傳回的任何值。folderId
permissions
根據指定的許可權傳回區段清單。 READ
為預設值。 許可權包括:
READ
:傳回並檢視區段的相關資訊。WRITE
:使用PUT
更新區段。CREATE
:使用POST
建立區段。DELETE
:刪除區段。 需要存取基礎特徵(如果有)。 例如,如果您想要移除區段,則需要擁有刪除屬於該區段之特徵的許可權。
請以個別的索引鍵值配對指定多個許可權。 例如,若要傳回僅具有READ
和WRITE
許可權的區段清單,請傳入"permissions":"READ"
、"permissions":"WRITE"
。
includePermissions
true
以傳回您對區段的許可權。 預設值為false
。關於頁面選項的附註
當未指定頁面資訊 時,要求會傳回陣列中的純JSON結果。 如果指定頁面資訊**,則傳回的清單會包裝在包含總結果和目前頁面相關資訊的JSON物件中。 您使用頁面選項的範例請求看起來可能類似這樣:
GET https://aam.adobe.io/v1/models/?page=1&pageSize=2&search=Test
API URLs api-urls
請求、中繼和生產環境及版本的URLs。
要求URLs request-urls
下表列出用來以方法傳入API個要求的要求URLs。
根據您使用的驗證方法,您需要根據下表調整您的要求URLs。
要求URLs [建議]{class="badge positive"}[已棄用]{class="badge negative"}透過Adobe Developer進行JWT驗證 request-urls-jwt
https://aam.adobe.io/v1/models/
https://aam.adobe.io/v1/datasources/
https://aam.adobe.io/v1/signals/derived/
https://aam.adobe.io/v1/destinations/
https://aam.adobe.io/v1/partner-sites/
https://aam.adobe.io/v1/folders/traits /
區段:
https://aam.adobe.io/v1/folders/segments /
https://aam.adobe.io/v1/schemas/
https://aam.adobe.io/v1/segments/
https://aam.adobe.io/v1/traits/
https://aam.adobe.io/v1/customer-trait-types
https://aam.adobe.io/v1/taxonomies/0/
要求[的URLs已棄用]{class="badge negative"}OAuth驗證 request-urls-oauth
https://api.demdex.com/v1/models/
https://api.demdex.com/v1/datasources/
https://api.demdex.com/v1/signals/derived/
https://api.demdex.com/v1/destinations/
https://api.demdex.com/v1/partner-sites/
https://api.demdex.com/v1/folders/traits /
區段:
https://api.demdex.com/v1/folders/segments /
https://api.demdex.com/v1/schemas/
https://api.demdex.com/v1/segments/
https://api.demdex.com/v1/traits/
https://api.demdex.com/v1/customer-trait-types
https://api.demdex.com/v1/taxonomies/0/
環境 environments
Audience Manager API提供不同工作環境的存取權。 這些環境可協助您針對個別資料庫測試程式碼,而不會影響即時生產資料。 下表列出可用的API環境和對應的資源主機名稱。
根據您使用的驗證方法,您需要根據下表調整您的環境URLs。
https://aam.adobe.io/...
https://api.demdex.com/...
https://aam-beta.adobe.io/...
https://api-beta.demdex.com/...
版本 versions
這些API的新版本會定期發行。 新發行版本會增加API版本編號。 請求URL中以v<version number>
參照的版本號碼,如下列範例所示:
https://<host>/v1/...
已定義的回應代碼 response-codes-defined
Audience Manager REST API傳回的HTTP
狀態代碼和回應文字。
200
OK
201
Created
PUT
與POST
的要求。204
No Content
400
Bad Request
403
Forbidden
404
Not Found
409
Conflict
500
Server Error