Method: events.ingest

从提供的 Destination 上传 Event 资源列表。

HTTP 请求

POST https://datamanager.googleapis.com/v1/events:ingest

网址采用 gRPC 转码语法。

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "destinations": [
    {
      object (Destination)
    }
  ],
  "events": [
    {
      object (Event)
    }
  ],
  "consent": {
    object (Consent)
  },
  "validateOnly": boolean,
  "encoding": enum (Encoding),
  "encryptionInfo": {
    object (EncryptionInfo)
  }
}
字段
destinations[]

object (Destination)

必需。事件发送到的目标位置列表。
events[]

object (Event)

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

object (Consent)

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

boolean

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

enum (Encoding)

可选。上传 UserData 文件时必须提供。用户标识符的编码类型。对于经过哈希处理的用户标识符，这是经过哈希处理的字符串的编码类型。对于经过加密的哈希用户标识符，这是外部加密字符串的编码类型，但不一定是内部哈希字符串的编码类型，这意味着内部哈希字符串的编码方式可能与外部加密字符串不同。对于非 UserData 上传，此字段会被忽略。
encryptionInfo

object (EncryptionInfo)

可选。UserData上传内容的加密信息。如果未设置，系统会假定上传的身份信息已经过哈希处理，但未加密。对于非 UserData 上传，此字段会被忽略。

响应正文

IngestEventsRequest的回答。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "requestId": string,
  "fieldWarnings": [
    {
      object (FieldWarning)
    }
  ]
}
字段
requestId

string

自动生成的请求 ID。
fieldWarnings[]

object (FieldWarning)

包含字段路径的详细行级警告。

授权范围

需要以下 OAuth 范围：

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

活动

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

JSON 表示法 
{
  "destinationReferences": [
    string
  ],
  "transactionId": string,
  "eventTimestamp": string,
  "lastUpdatedTimestamp": string,
  "userData": {
    object (UserData)
  },
  "consent": {
    object (Consent)
  },
  "adIdentifiers": {
    object (AdIdentifiers)
  },
  "currency": string,
  "eventSource": enum (EventSource),
  "eventDeviceInfo": {
    object (DeviceInfo)
  },
  "cartData": {
    object (CartData)
  },
  "customVariables": [
    {
      object (CustomVariable)
    }
  ],
  "experimentalFields": [
    {
      object (ExperimentalField)
    }
  ],
  "userProperties": {
    object (UserProperties)
  },
  "eventName": string,
  "clientId": string,
  "userId": string,
  "additionalEventParameters": [
    {
      object (EventParameter)
    }
  ],
  "thirdPartyUserData": {
    object (UserData)
  },
  "eventLocation": {
    object (EventLocation)
  },
  "appInstanceId": string,
  "callInfo": {
    object (CallInfo)
  },
  "conversionValue": number,
  "conversionCount": number
}
字段
destinationReferences[]

string

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

string

可选。此事件的唯一标识符。对于作为代码转化的额外数据源发送的事件，此字段为必填字段。
eventTimestamp

string (Timestamp format)

必需。事件发生的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不进行“Z”归一化处理的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
lastUpdatedTimestamp

string (Timestamp format)

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

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不进行“Z”归一化处理的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
userData

object (UserData)

可选。用户提供的数据，代表与事件关联的用户。
consent

object (Consent)

可选。关于关联用户是否已提供不同类型同意情况的信息。
adIdentifiers

object (AdIdentifiers)

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

string

可选。与此事件中所有货币价值相关联的货币代码。
eventSource

enum (EventSource)

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

object (DeviceInfo)

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

object (CartData)

可选。与事件关联的交易和商品的相关信息。
customVariables[]

object (CustomVariable)

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

object (ExperimentalField)

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

object (UserProperties)

可选。事件发生时广告主评估的用户信息。
eventName

string

可选。事件名称。对于 GA4 事件，此为必需字段。
clientId

string

可选。此 GA4 网站数据流的 Web 客户端用户实例的唯一标识符。
userId

string

可选。用户的唯一标识符，由广告客户定义。
additionalEventParameters[]

object (EventParameter)

可选。一个存储桶，用于存放要包含在事件中但尚未通过其他结构化字段指定的任何事件参数。
thirdPartyUserData

object (UserData)

可选。与 userData 中提供的数据类型相同，但明确标记为由第三方提供并归第三方所有，而非第一方广告客户数据。
eventLocation

object (EventLocation)

可选。此事件发生时收集到的用户位置信息。
appInstanceId

string

可选。此 GA4 应用数据流的应用客户端用户实例的唯一标识符。
callInfo

object (CallInfo)

可选。收集到的有关导致此事件的通话（如有）的信息。
conversionValue

number

