本頁面由 Cloud Translation API 翻譯而成。

將廣告 ID 上傳到使用者名單

您可以使用 Bulk Manager API 為 Authorized Buyers 使用者名單新增及移除廣告 ID，以便指定目標。您無法使用 Authorized Buyers Bulk Manager API 修改 Display & Video 360 目標對象名單。

以下是 HTTPS 大量上傳器 API 網址範例：

https://cm.g.doubleclick.net/upload?nid={GoogleNetworkId}

端點接受 HTTPS POST 要求。

GoogleNetworkId 的值應為 Cookie 比對網路 ID (NID)，該 ID 可在大量上傳者和 Cookie 比對中識別您的帳戶。

HTTPS POST 要求的酬載是經過編碼的通訊協定緩衝區，用於描述要修改的清單。請參閱 cookie-bulk-upload-proto.txt 中的大量上傳工具服務的結構定義。每個要求的酬載大小上限為 100 KB。

如要進一步瞭解如何編譯及使用 cookie-bulk-upload.proto 來序列化及剖析訊息，請參閱您的偏好語言的教學課程。

您可以上傳下列 ID 類型：

Google 使用者 ID
合作夥伴提供的 ID
iOS 廣告識別碼
Android 廣告 ID
Roku ID
Amazon Fire TV ID
Xbox 或 Microsoft ID

上傳 Google 使用者 ID

Google 使用者 ID 是來自 doubleclick.net 網域的加密 ID。

上傳 Google 使用者 ID 的方法如下：

使用 Google 設定 Cookie 比對，並代管對照表。
使用對照表將使用者 ID 轉換為 Google User ID。
將 Google User ID 上傳到使用者名單。

舉例來說，如果您在 Cookie 比對期間收到以下內容：

https://ad.network.com/pixel?google_gid=CAESEHIV8HXNp0pFdHgi2rElMfk&google_cver=1

google_gid 參數是加密的 Google 使用者 ID。

如要將項目新增至使用者名單，請將其複製到 UpdateUsersDataRequest 內文：

ops {
  user_id: "CAESEHIV8HXNp0pFdHgi2rElMfk"
  user_list_id: 111
  delete: false
  user_id_type: GOOGLE_USER_ID
}

上傳合作夥伴提供的 ID

合作夥伴提供的 ID 是合作夥伴自有網域的 ID。以下說明如何上傳合作夥伴提供的 ID：

使用 Google 設定 Cookie 比對，並允許 Google 代管您的對照表。
將合作夥伴提供的 ID 上傳到使用者名單。

舉例來說，如果您將網域的使用者 ID 設為 123456，則該 ID 便可在 Google 的代管對照表中填入 Cookie 比對。比對標記應包含指派給 google_hm 參數的 ID 網路安全 base64 編碼版本，如下所示：
```
https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=MTIzNDU2&google_cm
```
接著，您可以使用 UpdateUsersDataRequest 將合作夥伴提供的 ID 上傳至使用者名單：
```
ops {
 user_id: "123456"
 user_list_id: 123
 delete: false
 user_id_type: PARTNER_PROVIDED_ID
}
```
接著，Google 會將使用者名單從合作夥伴提供的 ID 轉譯為 Google 使用者 ID，然後將 ID 加進您的使用者名單。

上傳 IDFA 或 Android 廣告 ID

也可以上傳裝置 ID。

使用 UpdateUsersDataRequest 上傳裝置 ID：

ops {
 user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A"
 user_list_id: 111
 delete: false
 user_id_type: IDFA
}

Google 會將使用者名單從裝置 ID 轉譯成 Google 使用者 ID，並將 ID 加進使用者名單。

工作流程

所有大量上傳者要求和回應範例皆以文字格式編寫。您必須將這些項目以序列化通訊協定緩衝區訊息傳送至 Bulk Uploader API 端點。

舉例來說，如要上傳廣告識別碼和合作夥伴提供的 ID 到使用者名單 123，請建立 UpdateUsersDataRequest：

ops {
  user_id: "2024D65F-EBBD-11FF-23AB-823FC255913A"
  user_list_id: 123
  delete: false
  user_id_type: IDFA
}
ops {
  user_id: "1234567"
  user_list_id: 123
  delete: false
  user_id_type: PARTNER_PROVIDED_ID
}
# See warning before use. Requires affirmative end-user consent.
process_consent: true

接著傳送 HTTPS POST 要求，並以序列化的 UpdateUsersDataRequest 訊息做為酬載。

如果所有作業都成功，您會收到下列 UpdateUsersDataResponse：

