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`
`last_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ë`
`last_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`
`last_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ë`
`last_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`
`last_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`
`last_name`	`6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F`
`region_code`	`PT`
`postal_code`	`1229-076`

将数据转换为 `Event`

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

timestamp：事件发生的时间。
transaction_id：事件的唯一标识符。
event_source：事件的来源。如果指定，则必须为 EVENT_SOURCE_WEB。
ad_identifiers 或 user_data：事件必须包含广告标识符或用户数据。如果事件同时具有这两种类型的 ID，请同时发送这两种 ID。

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

下面是第二个事件中经过格式设置、经过哈希处理和编码的数据的 Event 示例：

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "currency": "EUR",
   "timestamp": "2025-06-10T23:42:33-05:00",
   "transactionId": "DEF999911111",
   "eventSource": "EVENT_SOURCE_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",
       "timestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "EVENT_SOURCE_WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "lastName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "currency": "EUR",
       "timestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "EVENT_SOURCE_WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "lastName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       }
     }
  ],
  "validateOnly": true
}

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

发送请求

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

成功响应

成功的请求会返回一个响应，其中包含一个包含 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",
   "timestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "EVENT_SOURCE_WEB",
   "destinationReferences": [
      "conversion_action_1"
   ]
}

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

后续步骤

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

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