The Data Manager API is in closed beta. To express interest in joining the closed beta, fill out this form.

此页面由 Cloud Translation API 翻译。

发送事件

您可以完成此快速入门，熟悉如何发送事件数据。

事件数据是代码转化的一种额外数据源，可最大限度地提高广告互动信号的质量，并增强数据和整体效果。

选择您要查看的指南版本：

在本快速入门中，您将完成以下步骤：

准备 Destination 以接收事件数据。
准备要发送的事件数据。
为事件构建 IngestionService 请求。
使用 Google APIs Explorer 发送请求。
了解成功和失败响应。

准备目的地

在发送数据之前，您需要准备好接收数据的目标位置。以下是可供您使用的 Destination 示例：

    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }

将 operatingAccount 的 accountId 设置为将接收事件数据的 Google Ads 账号 ID。operatingAccount 的 product 必须是 GOOGLE_ADS。
将 productDestinationId 设置为相应事件的转化操作 ID。转化操作必须是 Google Ads 转化操作，且 type 设置为 WEBPAGE。

本指南介绍了如何构建将每个事件发送到同一转化操作的请求。如果您想在同一请求中针对多个转化操作发送事件，请参阅多个目的地。

准备活动数据

请考虑以下活动数据。每个表都对应一个转化事件。每个转化事件都包含事件的时间戳、转化操作和转化价值。

每个事件都可能包含广告标识符（例如 gclid）或用户标识符（例如电子邮件地址、电话号码和地址信息）。

以下是第一个活动的数据：

活动 #1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`1.99`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`John`
`family_name`	`Smith-Jones`
`region_code`	`us`
`postal_code`	`94045`

第二个活动的数据如下：

活动 2
`conversion_time`	`June 10, 2025 11:42:33PM America/New_York`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`3.25`
`currency`	`eur`
`gclid`	`GCLID_2`
`emails`	`zoe@EXAMPLE.COM` `cloudy.sanfrancisco@gmail.com`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`

设置数据格式

根据格式设置指南中的规定设置字段格式。以下是格式化后的第一个活动的数据：

活动 #1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`1.99`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`john`
`family_name`	`smith-jones`
`region_code`	`US`
`postal_code`	`94045`

以下是第二个事件在格式化后的数据：

活动 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`3.25`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`zoe@example.com` `cloudysanfrancisco@gmail.com`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`

对数据进行哈希处理和编码

此外，格式化后的电子邮件地址、名字和姓氏必须使用 SHA-256 算法进行哈希处理，并使用十六进制或 Base64 编码进行编码。以下是第一个事件的数据在经过格式设置、哈希处理和使用十六进制编码进行编码后的结果：

活动 #1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`1.99`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A`
`family_name`	`DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081`
`region_code`	`US`
`postal_code`	`94045`

以下是第二个事件的数据在经过格式化、哈希处理和使用十六进制编码进行编码后的结果：

活动 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`3.25`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250` `223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4`
`given_name`	`2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450`
`family_name`	`6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F`
`region_code`	`PT`
`postal_code`	`1229-076`

将数据转换为 `Event`

将每个事件的格式化数据和哈希处理后的数据转换为 Event。填写以下必填字段：

event_timestamp：事件发生的时间。
transaction_id：相应活动的唯一标识符。
event_source：事件的来源。如果指定，则必须为 WEB。
ad_identifiers 或 user_data：事件必须包含广告标识符或用户数据。如果您同时拥有这两种数据，请同时发送。

如需查看可用字段的完整列表，请参阅 Event 参考文档。填充您有相应事件值的任何字段。

以下是第二个事件中格式化、哈希处理和编码后的数据的 Event 示例：

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "currency": "EUR",
   "eventTimestamp": "2025-06-10T23:42:33-05:00",
   "transactionId": "DEF999911111",
   "eventSource": "WEB",
   "userData": {
      "userIdentifiers": [
         {
            "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
         },
         {
            "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
         },
         {
            "address": {
              "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
              "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
              "regionCode": "PT",
              "postalCode": "1229-076"
            }
         }
      ]
   }
}

构建请求正文

将 Destination 和 Events 组合为请求正文：

{
  "destinations": [
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 1.99,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "currency": "EUR",
       "eventTimestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       }
     }
  ],
  "validateOnly": true
}

将正文中的占位符（例如 OPERATING_ACCOUNT_ID 和 CONVERSION_ACTION_1_ID）替换为您的账号和目标值。
将 validateOnly 设置为 true，以验证请求但不应用更改。准备好应用更改后，请将 validateOnly 设置为 false。
请注意，此请求未使用加密。

发送请求

使用示例右上角的复制按钮复制请求正文。
前往 events.ingest 页面。
点击右侧的 API 按钮，然后点击展开部分中的试试看！按钮。
将复制的请求正文粘贴到请求正文框中。
点击执行按钮，完成授权提示，然后查看响应。

成功响应

成功的请求会返回一个包含 requestId 的对象的响应。

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

失败响应

如果请求失败，系统会返回错误响应状态代码（例如 400 Bad Request）以及包含错误详细信息的响应。

例如，包含纯文本字符串而非十六进制编码值的 email_address 会生成以下响应：

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

未经过哈希处理且仅经过十六进制编码的 email_address 会产生以下响应：

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

为多个目标平台发送事件

如果您的数据包含针对不同目的地的事件，您可以使用目的地引用在同一请求中发送这些事件。

例如，如果您有一个转化操作 ID 为 123456789 的事件，以及另一个转化操作 ID 为 777111122 的事件，请通过设置每个 Destination 的 reference，在单个请求中发送这两个事件。reference 由用户定义，唯一的要求是每个 Destination 都有一个唯一的 reference。以下是针对相应请求修改后的 destinations 列表：

  "destinations": [
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "123456789"
      "reference": "conversion_action_1"
    },
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "777111122"
      "reference": "conversion_action_2"
    }
  ]

设置每个 Event 的 destination_references，以将其发送到一个或多个特定目的地。例如，以下 Event 仅适用于第一个 Destination，因此其 destination_references 列表仅包含第一个 Destination 的 reference：

{
   "adIdentifiers": {
      "gclid": "GCLID_1"
   },
   "conversionValue": 1.99,
   "currency": "USD",
   "eventTimestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "WEB",
   "destinationReferences": [
      "conversion_action_1"
   ]
}

destination_references 字段是一个列表，因此您可以为事件指定多个目的地。如果您未设置 Event 的 destination_references，Data Manager API 会将相应事件发送到请求中的所有目的地。

后续步骤

配置身份验证并使用客户端库设置环境。
了解每种类型数据的格式设置、哈希处理和编码要求。
了解如何加密用户数据。
了解最佳实践。
了解限制和配额。

发送事件 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。