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

用于将转化事件与其他线上活动（例如广告点击）进行匹配的标识符和其他信息。

字段
session_attributes

string

可选。用于事件归因和建模的会话属性。
gclid

string

可选。与此事件相关联的 Google 点击 ID (gclid)。
gbraid

string

可选。一种点击标识符，标识的是与应用事件相关联且源自 iOS14 及更高版本 iOS 设备的点击。
wbraid

string

可选。一种点击标识符，标识的是与网站事件相关联且源自 iOS14 及更高版本 iOS 设备的点击。
landing_page_device_info

DeviceInfo

可选。用户在与广告互动后访问广告客户网站时所用设备（如有）的相关信息。

AddressInfo

用户的地址信息。

字段
given_name

string

必需。用户的名字（小写），不含标点符号、前导或尾随空格，并以 SHA-256 格式进行哈希处理。
family_name

string

必需。用户的姓氏（全部小写），不含标点符号、前导或尾随空格，并以 SHA-256 格式进行哈希处理。
region_code

string

必需。用户的 ISO-3166-1 alpha-2 格式地址中 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

可选。与商品 Feed 关联的 Merchant Center Feed 标签。
merchant_feed_language_code

string

可选。与您上传商品的 Merchant Center Feed 相关联的 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

可选。要为自定义变量存储的值。
destination_references[]

string

可选。用于确定应将自定义变量发送到哪个 Event.destination_references 的参考字符串。如果为空，则使用 Event.destination_references。

CustomerType

与事件关联的客户的类型。

枚举
CUSTOMER_TYPE_UNSPECIFIED 未指定 CustomerType。不应使用此值。
NEW 客户是广告客户的新客户。
RETURNING 客户再次访问广告客户的网站。
REENGAGED 客户再次与广告客户互动。

CustomerValueBucket

广告客户评估的客户价值。

枚举
CUSTOMER_VALUE_BUCKET_UNSPECIFIED 未指定的 CustomerValueBucket。不应使用此值。
LOW 客户价值较低。
MEDIUM 客户价值中等。
HIGH 客户是高价值客户。

目的地

您要将数据发送到的 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 地址。

注意：Google Ads 不支持针对欧洲经济区 (EEA)、英国 (UK) 或瑞士 (CH) 境内的最终用户进行 IP 地址匹配。添加逻辑以有条件地排除来自这些地区的用户分享 IP 地址，并确保您清楚、全面地向用户提供与您在网站、应用和其他媒体资源上收集的数据有关的信息，并在法律或任何适用的 Google 政策要求的情况下征得用户同意。如需了解详情，请参阅线下转化数据导入功能简介页面。

编码

已哈希处理的身份识别信息的编码类型。

枚举
ENCODING_UNSPECIFIED 未指定编码类型。不应使用此值。
HEX 十六进制编码。
BASE64 Base 64 编码。

EncryptionInfo

正在提取的数据的加密信息。

字段
联合字段 wrapped_key。用于加密数据的封装密钥。wrapped_key 只能是下列其中一项：
gcp_wrapped_key_info

GcpWrappedKeyInfo

Google Cloud Platform 封装密钥信息。

事件

表示用户与广告客户的网站或应用之间的互动的事件。

字段
destination_references[]

string

可选。用于确定目的地的参考字符串。如果为空，则会将事件发送到请求中的所有 destinations。
transaction_id

string

必需。相应事件的唯一标识符。
event_timestamp

Timestamp

必需。事件发生的时间。
last_updated_timestamp

Timestamp

可选。上次更新活动的时间。
user_data

UserData

可选。用户提供的数据片段，表示事件所关联的用户。
consent

Consent

可选。关联用户是否已提供不同类型的意见征求信息。
ad_identifiers

AdIdentifiers

可选。用于将转化事件与其他线上活动（例如广告点击）进行匹配的标识符和其他信息。
currency

string

可选。与相应事件中的所有货币价值相关联的币种代码。
conversion_value

double

可选。与事件相关联的转化价值（针对基于价值的转化）。
event_source

EventSource

可选。指明事件发生位置（网站、应用、实体店等）的信号。
event_device_info

DeviceInfo

可选。事件发生时收集的有关所用设备（如有）的信息。
cart_data

CartData

可选。与活动相关的交易和商品信息。
custom_variables[]

CustomVariable

可选。要发送到转化容器（转化操作或 Floodlight 活动）的其他键值对信息。
experimental_fields[]

