此页面由 Cloud Translation API 翻译。

发送事件

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

在以下任一场景中使用 Data Manager API：

线上活动：将活动数据作为代码转化的额外数据源发送，以最大限度地提高广告互动信号，并增强数据和整体效果。
线下事件：发送线下转化或增强型潜在客户转化的事件数据。

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

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

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

准备目的地

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

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

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }

将 operatingAccount 的 accountId 设置为将接收事件数据的 Google Ads 账号 ID。operatingAccount 的 accountType 必须是 GOOGLE_ADS。
将 productDestinationId 设置为相应事件的转化操作 ID。对于线上活动，转化操作必须是 type 设置为 WEBPAGE 的 Google Ads 转化操作。对于线下事件，转化操作必须是 type 设置为 UPLOAD_CLICKS 的 Google Ads 转化操作。

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

准备活动数据

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

每个事件可能包含广告标识符（例如 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`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`

第二个活动的数据如下：

活动 #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`
`customer_type`	`RETURNING`

设置数据格式

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

活动 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`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`

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

活动 #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`
`customer_type`	`RETURNING`

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

此外，格式化后的电子邮件地址、名字和姓氏必须使用 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`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`

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

活动 #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`
`customer_type`	`RETURNING`

将数据转换为 `Event`

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

event_timestamp：事件发生的时间。
event_source：事件的来源。对于线下事件是必需参数。对于线上活动，此属性为可选。如果为线上活动指定了此属性，则必须为 WEB。
ad_identifiers 或 user_data：事件必须包含广告标识符或用户数据。如果您有这两种参数，请同时发送。

如果您要将线下转化作为额外的数据源发送，以提升效果和数据强度，则必须提供 transaction_id。否则，transaction_id 是可选的，但建议提供。

如需查看可用字段的完整列表，请参阅 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"
            }
         }
      ],
      "userProperties": {
        "customerType": "RETURNING"
      }
   }
}

构建请求正文

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

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "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"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "NEW",
         "customerValueBucket": "HIGH"
       }
     },
     {
       "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"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "RETURNING"
       }
     }
  ],
  "validateOnly": true
}

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

发送请求

使用示例右上角的复制按钮复制请求正文。
点击工具栏中的 API 按钮。
将复制的请求正文粘贴到请求正文框中。
点击执行按钮，完成授权提示，然后查看响应。

成功响应

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

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

记录返回的 requestId，以便在处理请求中的每个目的地时检索诊断信息。

失败响应

如果请求失败，系统会返回错误响应状态代码（例如 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": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "123456789",
      "reference": "conversion_action_1"
    },
    {
      "operatingAccount": {
        "accountType": "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 会将相应事件发送到请求中的所有目的地。

后续步骤

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

事件概览