发送受众群体成员

您可以完成本快速入门，熟悉 Data Manager API。选择要查看的快速入门版本：

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

  1. 准备一个 Destination 来接收受众群体数据。
  2. 准备要发送的受众群体数据。
  3. 为观众成员构建 IngestionService 请求。
  4. 使用 Google APIs Explorer 发送请求。
  5. 了解成功和失败响应。

准备目的地

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

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

      "productDestinationId": "AUDIENCE_ID"
    }

  • 将 operatingAccount 设置为将接收受众群体数据的产品和账号 ID。

准备受众群体数据

假设有一个以英文逗号分隔的文件，其中包含以下示例数据。文件中的每一行都对应一个受众群体成员，每个成员最多可以有三个电子邮件地址。

#,email_1,email_2,email_3
1,dana@example.com,DanaM@example.com,
2,ALEXJ@example.com, AlexJ@cymbalgroup.com,alexj@altostrat.com
3,quinn@CYMBALGROUP.com,baklavainthebalkans@gmail.com  ,
4,rosario@example.org,cloudySanFrancisco@GMAIL.com,

电子邮件地址必须符合以下格式和哈希处理要求：

  1. 移除所有前导、尾随和中间空格。
  2. 将电子邮件地址转换为小写。
  3. 使用 SHA-256 算法对电子邮件地址进行哈希处理。
  4. 使用十六进制 (hex) 或 Base64 编码对哈希字节进行编码。本指南中的示例使用十六进制编码。

格式化后的数据如下：

#,email_1,email_2,email_3
1,dana@example.com,danam@example.com,
2,alexj@example.com,alexj@cymbalgroup.com,alexj@altostrat.com
3,quinn@cymbalgroup.com,baklavainthebalkans@gmail.com,
4,rosario@example.org,cloudysanfrancisco@gmail.com,

以下是经过哈希处理和编码后的数据：

#,email_1,email_2,email_3
1,07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3,1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7
2,2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3,54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51,e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478
3,05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0,f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5
4,83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f,223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4

以下是输入数据第一行中 dana@example.com 和 danam@example.com 的格式化、哈希处理和编码电子邮件地址的示例 AudienceMember：

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ]
  }
}

构建请求正文

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

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

      "productDestinationId": "AUDIENCE_ID"
    }
  ],
  "audienceMembers": [
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
          },
          {
            "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3"
          },
          {
            "emailAddress": "54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51"
          },
          {
            "emailAddress": "e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0"
          },
          {
            "emailAddress": "f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f"
          },
          {
            "emailAddress": "223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4"
          }
        ]
      }
    }
  ],
  "consent": {
    "adUserData": "CONSENT_GRANTED",
    "adPersonalization": "CONSENT_GRANTED"
  },
  "encoding": "HEX",
  "termsOfService": {
    "customerMatchTermsOfServiceStatus": "ACCEPTED"
  },
  "validateOnly": true
}
  1. 将正文中的占位符（例如 OPERATING_ACCOUNT_PRODUCT、OPERATING_ACCOUNT_ID 和 AUDIENCE_ID）替换为您的账号和目标平台的值。
  2. 将 validateOnly 设置为 true，以验证请求但不应用更改。准备好应用更改后，请将 validateOnly 设置为 false。
  3. 将 termsOfService 设置为表示用户已接受目标客户匹配服务条款。
  4. 请注意，此请求表示已授予 consent，并且未使用加密。

发送请求

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

成功响应

成功的请求会返回一个包含 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": "audience_members.audience_members[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": "audience_members.audience_members[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

后续步骤