Show Menu
主題×

REST API快速入門

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

API需求與建議

使用Audience manager時,您必須且應做的 API事。
  • ​請求參數:除非另有指定,否則所有請求參數都是必要的。
  • JSON 內容類型:在程 content-type: application/json 式碼 中指 accept: application/json 定和指定。
  • ​要求與回應:以格式正確的物件傳送 JSON 請求。 Audience Manager 以格式化資 JSON 料回應。 伺服器回應可包含要求的資料、狀態碼或兩者。
  • ​存取:您的 Audience Manager 顧問會提供您用戶端ID和金鑰,讓您提出 API 要求。
  • ​檔案和程式碼範例:斜體 文字 ,代表您在製作或接收資料時提供或傳入的變 API 數。 以您 自己的程式碼 、參數或其他必要資訊取代斜體文字。

建議:建立一般API使用者

我們建議您建立個別的技術使用者帳戶,以便使用Audience Manager API。這是一般帳戶,不會系結至您組織中的特定使用者或與其關聯。 此類型的使 API 用者帳戶可協助您完成2項工作:
  • 識別呼叫的服務 API (例如,來自使用我們的應用程式或提出請 API求的其他工具的呼 API 叫)。
  • 不間斷地存取 APIs。當系結至特定人員的帳戶離開您的公司時,可能會將其刪除。 這會使您無法使用可用的程 API 式碼。 未系結至特定員工的一般帳戶可協助您避免此問題。
舉例來說,假設您想要使用批量管理工具一次變更許多區段,或是用於此類型 的帳戶 。 為此,您的使用者帳戶需要存 API 取權。 請建立非特定的使用者帳戶,該帳戶具有適當的認證、金鑰 API 和密碼,以進行呼叫,而不是新增權限給特定 API 使用者。 如果您開發使用Audience Manager的應用程式,這個功能也會很有 API用。
與您的Audience manager顧問合作,以設定一般、僅 API限使用者帳戶。

OAuth Authentication

Audience Manager遵循 REST API 代號 OAuth 2.0 驗證和續約的標準。 以下各節將說明如何驗證並開始使用 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 首 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, API 在原始Token過期後續約存取權。 如果請求,密碼工作 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從瀏覽器用戶端建立新存取Token JSON 的工作流程。

步驟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請求

在您收到驗 API 證Token後呼叫方法的要求。
若要對可用方法進行呼 API 叫:
  • 在標題 HTTP 中,設定 Authorization: Bearer <token>
  • 呼叫所需的 API 方法。

可選API查詢參數

設定可用於返回對象所有屬性的方法的可選參數。
您可將這些可選參數與傳 API 回物件所 有屬性 的方法搭配使用。 將查詢傳入請求字串中時,請在請求字串中設定這些選項 API。
參數
說明
頁面
依頁碼傳回結果。 編號從0開始。
pageSize
設定請求傳回的回應結果數目(預設為10)。
sortBy
根據指定的屬性排序並返回 JSON 結果。
降序
以遞減順序排序和傳回結果。 預設為遞增。
搜尋
根據您要用作搜尋參數的指定字串傳回結果。 例如,假設您想要在該項目的任何值欄位中,尋找具有「測試」字詞的所有模型的結果。 您的範例要求可能如下所示: GET https://api.demdex.com/v1/models/?search=Test 。 您可以搜尋「get all」方法傳回的任何值。
folderId
傳回指定資料夾內特徵的所有ID。 並非所有方法都適用。
權限
根據指定的權限傳回區段清單。 READ是預設值。 權限包括:
  • READ :傳回並檢視區段的相關資訊。
  • WRITE :使用 PUT 來更新區段。
  • CREATE :用 POST 來建立區段。
  • DELETE : 刪除區段. 需要存取基本特徵(如果有)。 例如,若您要移除屬於某個群體的特徵,您需要有權利加以刪除。
使用個別的索引鍵值配對指定多個權限。 例如,若要傳回僅具有和權限的 READ WRITE 段清單,請傳入 "permissions":"READ" "permissions":"WRITE"
includePermissions
(布林值)設為true可傳回區段的權限。 設值為 false。

關於頁面選項的附註

未指定頁 面資訊 ,請求會傳回純 JSON 結果為陣列。 如果指定 了頁面資訊 ,則傳回的清單會包裝在物件中,該物件包含 JSON 關於總結果和目前頁面的資訊。 您使用頁面選項的範例要求看起來可能類似下列:
GET https://api.demdex.com/v1/models/?page=1&pageSize=2&search=Test

API URL

URLs 請求、測試和生產環境以及版本。

請求URL

下表依方法列出用來傳入請求 API 的請求URL。
API 方法
請求 URL
演算法模型
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/

環境

這些 Audience Manager 功能 API可讓您存取不同的工作環境。 這些環境可協助您針對個別資料庫測試程式碼,而不會影響即時的生產資料。 下表列出了可用環境 API 和相應的資源主機名。
環境
主機名稱
生產
https://api.demdex.com/...
測試版
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
已建立
已建立資源。 傳回 PUT 和請 POST 求。
204
沒有內容
已刪除資源。 回應主體將為空。
400
Bad Request
伺服器不瞭解請求。 通常是由於語法格式錯誤所致。 請檢查您的要求,然後再試一次。
403
禁止
您沒有資源的存取權。
404
找不到
找不到指定路徑的資源。
409
衝突
由於資源狀態衝突,無法完成請求。
500
伺服器錯誤
伺服器遇到未預期的錯誤,導致其無法完成請求。