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

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

Bulk Uploader API を使用すると、認定バイヤーのユーザーリストに対して広告 ID の追加や削除を行い、ターゲティングを行うことができます。

HTTPS Bulk Uploader API のサンプルを次に示します。

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 に設定されている場合は、Cookie マッチングを使用して、Google がホストするマッチテーブルにその ID を入力できます。マッチタグには、次のように、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
}
```
その後、ユーザーリストがパートナー提供の 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
}

次に、ユーザーリストがデバイス 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-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)

一括アップロードリクエストで同意を処理

一括アップロード API を利用するパートナーは、process_consent パラメータを使用して、一括アップロードの目的で Google とユーザーデータを共有する適切な法的根拠を提示する必要があります。この要件は、すべての一括アップロードリクエストに適用されます。

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