カスタム入札の実装

ディスプレイ＆ビデオ 360 API を使用して、カスタム入札の実装を管理できます。カスタム入札アルゴリズムを作成し、個々のスクリプトをアップロードして検証し、特定のアルゴリズムを入札戦略としてリソースに割り当てることができます。

このページでは、Display & Video 360 API を使用してカスタム入札アルゴリズムを作成、更新、割り当てる方法について説明します。各セクションにはコードサンプルが用意されています。

カスタム入札アルゴリズムを作成する

CustomBiddingAlgorithm オブジェクトは、広告申込情報に割り当てて入札戦略で使用できる個々のアルゴリズムを表します。このオブジェクトには、アルゴリズムの詳細（customBiddingAlgorithmType、entityStatus、customBiddingAlgorithmState など）が含まれています。アルゴリズムで使用する子リソースとして CustomBiddingScript オブジェクトを作成できます。

スクリプトベースのカスタム入札アルゴリズムを作成する方法の例を次に示します。

Python

# Create a custom bidding algorithm object.
custom_bidding_algorithm_obj = {
    'advertiserId': advertiser-id,
    'displayName': display-name,
    'entityStatus': 'ENTITY_STATUS_ACTIVE',
    'customBiddingAlgorithmType': 'SCRIPT_BASED'
}

# Create the custom bidding algorithm.
response = service.customBiddingAlgorithms().create(
    body=algorithm_obj
).execute()

# Display the new custom bidding algorithm.
print(f'The following Custom Bidding Algorithm was created: {response}')

アルゴリズムへのアクセスを管理する

カスタム入札アルゴリズムは、パートナーまたは広告主様が所有できます。パートナーが所有するアルゴリズムには、そのパートナーと sharedAdvertiserIds フィールドに記載されている子広告主がアクセスして変更できます。広告主が所有するアルゴリズムには、その広告主と親パートナーがアクセスして変更できますが、他の広告主と共有することはできません。

アルゴリズムを 1 つの広告主に対してのみ使用する場合は、advertiserId フィールドを使用して、広告主を所有者として割り当てます。それ以外の場合は、広告主の親パートナーを partnerId フィールドで所有者として割り当て、sharedAdvertiserIds フィールドで広告主にアクセス権を付与します。

スクリプトをアップロードする

カスタム入札アルゴリズムを作成したら、そのアルゴリズムで使用するスクリプトを作成します。スクリプトベースのカスタム入札アルゴリズムでは、ユーザーが提供したスクリプトを使用してインプレッションの価値を評価します。シンプルなスクリプトのサンプルと高度なフィールドのリストは、ディスプレイ＆ビデオ 360 ヘルプセンターで確認できます。

以降のセクションでは、新しいスクリプトまたは更新されたスクリプトをカスタム入札アルゴリズムに追加する方法について説明します。

スクリプト リソースのロケーションを取得する

まず、customBiddingAlgorithms.uploadScript メソッドを使用して、カスタム入札アルゴリズム リソースで使用可能なリソースの場所を取得します。このリクエストは、リソース名を含む CustomBiddingScriptRef オブジェクトを返します。リソース名で指定された場所にスクリプト ファイルをアップロードできます。次に、カスタム入札スクリプト参照オブジェクトを使用してスクリプト リソースを作成します。

使用可能なリソースのロケーションを取得する方法の例を次に示します。

Python

# Retrieve a usable custom bidding script reference
# object.
custom_bidding_script_ref = service.customBiddingAlgorithms().uploadScript(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id
).execute()

# Display the new custom bidding script reference object.
print('The following custom bidding script reference object was retrieved:'
      f'{custom_bidding_script_ref}')

スクリプト ファイルをアップロードする

使用可能なリソースの場所を取得したら、media.upload メソッドを使用して、ディスプレイ＆ビデオ 360 システムのその場所にスクリプト ファイルをアップロードします。このメソッドは、クエリ パラメータ uploadType=media を必要とするシンプルなアップロードをサポートします。

取得したカスタム入札スクリプト参照オブジェクトを指定してスクリプト ファイルをアップロードする例を次に示します。

Python

# Create a media upload object.
media = MediaFileUpload(script-path)

# Create upload request.
upload_request = service.media().upload(
    resourceName=resource-name, media_body=media)

# Override response handler to expect null response.
upload_request.postproc = HttpRequest.null_postproc

# Upload script to resource location given in retrieved custom bidding
# script reference object.
upload_request.execute()

スクリプト オブジェクトを作成する

スクリプト ファイルをアップロードしたら、customBiddingAlgorithms.scripts.create メソッドを使用してカスタム入札スクリプト リソースを作成します。リクエストで渡される CustomBiddingScript オブジェクトには、script フィールドの割り当て値として CustomBiddingScriptRef オブジェクトのみを含める必要があります。これにより、アップロードされたスクリプト ファイルが新しいスクリプト リソースに関連付けられます。

スクリプト ファイルの作成方法の例を次に示します。

Python

# Create a custom bidding script object.
script_obj = {
    'script': custom-bidding-script-ref
}

# Create the custom bidding script.
response = service.customBiddingAlgorithms().scripts().create(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id,
    body=script_obj).execute()

# Display the new custom bidding script object.
print(f'The following custom bidding script was created: {response}')

カスタム入札スクリプト リソースを作成すると、ディスプレイ＆ビデオ 360 でスクリプトが処理され、インプレッションのスコアリングに正常に使用できることが確認されます。スクリプト オブジェクトの state フィールドを使用して、この処理の状態を取得します。新しいスクリプトが承認されると、カスタム入札アルゴリズムはスクリプトを使用してインプレッションの価値のスコア付けを開始します。これはすぐに実行されるため、新しいスクリプト リソースを作成する前に、アルゴリズムを更新するかどうかを必ず確認してください。

カスタム入札アルゴリズムを割り当てる

カスタム入札アルゴリズムを作成し、承認済みのスクリプトをアップロードして、必要な要件を満たしたら、カスタム入札アルゴリズムを広告申込情報または広告掲載オーダーの入札戦略に割り当てることができます。

BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO とカスタム入札アルゴリズム ID をそれぞれ performanceGoalType フィールドと customBiddingAlgorithmId フィールドに割り当てることで、費用最大化入札戦略とパフォーマンス目標入札戦略でカスタム入札アルゴリズムを使用できます。入札戦略によっては、他の入札パラメータが使用可能または必須になる場合があります。

次の例は、特定のカスタム入札アルゴリズムで費用最大化入札戦略を使用するように広告申込情報を更新する方法を示しています。

Python

# Create the new bid strategy object.
bidding_strategy = {
    'maximizeSpendAutoBid': {
        'performanceGoalType':
            'BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO',
        'customBiddingAlgorithmId': custom-bidding-algorithm-id
    }
}

# Create a line item object assigning the new bid strategy.
line_item_obj = {'bidStrategy': bidding_strategy}

# Update the line item with a new bid strategy.
response = service.advertisers().lineItems().patch(
    advertiserId=advertiser-id,
    lineItemId=line-item-id,
    updateMask='bidStrategy',
    body=line_item_obj).execute()

# Display the line item's new bid strategy
print(f'Line Item {response["name"]} is now using the following bid'
     f' strategy: {response["bidStrategy"]}.')