Package google.ads.datamanager.v1

索引

IngestionService

這項服務可將目標對象資料傳送至支援的目的地。

IngestAudienceMembers

rpc IngestAudienceMembers(IngestAudienceMembersRequest) returns (IngestAudienceMembersResponse)

將 AudienceMember 資源清單上傳至提供的 Destination。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/datamanager
IngestEvents

rpc IngestEvents(IngestEventsRequest) returns (IngestEventsResponse)

從提供的 Destination 上傳 Event 資源清單。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/datamanager
RemoveAudienceMembers

rpc RemoveAudienceMembers(RemoveAudienceMembersRequest) returns (RemoveAudienceMembersResponse)

從提供的 Destination 中移除 AudienceMember 資源清單。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/datamanager

AdIdentifiers

用於比對轉換事件與其他線上活動 (例如廣告點擊) 的 ID 和其他資訊。

欄位
session_attributes

string

(選用步驟) 用於事件歸因和模擬的工作階段屬性。
gclid

string

(選用步驟) 與這個事件相關聯的 Google 點擊 ID (gclid)。
gbraid

string

(選用步驟) 與應用程式事件相關聯的點擊 ID，且點擊來自 iOS 裝置 (iOS14 以上版本)。
wbraid

string

(選用步驟) 與網站事件相關聯的點擊 ID，且點擊來自 iOS 裝置 (iOS14 以上版本)。
landing_page_device_info

DeviceInfo

(選用步驟) 使用者與廣告互動後，抵達廣告主網站時所用裝置的相關資訊 (如有)。

AddressInfo

使用者的地址資訊。

欄位
given_name

string

必要欄位。使用者名字 (不含標點符號、開頭或結尾的空白字元，且須全部小寫)，並以 SHA-256 雜湊處理。
family_name

string

必要欄位。使用者姓氏，須為全小寫，不得包含標點符號，開頭或結尾不得有空白字元，並以 SHA-256 雜湊處理。
region_code

string

必要欄位。使用者地址的 ISO-3166-1 alpha-2 雙字母區域代碼。
postal_code

string

必要欄位。使用者的地址郵遞區號。

AudienceMember

要接受手術的觀眾。

欄位
consent

Consent

(選用步驟) 使用者的同意聲明設定。
聯集欄位 data。要處理的識別資料類型。data 只能是下列其中一項：
user_data

UserData

可識別使用者的使用者提供資料。
pair_data

PairData

發布商及廣告主使用者身分資料比對 (PAIR) ID。
mobile_data

MobileData

可識別使用者行動裝置的資料。

CartData

與事件相關聯的購物車資料。

欄位
merchant_id

string

(選用步驟) 與項目相關聯的 Merchant Center ID。
merchant_feed_label

string

(選用步驟) 與商品動態饋給相關聯的 Merchant Center 動態饋給標籤。
merchant_feed_language_code

string

(選用步驟) 與上傳商品所在 Merchant Center 動態饋給相關聯的 ISO 639-1 語言代碼。
transaction_discount

double

(選用步驟) 與交易相關的所有折扣總和。
items[]

Item

(選用步驟) 與活動相關的項目清單。

使用者的數位市場法 (DMA) 同意聲明設定。

欄位
ad_user_data

ConsentStatus

(選用步驟) 代表使用者是否同意提供廣告使用者資料。
ad_personalization

ConsentStatus

(選用步驟) 表示使用者是否同意放送個人化廣告。

ConsentStatus

代表使用者是否已同意、拒絕或未指定同意聲明。

列舉
CONSENT_STATUS_UNSPECIFIED 不指定。
CONSENT_GRANTED 已授予。
CONSENT_DENIED 已拒絕。

CustomVariable

廣告轉換的自訂變數。

欄位
variable

string

(選用步驟) 要設定的自訂變數名稱。如果系統找不到指定目的地的變數，就會忽略該變數。
value

string

(選用步驟) 要儲存的自訂變數值。

目的地

要將資料傳送至哪個 Google 產品。例如 Google Ads 帳戶。

欄位
reference

