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

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

您可以使用 Bulk Uploader API，在 Authorized Buyers 使用者名單中新增或移除廣告 ID，以便指定。

以下是 HTTPS Bulk Uploader API 網址範例：

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

端點接受 HTTPS POST 要求。

GoogleNetworkId 的值應為您的 Cookie 比對聯播網 ID (NID)，用來識別大量上傳工具和 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 Matching，並代管對照表。
使用對照表將 User-ID 轉換為 Google User-ID。
將 Google 使用者 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，即可在 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 User-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 端點。

舉例來說，如要將 IDFA 和合作夥伴提供的 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

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

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

status: NO_ERROR

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

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

如果所有作業都失敗，回應會包含 UpdateUsersDataResponse，且 status 設為 BAD_COOKIE：

status: BAD_COOKIE

範例

以下 Python 指令碼範例示範如何使用 cookie-batch-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