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
}
字段
requestId

string

请求的自动生成的 ID。

授权范围

需要以下 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,
  "conversionValue": number,
  "eventSource": enum (EventSource),
  "eventDeviceInfo": {
    object (DeviceInfo)
  },
  "cartData": {
    object (CartData)
  },
  "customVariables": [
    {
      object (CustomVariable)
    }
  ],
  "experimentalFields": [
    {
      object (ExperimentalField)
    }
  ],
  "userProperties": {
    object (UserProperties)
  }
}
字段
destinationReferences[]

string

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

string

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

string (Timestamp format)

必需。事件发生的时间。

采用 RFC 3339 标准，生成的输出将始终在末尾带 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，并使用 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

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

number

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

enum (EventSource)

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

object (DeviceInfo)

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

object (CartData)

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

object (CustomVariable)

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

object (ExperimentalField)

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

object (UserProperties)

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

AdIdentifiers

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

JSON 表示法 
{
  "sessionAttributes": string,
  "gclid": string,
  "gbraid": string,
  "wbraid": string,
  "landingPageDeviceInfo": {
    object (DeviceInfo)
  }
}
字段
sessionAttributes

string

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

string

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

string

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

string

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

object (DeviceInfo)

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

DeviceInfo

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

JSON 表示法 
{
  "userAgent": string,
  "ipAddress": string
}
字段
userAgent

string

可选。相应上下文的设备的用户代理字符串。
ipAddress

string

可选。相应上下文的设备的 IP 地址。

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

EventSource

事件的来源。

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

CartData

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

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

string

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

string

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

string

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

number

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

object (Item)

可选。与活动关联的商品列表。

项

表示与活动关联的购物车中的商品。

JSON 表示法 
{
  "merchantProductId": string,
  "quantity": string,
  "unitPrice": number
}
字段
merchantProductId

string

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

string (int64 format)

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

number

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

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)
}
字段
customerType

enum (CustomerType)

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

enum (CustomerValueBucket)

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

CustomerType

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

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

CustomerValueBucket

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

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