string

(選用步驟) 這個 Destination 資源的 ID，在要求中必須是唯一的。在 IngestEventsRequest 中參照這個 Destination 時使用。
login_account

ProductAccount

(選用步驟) 用於發出這項 API 呼叫的帳戶。如要新增或移除 operating_account 中的資料，這個 login_account 必須具備 operating_account 的寫入權限。舉例來說，operating_account 的管理員帳戶，或是已連結至 operating_account 的帳戶。
linked_account

ProductAccount

(選用步驟) 通話使用者login_account可透過已建立的帳戶連結存取的帳戶。舉例來說，資料合作夥伴的 login_account 可能可以存取客戶的 linked_account。合作夥伴可能會使用這個欄位，將資料從 linked_account 傳送至另一個 operating_account。
operating_account

ProductAccount

必要欄位。要傳送資料至哪個帳戶，或是要從哪個帳戶移除資料。
product_destination_id

string

必要欄位。要擷取資料的產品帳戶物件。例如 Google Ads 目標對象 ID 或 Display & Video 360 目標對象 ID。

DeviceInfo

事件發生時使用的裝置資訊 (如有)。

欄位
user_agent

string

(選用步驟) 指定情境的裝置使用者代理程式字串。
ip_address

string

(選用步驟) 指定情境中裝置的 IP 位址。

編碼

已雜湊處理的識別資訊編碼類型。

列舉
ENCODING_UNSPECIFIED 未指定編碼類型。請一律不使用這個值。
HEX 十六進位編碼。
BASE64 Base64 編碼。

EncryptionInfo

要擷取的資料加密資訊。

欄位
聯集欄位 wrapped_key。用來加密資料的包裝金鑰。wrapped_key 只能是下列其中一項：
gcp_wrapped_key_info

GcpWrappedKeyInfo

Google Cloud Platform 包裝金鑰資訊。

活動

代表使用者與廣告主網站或應用程式的互動事件。

欄位
destination_references[]

string

(選用步驟) 用來判斷目的地的參照字串。
transaction_id

string

必要欄位。這個事件的專屬 ID。
event_timestamp

Timestamp

必要欄位。事件發生的時間。
last_updated_timestamp

Timestamp

(選用步驟) 活動上次更新的時間。
user_data

UserData

(選用步驟) 使用者提供的資料片段，代表與事件相關聯的使用者。
consent

Consent

(選用步驟) 相關聯使用者是否已提供不同類型的同意聲明。
ad_identifiers

AdIdentifiers

(選用步驟) 用於比對轉換事件與其他線上活動 (例如廣告點擊) 的 ID 和其他資訊。
currency

string

(選用步驟) 與此事件中所有金額相關聯的幣別代碼。
conversion_value

double

(選用步驟) 與事件相關的轉換價值 (適用於以價值為準的轉換)。
event_source

EventSource

(選用步驟) 事件發生地點的信號 (網站、應用程式、店內等)。
event_device_info

DeviceInfo

(選用步驟) 事件發生時所用裝置的相關資訊 (如有)。
cart_data

CartData

(選用步驟) 與活動相關的交易和項目資訊。
custom_variables[]

CustomVariable

(選用步驟) 要傳送至轉換容器 (轉換動作或 Floodlight 活動) 的其他鍵/值配對資訊。
experimental_fields[]

ExperimentalField

(選用步驟) 實驗性欄位的鍵/值組合清單，這些欄位最終可能會升級為 API 的一部分。

EventSource

事件的來源。

列舉
EVENT_SOURCE_UNSPECIFIED 未指定 EventSource。請一律不使用這個值。
WEB 活動是透過網路瀏覽器產生。

ExperimentalField

代表非官方欄位的實驗性欄位。

欄位
field

string

(選用步驟) 要使用的欄位名稱。
value

string

(選用步驟) 要設定的欄位值。

GcpWrappedKeyInfo

Google Cloud Platform 包裝金鑰的相關資訊。

欄位
key_type

KeyType

必要欄位。用於加密資料的演算法類型。
wip_provider

string