status: NO_ERROR

如果部分作業成功，回應會包含 UpdateUsersDataResponse，其中每項失敗的作業都有錯誤：

status: PARTIAL_SUCCESS
errors {
  user_id: "1234567"
  error_code: UNKNOWN_ID
  user_id_type: PARTNER_PROVIDED_ID
}

如果所有作業都未成功，回應會包含 status 設為 BAD_COOKIE 的 UpdateUsersDataResponse：

status: BAD_COOKIE

範例

這是 Python 指令碼範例，示範如何使用 cookie-bulk-upload.proto 產生的程式庫，透過大量上傳工具服務填入指定 ID 的使用者清單：

  #!/usr/bin/python
#
# Copyright 2023 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""A sample demonstrating usage of the Authorized Buyers Bulk Upload service.

Successfully running this example will add the provided ID to the given user
list. To learn more about the bulk uploader service, see:
https://developers.google.com/authorized-buyers/rtb/bulk-uploader
"""


import argparse

import gen.cookie_bulk_upload_pb2

import requests


BULK_UPLOAD_ENDPOINT_TEMPLATE = 'https://cm.g.doubleclick.net/upload?nid=%s'


def main(account_nid, user_list_id, user_id, user_id_type):
    # Build the bulk upload request.
    update_request = gen.cookie_bulk_upload_pb2.UpdateUsersDataRequest()
    update_request.send_notifications = True

    ops = update_request.ops
    op = ops.add()
    op.user_list_id = user_list_id
    op.user_id = user_id
    op.user_id_type = user_id_type

    user_id_type_value = gen.cookie_bulk_upload_pb2.UserIdType.Name(
        user_id_type)

    print(f'For NID "{account_nid}", adding user ID "{user_id}" of type '
          f'"{user_id_type_value}" to user list ID "{user_list_id}"')

    # Execute the bulk upload request.
    response = requests.post(BULK_UPLOAD_ENDPOINT_TEMPLATE % account_nid,
                             data=update_request.SerializeToString())

    # Parse and display the response.
    update_response = gen.cookie_bulk_upload_pb2.UpdateUsersDataResponse()
    update_response.ParseFromString(response.content)

    print('Operation completed with the following:')
    print(f'\tHTTP Status code: {response.status_code}')
    status_value = gen.cookie_bulk_upload_pb2.ErrorCode.Name(
        update_response.status)
    print(f'\tUpdateUsersDataResponse.status: {status_value}')
    print(f'\tUpdateUsersDataResponse.errors: {update_response.errors}')
    print('\tUpdateUsersDataResponse.notifications: '
          f'{update_response.notifications}')
    n_status_value = gen.cookie_bulk_upload_pb2.NotificationStatus.Name(
        update_response.notification_status)
    print(f'\tUpdateUsersDataResponse.notification_status: {n_status_value}')


if __name__ == '__main__':
    parser = argparse.ArgumentParser(
        description=('A sample demonstrating usage of the Authorized Buyers '
                     'bulk uploader service.'))
    parser.add_argument('-n', '--account_nid',
                        required=True, help='The Account NID.')
    parser.add_argument('-u', '--user_id',
                        required=True, help='The User ID to be added.')
    parser.add_argument('-l', '--user_list_id', type=int, required=True,
                        help='The user list that the ID is being added to.')
    parser.add_argument('-t', '--user_id_type', type=int, required=True,
                        help=('The type of user ID being added. See '
                              '"UserIdType" enum for more details.'))
    args = parser.parse_args()

    main(args.account_nid, args.user_list_id, args.user_id, args.user_id_type)

處理大量上傳要求的同意聲明

使用 Bulk Upload API 的合作夥伴必須證明自己有適當法律依據，才能使用 process_consent 參數與 Google 共用使用者資料，以進行大量上傳。這項規定適用於所有大量上傳要求。

如果根據 Google 的《歐盟地區使用者同意授權政策》(請參閱 https://www.google.com/about/company/user-consent-policy/) 或其他當地法律要求，且需要使用者同意的使用者資料，合作夥伴必須透過設定 process_consent=True 取得使用者同意，並表明已收集同意聲明。

針對不受使用者同意聲明規定規範的使用者資料，合作夥伴必須透過設定 process_consent=True 來表示不需要取得同意聲明。

系統會篩選缺少 process_consent 的要求並傳回下列錯誤：

status: MISSING_CONSENT_WILL_BE_DROPPED

系統會篩選 process_consent 設為 false 的要求並傳回下列錯誤：

status: MISSING_CONSENT