Trang này được dịch bởi Cloud Translation API.

Gửi thành viên đối tượng

Bạn có thể làm theo hướng dẫn bắt đầu nhanh này để làm quen với Data Manager API. Chọn phiên bản hướng dẫn bắt đầu nhanh mà bạn muốn xem:

Trong hướng dẫn nhanh này, bạn sẽ hoàn tất các bước sau:

Chuẩn bị một Destination để nhận dữ liệu về đối tượng.
Chuẩn bị dữ liệu đối tượng để gửi.
Tạo yêu cầu IngestionService cho các thành viên trong đối tượng.
Gửi yêu cầu bằng Google APIs Explorer.
Tìm hiểu về các phản hồi thành công và không thành công.

Chuẩn bị cho một điểm đến

Trước khi có thể gửi dữ liệu, bạn cần chuẩn bị đích đến để gửi dữ liệu. Sau đây là một Destination mẫu để bạn sử dụng:

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

      "productDestinationId": "AUDIENCE_ID"
    }

Đặt operatingAccount thành loại tài khoản và mã tài khoản sẽ nhận dữ liệu đối tượng.

Chuẩn bị dữ liệu về đối tượng

Hãy xem xét dữ liệu mẫu sau đây trong một tệp được phân tách bằng dấu phẩy. Mỗi dòng trong tệp tương ứng với một thành viên của đối tượng và mỗi thành viên có tối đa 3 địa chỉ email.

#,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,

Địa chỉ email có các yêu cầu sau về định dạng và băm:

Xoá tất cả khoảng trắng ở đầu, cuối và ở giữa.
Chuyển đổi địa chỉ email thành chữ thường.
Băm địa chỉ email bằng thuật toán SHA-256.
Mã hoá các byte băm bằng hệ thập lục phân (hex) hoặc phương thức mã hoá Base64. Các ví dụ trong hướng dẫn này sử dụng phương thức mã hoá thập lục phân.

Sau đây là dữ liệu đã được định dạng:

#,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,

Sau đây là dữ liệu sau khi được băm và mã hoá:

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

Dưới đây là một mẫu AudienceMember cho địa chỉ email đã được định dạng, băm và mã hoá của dana@example.com và danam@example.com từ hàng đầu tiên của dữ liệu đầu vào:

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

Tạo nội dung yêu cầu

Kết hợp Destination và userData cho nội dung yêu cầu:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "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
}

Cập nhật các phần giữ chỗ trong nội dung, chẳng hạn như OPERATING_ACCOUNT_TYPE, OPERATING_ACCOUNT_ID và AUDIENCE_ID bằng các giá trị cho tài khoản và đích đến của bạn.
Đặt validateOnly thành true để xác thực yêu cầu mà không áp dụng các thay đổi. Khi bạn đã sẵn sàng áp dụng các thay đổi, hãy đặt validateOnly thành false.
Đặt termsOfService để cho biết rằng người dùng đã chấp nhận Điều khoản dịch vụ về tính năng So khớp khách hàng.
Xin lưu ý rằng yêu cầu này cho biết consent được cấp và không sử dụng phương thức mã hoá.

Gửi yêu cầu

Sao chép nội dung yêu cầu bằng nút sao chép ở trên cùng bên phải của mẫu.
Nhấp vào nút API trên thanh công cụ.
Dán nội dung yêu cầu đã sao chép vào hộp Nội dung yêu cầu.
Nhấp vào nút Thực thi, hoàn tất lời nhắc uỷ quyền và xem xét phản hồi.

Phản hồi thành công

Yêu cầu thành công sẽ trả về một phản hồi có chứa một đối tượng requestId.

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

Ghi lại requestId được trả về để bạn có thể truy xuất thông tin chẩn đoán khi mỗi đích đến trong yêu cầu được xử lý.

Phản hồi thất bại

Yêu cầu không thành công sẽ dẫn đến mã trạng thái phản hồi lỗi, chẳng hạn như 400 Bad Request và phản hồi có thông tin chi tiết về lỗi.

Ví dụ: email_address chứa một chuỗi văn bản thuần tuý thay vì một giá trị được mã hoá hex sẽ tạo ra phản hồi sau:

{
  "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"
          }
        ]
      }
    ]
  }
}

Một email_address không được băm và chỉ được mã hoá theo hệ thập lục phân sẽ tạo ra phản hồi sau:

{
  "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"
          }
        ]
      }
    ]
  }
}

Gửi sự kiện cho nhiều đích đến

Nếu dữ liệu của bạn chứa các thành viên đối tượng cho nhiều đích đến, bạn có thể gửi họ trong cùng một yêu cầu bằng cách sử dụng thông tin tham chiếu về đích đến.

Ví dụ: nếu bạn có một thành viên đối tượng cho mã danh sách người dùng 11112222 và một thành viên đối tượng khác cho mã danh sách người dùng 77778888, hãy gửi cả hai thành viên đối tượng trong một yêu cầu bằng cách đặt reference của mỗi Destination. reference do người dùng xác định – yêu cầu duy nhất là mỗi Destination phải có một reference duy nhất. Sau đây là danh sách destinations đã sửa đổi cho yêu cầu:

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

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "77778888",
      "reference": "audience_2"
    }
  ]

Đặt destination_references của mỗi AudienceMember để gửi đến một hoặc nhiều đích đến cụ thể. Ví dụ: sau đây là một AudienceMember chỉ dành cho Destination đầu tiên, vì vậy, danh sách destination_references của AudienceMember này chỉ chứa reference của Destination đầu tiên:

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

Trường destination_references là một danh sách, vì vậy bạn có thể chỉ định nhiều đích đến cho một thành viên trong đối tượng. Nếu bạn không đặt destination_references của AudienceMember, Data Manager API sẽ gửi thành viên đối tượng đến tất cả các đích đến trong yêu cầu.

Các bước tiếp theo

Định cấu hình quy trình xác thực và thiết lập môi trường bằng một thư viện ứng dụng.
Tìm hiểu về các yêu cầu về định dạng, băm và mã hoá đối với từng loại dữ liệu.
Tìm hiểu cách mã hoá dữ liệu người dùng.
Tìm hiểu cách truy xuất thông tin chẩn đoán cho các yêu cầu của bạn.
Tìm hiểu về các phương pháp hay nhất.
Tìm hiểu về hạn mức và cuota.

Tổng quan về đối tượng