您可以完成本快速入門導覽課程,熟悉 Data Manager API。請選擇要查看的捷出指南版本:
在本快速入門導覽課程中,您將完成下列步驟:
- 準備
Destination
來接收目標對象資料。 - 準備要傳送的目標對象資料。
- 為目標對象成員建立
IngestionService
要求。 - 使用 Google APIs Explorer 傳送要求。
- 瞭解成功和失敗回應。
準備目的地
您必須先準備要傳送資料的目的地,才能傳送資料。以下提供範例 Destination
供您使用:
{
"operatingAccount": {
"product": "OPERATING_ACCOUNT_PRODUCT",
"accountId": "OPERATING_ACCOUNT_ID"
},
"productDestinationId": "AUDIENCE_ID"
}
將
operatingAccount
設為接收目標對象資料的產品和帳戶 ID。
準備目標對象資料
請參考以下以逗號分隔的檔案中的資料範例。檔案中的每一行都對應至目標對象的一位成員,且每位成員最多有三個電子郵件地址。
#,email_1,email_2,email_3
1,dana@example.com,DanaM@example.com,
2,ALEXJ@example.com, AlexJ@cymbalgroup.com,alexj@altostrat.com
3,quinn@CYMBALGROUP.com,baklavainthebalkans@gmail.com ,
4,rosario@example.org,cloudySanFrancisco@GMAIL.com,
電子郵件地址有以下格式和雜湊處理規定:
- 移除所有開頭、結尾和中間的空格。
- 將電子郵件地址轉換為小寫。
- 使用 SHA-256 演算法對電子郵件地址進行雜湊處理。
- 使用十六進位 (十六進位) 或 Base64 編碼來編碼雜湊位元組。本指南中的範例使用十六進位編碼。
以下是經過格式設定的資料:
#,email_1,email_2,email_3
1,dana@example.com,danam@example.com,
2,alexj@example.com,alexj@cymbalgroup.com,alexj@altostrat.com
3,quinn@cymbalgroup.com,baklavainthebalkans@gmail.com,
4,rosario@example.org,cloudysanfrancisco@gmail.com,
以下是經過雜湊處理和編碼的資料:
#,email_1,email_2,email_3
1,07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3,1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7
2,2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3,54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51,e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478
3,05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0,f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5
4,83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f,223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4
以下是輸入資料第一列 dana@example.com
和 danam@example.com
格式化、雜湊處理及編碼的電子郵件地址的 AudienceMember
範例:
{
"userData": {
"userIdentifiers": [
{
"emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
},
{
"emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
}
]
}
}
建構要求主體
將 Destination
和 userData
組合為要求主體:
{
"destinations": [
{
"operatingAccount": {
"product": "OPERATING_ACCOUNT_PRODUCT",
"accountId": "OPERATING_ACCOUNT_ID"
},
"productDestinationId": "AUDIENCE_ID"
}
],
"audienceMembers": [
{
"userData": {
"userIdentifiers": [
{
"emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
},
{
"emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
}
]
}
},
{
"userData": {
"userIdentifiers": [
{
"emailAddress": "2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3"
},
{
"emailAddress": "54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51"
},
{
"emailAddress": "e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478"
}
]
}
},
{
"userData": {
"userIdentifiers": [
{
"emailAddress": "05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0"
},
{
"emailAddress": "f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5"
}
]
}
},
{
"userData": {
"userIdentifiers": [
{
"emailAddress": "83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f"
},
{
"emailAddress": "223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4"
}
]
}
}
],
"consent": {
"adUserData": "CONSENT_GRANTED",
"adPersonalization": "CONSENT_GRANTED"
},
"encoding": "HEX",
"termsOfService": {
"customerMatchTermsOfServiceStatus": "ACCEPTED"
},
"validateOnly": true
}
- 將主體中的預留位置 (例如
OPERATING_ACCOUNT_PRODUCT
、OPERATING_ACCOUNT_ID
和AUDIENCE_ID
) 更新為帳戶和目的地的值。 - 將
validateOnly
設為true
,即可驗證要求,而不會套用變更。準備套用變更時,請將validateOnly
設為false
。 - 將
termsOfService
設為「已接受」表示使用者已接受客戶比對服務條款。 - 請注意,這項要求表示已授予
consent
,且不會使用加密功能。
傳送要求
- 使用範例右上方的複製按鈕複製要求主體。
- 前往
audienceMembers.ingest
頁面。 - 按一下右側的「API」按鈕,然後點選展開區段中的「立即試用」按鈕。
- 將複製的請求主體貼到「Request body」方塊中。
- 按一下「執行」按鈕,完成授權提示,然後查看回應。
成功回應
成功的要求會傳回回應,其中包含含有 requestId
的物件。
{
"requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}
失敗回應
要求失敗會導致錯誤回應狀態碼 (例如 400 Bad
Request
),以及包含錯誤詳細資料的回應。
舉例來說,如果 email_address
包含純文字字串,而非十六進位編碼值,就會產生以下回應:
{
"error": {
"code": 400,
"message": "There was a problem with the request.",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "INVALID_ARGUMENT",
"domain": "datamanager.googleapis.com"
},
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "audience_members.audience_members[0].user_data.user_identifiers",
"description": "Email is not hex encoded.",
"reason": "INVALID_HEX_ENCODING"
}
]
}
]
}
}
未經雜湊處理且僅以十六進位編碼的 email_address
會產生下列回應:
{
"error": {
"code": 400,
"message": "There was a problem with the request.",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "INVALID_ARGUMENT",
"domain": "datamanager.googleapis.com"
},
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "audience_members.audience_members[0]",
"reason": "INVALID_SHA256_FORMAT"
}
]
}
]
}
}
後續步驟
- 設定驗證機制,並使用用戶端程式庫設定環境。
- 瞭解各類資料的格式、雜湊和編碼規定。
- 瞭解如何加密使用者資料。
- 瞭解最佳做法。
- 瞭解限制和配額。