可选。与事件关联的转化价值（适用于基于价值的转化）。
conversionCount

number

可选。与事件关联的转化数量（适用于基于计数的转化）。

AdIdentifiers

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

JSON 表示法 
{
  "sessionAttributes": string,
  "gclid": string,
  "gbraid": string,
  "wbraid": string,
  "landingPageDeviceInfo": {
    object (DeviceInfo)
  },
  "mobileDeviceId": string,
  "dclid": string,
  "impressionId": string,
  "matchId": string,
  "encryptedUserIds": [
    {
      object (EncryptedUserId)
    }
  ],
  "ppid": string,
  "visitorPpid": string,
  "leadId": string
}
字段
sessionAttributes

string

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

string

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

string

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

string

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

object (DeviceInfo)

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

string

可选。广告客户的移动标识符。这可能是 iOS 上的 IDFA、Android 上的 AdID 或其他平台的广告客户标识符。
dclid

string

可选。与此事件关联的展示广告点击 ID。
impressionId

string

可选。与此事件关联的展示 ID。
matchId

string

可选。用于将此事件与上一个事件联接的匹配 ID 字段。
encryptedUserIds[]

object (EncryptedUserId)

可选。任意数量的加密用户 ID。
ppid

string

可选。由发布商定义的经过身份验证（已登录）用户的唯一标识符。
visitorPpid

string

可选。由发布商定义的未通过身份验证的用户（未登录的用户）的唯一标识符。
leadId

string

可选。用户提交潜在客户表单时，Google 生成的 ID。

EncryptedUserId

为用于归因而颁发的用户标识符。如果使用此字段，则所有字段均为必填字段。

JSON 表示法 
{
  "encryptedId": string,
  "entityType": enum (EncryptionEntityType),
  "entityId": string,
  "source": enum (EncryptionSource)
}
字段
encryptedId

string

必需。由字母数字组成的加密 ID。
entityType

enum (EncryptionEntityType)

必需。加密实体类型。此密钥应与广告投放或数据传输的加密配置相匹配。
entityId

string (int64 format)

必需。加密实体 ID。此密钥应与广告投放或数据传输的加密配置相匹配。
source

enum (EncryptionSource)

必需。说明经过加密的 Cookie 是从广告投放（%m 宏）还是从数据传输中收到的。

EncryptionEntityType

加密实体类型。

枚举
ENCRYPTION_ENTITY_TYPE_UNSPECIFIED 未指定加密实体类型。
CAMPAIGN_MANAGER_ACCOUNT Campaign Manager 360 账号。
CAMPAIGN_MANAGER_ADVERTISER Campaign Manager 360 广告客户。
DISPLAY_VIDEO_PARTNER Display & Video 360 合作伙伴。
DISPLAY_VIDEO_ADVERTISER Display & Video 360 广告客户。
GOOGLE_ADS_CUSTOMER Google Ads 客户。
GOOGLE_AD_MANAGER_NETWORK_CODE Google Ad Manager 广告资源网代码。

EncryptionSource

加密来源。

枚举
ENCRYPTION_SOURCE_UNSPECIFIED 未指定加密来源。
AD_SERVING 广告投放加密来源。
DATA_TRANSFER 数据传输加密来源。

EventSource

事件的来源。

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

CartData

与事件关联的购物车数据。

JSON 表示法 
{
  "merchantId": string,
  "merchantFeedLabel": string,
  "merchantFeedLanguageCode": string,
  "transactionDiscount": number,
  "items": [
    {
      object (Item)
    }
  ],
  "couponCodes": [
    string
  ]
}
字段
merchantId

string

可选。与商品关联的 Merchant Center ID。
merchantFeedLabel

string

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

string

可选。与商品的 Merchant Center Feed 关联的 ISO 639-1 语言代码。
transactionDiscount

number

可选。与交易相关的所有折扣的总和。
items[]

object (Item)

可选。与事件相关的商品列表。
couponCodes[]

string

可选。已应用于购物车的优惠券代码列表。购物车级和商品级优惠券代码彼此独立。

如果事件是针对 Google Analytics 目标，请仅提供一个优惠券代码。Google Analytics 会忽略其他优惠券代码。

项

表示与事件关联的购物车中的商品。

JSON 表示法 
{
  "merchantProductId": string,
  "quantity": string,
  "unitPrice": number,
  "itemId": string,
  "additionalItemParameters": [
    {
      object (ItemParameter)
    }
  ],
  "merchantId": string,
  "merchantFeedLabel": string,
  "merchantFeedLanguageCode": string,
  "customVariables": [
    {
      object (ItemCustomVariable)
    }
  ],
  "conversionValue": number
}
字段
merchantProductId

string

可选。Merchant Center 账号中的商品 ID。
quantity

string (int64 format)

