このページは Cloud Translation API によって翻訳されました。

広告 ID をユーザーリストにアップロードする

Bulk Uploader API を使用すると、認定バイヤーのユーザーリストに対して広告 ID の追加や削除を行い、ターゲティングに使用できます。認定バイヤーの Bulk Uploader API を使用してディスプレイ&ビデオ 360 のオーディエンスリストを変更することはできません。

HTTPS Bulk Uploader API の URL の例を次に示します。

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

エンドポイントは HTTPS POST リクエストを受け入れます。

GoogleNetworkId の値には、一括アップロードと Cookie マッチングでアカウントを一意に識別する Cookie マッチングネットワーク ID（NID）を指定します。

HTTPS POST リクエストのペイロードは、エンコードされたプロトコルバッファで、変更するリストを記述します。一括アップロードサービスのスキーマについては、cookie-bulk-upload-proto.txt をご覧ください。各リクエストのペイロードは 100 KB に制限されています。

cookie-bulk-upload.proto をコンパイルして使用してメッセージのシリアル化と解析を行う方法については、ご使用の言語のチュートリアルをご覧ください。

アップロードできる識別子のタイプは次のとおりです。

Google ユーザー ID
パートナー指定の ID
iOS の IDFA
Android 広告 ID
Roku ID
Amazon Fire TV ID
Xbox または Microsoft ID

Google ユーザー ID をアップロード

Google ユーザー ID は、doubleclick.net ドメインの暗号化された ID です。

Google ユーザー ID をアップロードする方法は次のとおりです。

Google で Cookie マッチングをセットアップし、マッチテーブルをホストします。
マッチテーブルを使用して、ユーザー ID を Google ユーザー 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 マッチングを使用してユーザー ID を入力できます。マッチタグには、次のように、google_hm パラメータに割り当てられたウェブセーフな base64 エンコード版の ID を含める必要があります。
```
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 に変換し、ユーザーリストに追加します。

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 に変換し、ユーザーリストに追加します。

ワークフロー

一括アップロードのリクエストとレスポンスの例はすべて、テキスト形式で記述されています。シリアル化されたプロトコルバッファメッセージとして、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
}

どのオペレーションも成功しなかった場合、レスポンスには 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 の EU ユーザーの同意ポリシー（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