ExperimentalField

可选。实验性字段的键值对列表，这些字段最终可能会升级为 API 的一部分。
user_properties

UserProperties

可选。广告客户在事件发生时评估的用户相关信息。

EventSource

事件的来源。

枚举
EVENT_SOURCE_UNSPECIFIED 未指定的 EventSource。不应使用此值。
WEB 相应事件是通过网络浏览器生成的。
APP 相应事件是由应用生成的。
IN_STORE 相应活动是根据实体店交易生成的。
PHONE 相应事件是通过电话生成的。
OTHER 相应事件是从其他来源生成的。

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

必需。要发送到指定目的地的用户列表。单个请求中最多可以发送 10,000 个 AudienceMember 资源。
consent

Consent

可选。请求级意见征求，适用于请求中的所有用户。用户级意见征求会覆盖请求级意见征求，并且可以在每个 AudienceMember 中指定。
validate_only

bool

可选。用于测试目的。如果为 true，则系统会验证请求，但不会执行请求。仅返回错误，不返回结果。
encoding

Encoding

可选。对于 UserData 上传内容是必需的。用户标识符的编码类型。对于经过哈希处理的用户标识符，这是哈希处理后的字符串的编码类型。对于加密的哈希用户标识符，这是外部加密字符串的编码类型，但不一定是内部哈希字符串的编码类型，这意味着内部哈希字符串的编码方式可能与外部加密字符串不同。对于非 UserData 上传，系统会忽略此字段。
encryption_info

EncryptionInfo

可选。UserData 上传的加密信息。如果未设置，则假定上传的身份识别信息已进行哈希处理，但未加密。对于非 UserData 上传，系统会忽略此字段。
terms_of_service

TermsOfService

可选。用户已接受/拒绝的服务条款。

IngestAudienceMembersResponse

来自 IngestAudienceMembersRequest 的响应。

字段
request_id

string

请求的自动生成的 ID。

IngestEventsRequest

请求将受众群体成员上传到指定的目标平台。返回 IngestEventsResponse。

字段
destinations[]

Destination

必需。要将事件发送到的目的地列表。
events[]

Event

必需。要发送到指定目的地的事件列表。一次请求中最多可以发送 2,000 个 Event 资源。
consent

Consent

可选。请求级意见征求，适用于请求中的所有用户。用户级意见征求会覆盖请求级意见征求，并且可以在每个 Event 中指定。
validate_only

bool

可选。用于测试目的。如果为 true，则系统会验证请求，但不会执行请求。仅返回错误，不返回结果。
encoding

Encoding

可选。对于 UserData 上传内容是必需的。用户标识符的编码类型。对于经过哈希处理的用户标识符，这是哈希处理后的字符串的编码类型。对于加密的哈希用户标识符，这是外部加密字符串的编码类型，但不一定是内部哈希字符串的编码类型，这意味着内部哈希字符串的编码方式可能与外部加密字符串不同。对于非 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/IDFA）的列表。单个 AudienceMember 中最多可提供 10 个 mobileIds。

PairData

相应受众群体的 PAIR ID。至少需要一个配对 ID。

字段
pair_ids[]

string

必需。由 Cleanroom 提供的 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 上传内容是必需的。用户标识符的编码类型。仅适用于加密用户标识符的外部编码。对于非 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

可识别用户的数据。必须至少提供一个标识符。

字段
user_identifiers[]

UserIdentifier

必需。用户的标识符。您可以提供同一类型数据的多个实例（例如，多个电子邮件地址）。为了提高匹配的可能性，请尽可能提供更多标识符。在单个 AudienceMember 或 Event 中最多可以提供 10 个 userIdentifiers。

UserIdentifier

用户的单个标识符。

字段
联合字段 identifier。必须指定一个。identifier 只能是下列其中一项：
email_address

string

使用 SHA-256 哈希函数在标准化后对电子邮件地址进行哈希处理。
phone_number

string

使用 SHA-256 哈希函数在标准化（E164 标准）后进行哈希处理的电话号码。
address

AddressInfo

用户地址的已知组成部分。用于存放一次性匹配的标识符分组。

UserProperties

广告客户在事件发生时评估的用户相关信息。如需了解详情，请访问 https://support.google.com/google-ads/answer/14007601。

字段
customer_type

CustomerType

可选。与事件关联的客户的类型。
customer_value_bucket

CustomerValueBucket

可选。广告客户评估的客户价值。