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,
  "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,
  "conversionValue": 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)

可选。要发送到转化容器（转化操作或 Floodlight 活动）的其他键值对信息。
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 应用数据流的应用客户端的用户实例的唯一标识符。
conversionValue

number

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

AdIdentifiers

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

JSON 表示法 
{
  "sessionAttributes": string,
  "gclid": string,
  "gbraid": string,
  "wbraid": string,
  "landingPageDeviceInfo": {
    object (DeviceInfo)
  },
  "mobileDeviceId": 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；在其他平台上，此标识符为广告客户标识符。

DeviceInfo

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

JSON 表示法 
{
  "userAgent": string,
  "ipAddress": string,
  "category": string,
  "languageCode": string,
  "screenHeight": integer,
  "screenWidth": integer,
  "operatingSystem": string,
  "operatingSystemVersion": string,
  "model": string,
  "brand": string,
  "browser": string,
  "browserVersion": string
}
字段
userAgent

string

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

string

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

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

string

可选。设备类别。例如，“桌面设备”“平板电脑”“移动设备”“智能电视”。
languageCode

string

可选。设备使用的语言，采用 ISO 639-1 格式。
screenHeight

integer

可选。屏幕的高度（以像素为单位）。
screenWidth

integer

可选。屏幕宽度（以像素为单位）。
operatingSystem

string

可选。设备的操作系统或平台。
operatingSystemVersion

string

可选。操作系统或平台的版本。
model

string

可选。设备的型号。
brand

string

可选。设备的品牌。
browser

string

可选。浏览器的品牌或类型。
browserVersion

string

可选。浏览器版本。

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

可选。事件发生的次大陆代码，采用联合国 M49 格式。
continentCode

string

可选。事件发生地点的洲代码，采用联合国 M49 格式。