必要欄位。使用 KEK 時，必須提供 Workload Identity 集區提供者。
kek_uri

string

必要欄位。Google Cloud Platform Cloud Key Management Service 資源 ID。
encrypted_dek

string

必要欄位。Base64 編碼的加密資料加密金鑰。

KeyType

用於加密資料的演算法類型。

列舉
KEY_TYPE_UNSPECIFIED 未指定金鑰類型。請一律不使用這個值。
XCHACHA20_POLY1305 演算法 XChaCha20-Poly1305

IngestAudienceMembersRequest

要求將目標對象成員上傳至指定目的地。傳回 IngestAudienceMembersResponse。

欄位
destinations[]

Destination

必要欄位。要將目標對象成員帶往的到達網頁清單。
audience_members[]

AudienceMember

必要欄位。要傳送至指定目的地的使用者清單。單一要求最多可傳送 10000 個 AudienceMember 資源。
consent

Consent

(選用步驟) 要求層級的同意聲明，適用於要求中的所有使用者。使用者層級同意聲明會覆寫要求層級同意聲明，且可在每個 AudienceMember 中指定。
validate_only

bool

(選用步驟) 僅供測試用途。如果為 true，系統會驗證要求，但不會執行。系統只會傳回錯誤，不會傳回結果。
encoding

Encoding

(選用步驟) 上傳 UserData 時必須提供這項資訊。使用者 ID 的編碼類型。如果是經過雜湊處理的使用者 ID，這就是雜湊字串的編碼類型。如果是加密的雜湊使用者 ID，這是外部加密字串的編碼類型，但不一定是內部雜湊字串的編碼類型，也就是說，內部雜湊字串的編碼方式可能與外部加密字串不同。如果上傳的不是 UserData，系統會忽略這個欄位。
encryption_info

EncryptionInfo

(選用步驟) UserData 上傳內容的加密資訊。如果未設定，系統會假設上傳的識別資訊已雜湊處理，但未加密。如果上傳的不是 UserData，系統會忽略這個欄位。
terms_of_service

TermsOfService

(選用步驟) 使用者接受/拒絕的服務條款。

IngestAudienceMembersResponse

IngestAudienceMembersRequest 的回應。

欄位
request_id

string

系統自動產生的要求 ID。

IngestEventsRequest

要求將目標對象成員上傳至指定目的地。傳回 IngestEventsResponse。

欄位
destinations[]

Destination

必要欄位。要將事件傳送至的目的地清單。
events[]

Event

必要欄位。要傳送至指定目的地的事件清單。單一要求最多可傳送 2000 個 Event 資源。
consent

Consent

(選用步驟) 要求層級的同意聲明，適用於要求中的所有使用者。使用者層級同意聲明會覆寫要求層級同意聲明，且可在每個 Event 中指定。
validate_only

bool

(選用步驟) 僅供測試用途。如果為 true，系統會驗證要求，但不會執行。系統只會傳回錯誤，不會傳回結果。
encoding

Encoding

(選用步驟) 上傳 UserData 時必須提供這項資訊。使用者 ID 的編碼類型。如果是經過雜湊處理的使用者 ID，這就是雜湊字串的編碼類型。如果是加密的雜湊使用者 ID，這是外部加密字串的編碼類型，但不一定是內部雜湊字串的編碼類型，也就是說，內部雜湊字串的編碼方式可能與外部加密字串不同。如果上傳的不是 UserData，系統會忽略這個欄位。
encryption_info

EncryptionInfo

(選用步驟) UserData 上傳內容的加密資訊。如果未設定，系統會假設上傳的識別資訊已雜湊處理，但未加密。如果上傳的不是 UserData，系統會忽略這個欄位。

IngestEventsResponse

IngestEventsRequest 的回應。

欄位
request_id

string

系統自動產生的要求 ID。

項目

代表與活動相關聯的購物車項目。

欄位
merchant_product_id

string

(選用步驟) Merchant Center 帳戶中的產品 ID。
quantity

int64

(選用步驟) 與活動相關的這項商品數量。
unit_price

double