可选。与事件关联的此商品的数量。
unitPrice

number

可选。单价（不含税、运费及任何交易级折扣）。
itemId

string

可选。用于引用商品的唯一标识符。
additionalItemParameters[]

object (ItemParameter)

可选。一个存储桶，用于存放与商品相关的任何事件参数，这些参数应包含在事件中，但尚未通过其他结构化字段指定。
merchantId

string

可选。与商品关联的 Merchant Center ID。对于实体店销售特惠活动，此值将覆盖在购物车级别设置的值。对于其他事件，此字段会被忽略。
merchantFeedLabel

string

可选。Merchant Center Feed 的 Feed 标签。如果仍在使用国家/地区，则可以改用 ISO-3166-1 alpha-2 格式的 2 字母国家/地区代码。对于实体店销售特惠活动，此值将覆盖在购物车级别设置的值。对于其他事件，此字段会被忽略。
merchantFeedLanguageCode

string

可选。您用来上传商品数据的 Merchant Center Feed 所关联的 ISO 639-1 语言代码。
customVariables[]

object (ItemCustomVariable)

可选。在跟踪单项转化时，要发送到转化容器（转化操作或 Floodlight 活动）的其他键值对信息。
conversionValue

number

可选。事件中与此商品关联的转化价值（适用于每件商品的转化价值不同的情况）。

ItemParameter

一个存储桶，用于存放与商品相关的任何事件参数，这些参数应包含在事件中，但尚未通过其他结构化字段指定。

JSON 表示法 
{
  "parameterName": string,
  "value": string
}
字段
parameterName

string

必需。要使用的参数的名称。
value

string

必需。要设置的参数值的字符串表示形式。

ItemCustomVariable

适用于广告转化的商品级自定义变量。

JSON 表示法 
{
  "variable": string,
  "value": string,
  "destinationReferences": [
    string
  ]
}
字段
variable

string

可选。要设置的自定义变量的名称。如果未找到给定目标的变量，则该变量将被忽略。
value

string

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

string

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

CustomVariable

适用于广告转化的自定义变量。

JSON 表示法 
{
  "variable": string,
  "value": string,
  "destinationReferences": [
    string
  ]
}
字段
variable

string

可选。要设置的自定义变量的名称。如果未找到给定目标的变量，则该变量将被忽略。
value

string

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

string

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

ExperimentalField

表示非官方字段的实验性字段。

JSON 表示法 
{
  "field": string,
  "value": string
}
字段
field

string

可选。要使用的字段的名称。
value

string

可选。要设置的字段的值。

UserProperties

事件发生时广告主评估的用户信息。如需了解详情，请参阅 https://support.google.com/google-ads/answer/14007601。

JSON 表示法 
{
  "customerType": enum (CustomerType),
  "customerValueBucket": enum (CustomerValueBucket),
  "additionalUserProperties": [
    {
      object (UserProperty)
    }
  ]
}
字段
customerType

enum (CustomerType)

可选。与事件相关的客户类型。
customerValueBucket

enum (CustomerValueBucket)

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

object (UserProperty)

可选。与此事件关联的用户的所有其他用户属性的存储桶。

CustomerType

与事件相关的客户类型。

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

CustomerValueBucket

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

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

UserProperty

与此事件关联的用户的所有其他用户属性的存储桶。

JSON 表示法 
{
  "propertyName": string,
  "value": string
}
字段
propertyName

string

必需。要使用的用户属性的名称。
value

string

必需。要使用的用户属性值的字符串表示形式。

EventParameter

GA4 事件的事件参数。

JSON 表示法 
{
  "parameterName": string,
  "value": string
}
字段
parameterName

string

必需。要使用的参数的名称。
value

string

必需。要设置的参数值的字符串表示形式。

EventLocation

事件发生的地点。

JSON 表示法 
{
  "storeId": string,
  "city": string,
  "subdivisionCode": string,
  "regionCode": string,
  "subcontinentCode": string,
  "continentCode": string
}
字段
storeId

string

可选。对于实体店销售，此字段为必填字段。用于表示事件发生所在实体店的标识符。
city

string

可选。事件发生所在城市的名称。
subdivisionCode

string

可选。事件发生地的 ISO 3166-2 细分代码。
regionCode

string

可选。用户地址的 2 字母 CLDR 地区代码。
subcontinentCode

string

可选。事件发生地的次大陆代码（采用 UN M49 格式）。
continentCode

string

可选。事件发生地的大洲代码（采用 UN M49 格式）。

CallInfo

收集到的有关导致此事件的通话（如有）的信息。

JSON 表示法 
{
  "startTimestamp": string
}
字段
startTimestamp

string (Timestamp format)

必需。导致此事件的通话开始时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不进行“Z”归一化处理的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。