快速入门

您可以完成本快速入门，熟悉 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,[e-mail],[e-mail],
2,[e-mail], [e-mail],[e-mail]
3,[e-mail],[e-mail]  ,
4,[e-mail],[e-mail],

电子邮件地址须满足以下格式和哈希处理要求：

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

格式化后的数据如下：

#,email_1,email_2,email_3
1,[e-mail],[e-mail],
2,[e-mail],[e-mail],[e-mail]
3,[e-mail],[e-mail],
4,[e-mail],[e-mail],

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

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

下面的 AudienceMember 示例显示了输入数据第一行的 [e-mail] 和 [e-mail] 经过格式设置、哈希处理和编码后的电子邮件地址：

{
  "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. 前往 audienceMembers.ingest 页面。
3. 点击右侧的 API 按钮，然后点击展开部分中的 Try it! 按钮。
4. 将复制的请求正文粘贴到请求正文框中。
5. 点击执行按钮，完成授权提示，然后查看响应。

成功响应

成功的请求会返回一个响应，其中包含一个包含 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"
          }
        ]
      }
    ]
  }
}

后续步骤

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