(選用步驟) 此為單位價格，不含稅金、運費和任何交易折扣。

MobileData

目標對象的行動裝置 ID。至少須提供一個行動 ID。

欄位
mobile_ids[]

string

必要欄位。行動裝置 ID (廣告 ID/廣告識別碼) 清單。單一 AudienceMember 最多可提供 10 個 mobileIds。

PairData

目標對象的 PAIR ID。至少須提供一組 PAIR ID。

欄位
pair_ids[]

string

必要欄位。資料無塵室提供的 PII 資料 (以 SHA256 雜湊處理，並使用發布商金鑰透過 EC 可交換密碼加密)，用於 PAIR 使用者名單。單一 AudienceMember 最多可提供 10 個 pairIds。

產品

代表特定 Google 產品。用於尋找帳戶和目的地。

列舉
PRODUCT_UNSPECIFIED 未指明產品。請一律不使用這個值。
GOOGLE_ADS Google Ads。
DISPLAY_VIDEO_PARTNER Display & Video 360 合作夥伴。
DISPLAY_VIDEO_ADVERTISER Display & Video 360 廣告主。
DATA_PARTNER 資料合作夥伴。

ProductAccount

代表特定帳戶。

欄位
product

Product

必要欄位。帳戶所屬的產品。例如 GOOGLE_ADS。
account_id

string

必要欄位。帳戶的 ID。例如 Google Ads 帳戶 ID。

RemoveAudienceMembersRequest

要求從指定目的地中的目標對象移除使用者。傳回 RemoveAudienceMembersResponse。

欄位
destinations[]

Destination

必要欄位。要從中移除使用者的目的地清單。
audience_members[]

AudienceMember

必要欄位。要移除的使用者清單。
validate_only

bool

(選用步驟) 僅供測試用途。如果為 true，系統會驗證要求，但不會執行。系統只會傳回錯誤，不會傳回結果。
encoding

Encoding

(選用步驟) 上傳 UserData 時必須提供這項資訊。使用者 ID 的編碼類型。僅適用於加密使用者 ID 的外部編碼。如果上傳的不是 UserData，系統會忽略這個欄位。
encryption_info

EncryptionInfo

(選用步驟) UserData 上傳內容的加密資訊。如果未設定，系統會假設上傳的識別資訊已雜湊處理，但未加密。如果上傳的不是 UserData，系統會忽略這個欄位。

RemoveAudienceMembersResponse

RemoveAudienceMembersRequest 的回應。

欄位
request_id

string

系統自動產生的要求 ID。

TermsOfService

使用者接受/拒絕的服務條款。

欄位
customer_match_terms_of_service_status

TermsOfServiceStatus

(選用步驟) 目標顧客比對服務條款：https://support.google.com/adspolicy/answer/6299717。您必須接受這項條款，才能將資料上傳至目標顧客比對使用者名單。

TermsOfServiceStatus

代表呼叫者接受或拒絕服務條款的決定。

列舉
TERMS_OF_SERVICE_STATUS_UNSPECIFIED 不指定。
ACCEPTED 狀態：表示來電者已選擇接受《服務條款》。
REJECTED 狀態：表示呼叫者已選擇拒絕服務條款。

UserData

可識別使用者的資料。至少須提供一個 ID。

欄位
user_identifiers[]

UserIdentifier

必要欄位。使用者的 ID。您可以提供多個相同類型的資料例項 (例如多個電子郵件地址)。如要提高比對成功的機率，請盡可能提供多個 ID。單一 AudienceMember 或 Event 最多可提供 10 個 userIdentifiers。

UserIdentifier

使用者的單一 ID。

欄位
聯集欄位 identifier。必須指定其中一個。identifier 只能是下列其中一項：
email_address

string

經過正規化處理後，使用 SHA-256 雜湊函式雜湊處理的電子郵件地址。
phone_number

string

使用 SHA-256 雜湊函式，在正規化 (E164 標準) 後雜湊處理的電話號碼。
address

AddressInfo

使用者地址的已知元件。包含一次比對的所有 ID 分組。