Display & Video 360 API v3 はサポートを終了しました。v4 への移行。

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

カスタム入札の実装

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

このページでは、ディスプレイ＆ビデオ 360 API を使用してカスタム入札アルゴリズムを作成、更新、割り当てる方法について説明します。各セクションにコードサンプルを示します。

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

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

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

Java

// Create the custom bidding algorithm structure.
CustomBiddingAlgorithm customBiddingAlgorithm =
    new CustomBiddingAlgorithm()
        .setAdvertiserId(advertiser-id)
        .setDisplayName(display-name)
        .setEntityStatus("ENTITY_STATUS_ACTIVE")
        .setCustomBiddingAlgorithmType("SCRIPT_BASED");

// Configure the create request.
CustomBiddingAlgorithms.Create request =
    service.customBiddingAlgorithms().create(customBiddingAlgorithm);

// Create the custom bidding algorithm.
CustomBiddingAlgorithm response = request.execute();

// Display the new custom bidding algorithm name.
System.out.printf(
    "Custom bidding algorithm %s was created.%n",
    response.getName()
);

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=custom_bidding_algorithm_obj
).execute()

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

PHP

// Create a custom bidding algorithm object.
$customBiddingAlgorithm =
    new Google_Service_DisplayVideo_CustomBiddingAlgorithm();
$customBiddingAlgorithm->setAdvertiserId(advertiser-id);
$customBiddingAlgorithm->setDisplayName(display-name);
$customBiddingAlgorithm->setEntityStatus('ENTITY_STATUS_ACTIVE');
$customBiddingAlgorithm->setCustomBiddingAlgorithmType('SCRIPT_BASED');

// Create the custom bidding algorithm.
$result =
    $this->service->customBiddingAlgorithms->create($customBiddingAlgorithm);

// Display the new custom bidding algorithm name.
printf('Custom Bidding Algorithm %s was created.\n', $result['name']);

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

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

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

アルゴリズムロジックをアップロードする

次に、カスタム入札アルゴリズムのタイプに応じて、スクリプトまたはルールオブジェクトを作成します。このオブジェクトには、アルゴリズムで使用するロジックを指定できます。

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

スクリプトベースのカスタム入札アルゴリズムは、ユーザー提供のスクリプトを使用してインプレッションの価値を評価します。シンプルなスクリプトのサンプルと高度なフィールドのリストについては、ディスプレイ＆ビデオ 360 ヘルプセンターをご覧ください。

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

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

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

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

Java

// Retrieve a usable custom bidding script
// reference.
CustomBiddingScriptRef scriptRef =
    service
        .customBiddingAlgorithms()
        .uploadScript(custom-bidding-algorithm-id)
        .setAdvertiserId(advertiser-id)
        .execute();

// Display the custom bidding script reference resource path.
System.out.printf(
    "The script can be uploaded to the following resource path: %s%n",
    scriptRef.getResourceName()
);

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}')

PHP

// Set parent advertiser ID of custom bidding
// algorithm in optional parameters array for request.
$optParams = array('advertiserId' => advertiser-id);

// Retrieve a usable custom bidding script reference.
$scriptRefResponse = $this->service->customBiddingAlgorithms->uploadScript(
    custom-bidding-algorithm-id,
    $optParams
);

// Display the new custom bidding script reference object.
printf(
    'The script can be uploaded to the following resource path: %s\n',
    $scriptRefResponse->getResourceName()
);

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

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

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

Java

// Create media object.
GoogleBytestreamMedia media = new GoogleBytestreamMedia();
media.setResourceName(resource-name);

// Create input stream for the script file.
InputStreamContent scriptFileStream =
    new InputStreamContent(
        null, new FileInputStream(script-path));

// Create media.upload request.
Media.Upload uploadRequest =
        service
            .media()
            .upload(
                resource-name,
                media,
                scriptFileStream);

// Retrieve uploader from the request and set it to us a simple
// upload request.
MediaHttpUploader uploader = uploadRequest.getMediaHttpUploader();
uploader.setDirectUploadEnabled(true);

// Execute the upload using an Upload URL with the destination resource
// name.
uploader
    .upload(
        new GenericUrl(
            "https://displayvideo.googleapis.com/upload/media/"
                + resource-name));

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()

PHP

// Create a media object.
$mediaBody = new Google_Service_DisplayVideo_GoogleBytestreamMedia();
$mediaBody->setResourceName(resource-name);

// Set parameters for upload request.
$optParams = array(
    'data' => file_get_contents(script-path),
    'uploadType' => 'media',
    'resourceName' => resource-name
);

// Upload script file to given resource location.
$this->service->media->upload(
    resource-name,
    $mediaBody,
    $optParams
);

cURL

curl --request POST 'https://displayvideo.googleapis.com/upload/media/resource-name?uploadType=media' 
  -H 'authorization: Bearer access-token'
  -H 'Content-Type: text/plain'
  --data-binary @script-path

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

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

スクリプトリソースを作成する方法の例を次に示します。

Java

// Create the custom bidding script structure.
CustomBiddingScript customBiddingScript =
    new CustomBiddingScript()
        .setScript(custom-bidding-script-ref);

// Create the custom bidding script.
CustomBiddingScript response =
    service
        .customBiddingAlgorithms()
        .scripts()
        .create(custom-bidding-algorithm-id, customBiddingScript)
        .setAdvertiserId(advertiser-id)
        .execute();

// Display the new script resource name
System.out.printf(
    "The following script was created: %s%n",
    response.getName());

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}')

PHP

// Create the custom bidding script object.
$customBiddingScript =
    new Google_Service_DisplayVideo_CustomBiddingScript();
$customBiddingScript->setScript(custom-bidding-script-ref);

// Set parameters for create script request.
$optParams = array(
    'advertiserId' => advertiser-id
);

// Create the custom bidding script.
$result = $this->service->customBiddingAlgorithms_scripts->create(
    custom-bidding-algorithm-id,
    $customBiddingScript,
    $optParams
);

// Display the new script resource name.
printf('The following script was created: %s.\n', $result->getName());

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

ルールをアップロードする

ルールベースのカスタム入札アルゴリズムでは、AlgorithmRules オブジェクトで提供されるロジックを使用して、インプレッションの価値を評価します。

AlgorithmRules オブジェクトは JSON ファイルでアップロードされ、CustomBiddingAlgorithmRules オブジェクトを介してカスタム入札アルゴリズムに関連付けられます。

ルールリソースのロケーションを取得する

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

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

Java

// Create the custom bidding algorithm structure.
CustomBiddingAlgorithmRulesRef rulesRef =
    service
        .customBiddingAlgorithms()
        .uploadRules(custom-bidding-algorithm-id)
        .setAdvertiserId(advertiser-id)
        .execute();

System.out.printf(
    "The rules can be uploaded to the following resource path: %s%n",
    rulesRef.getResourceName()
);

Python

# Retrieve a usable custom bidding algorithm rules reference
# object.
custom_bidding_algorithm_rules_ref = service.customBiddingAlgorithms().uploadRules(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id
).execute()

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

PHP

// Set parent advertiser ID of custom bidding algorithm
// in optional parameters array for request.
$optParams = array('advertiserId' => advertiser-id);

// Retrieve a usable custom bidding algorithm rules reference.
$rulesRefResponse = $this->service->customBiddingAlgorithms->uploadRules(
    custom-bidding-algorithm-id,
    $optParams
);

// Display the new custom bidding algorithm rules reference object resource path.
printf(
    'The rules can be uploaded to the following resource path: %s\n',
    $rulesRefResponse->getResourceName()
);

`AlgorithmRules` ファイルをアップロードする

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

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

Java

// Create media object.
GoogleBytestreamMedia media = new GoogleBytestreamMedia();
media.setResourceName(resource-name);

// Create input stream for the rules file.
InputStreamContent rulesFileStream =
    new InputStreamContent(
        null, new FileInputStream(rules-file-path));

// Create media.upload request.
 Media.Upload uploadRequest =
    service
        .media()
        .upload(
            resource-name,
            media,
            rulesFileStream);

// Retrieve uploader from the request and set it to us a simple
// upload request.
MediaHttpUploader uploader = uploadRequest.getMediaHttpUploader();
uploader.setDirectUploadEnabled(true);

// Execute the upload using an Upload URL with the destination resource
// name.
uploader
    .upload(
        new GenericUrl(
            "https://displayvideo.googleapis.com/upload/media/"
                + resource-name));

Python

# Create a media upload object.
media = MediaFileUpload(rules-file-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 rules file to resource location given in retrieved custom bidding
# algorithm rules reference object.
upload_request.execute()

PHP

// Create a media object.
$mediaBody = new Google_Service_DisplayVideo_GoogleBytestreamMedia();
$mediaBody->setResourceName(resource-name);

// Set parameters for upload request.
$optParams = array(
    'data' => file_get_contents(rules-file-path),
    'uploadType' => 'media',
    'resourceName' => resource-name
);

// Upload rules file to given resource location.
$this->service->media->upload(
    resource-name,
    $mediaBody,
    $optParams
);

cURL

curl --request POST 'https://displayvideo.googleapis.com/upload/media/resource-name?uploadType=media' 
  -H 'authorization: Bearer access-token'
  -H 'Content-Type: text/plain'
  --data-binary @rules-file-path

rules オブジェクトを作成する

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

ルールリソースを作成する方法の例を次に示します。

Java

// Create the custom bidding algorithm rules structure.
CustomBiddingAlgorithmRules customBiddingAlgorithmRules =
    new CustomBiddingAlgorithmRules()
        .setRules(custom-bidding-algorithm-rules-ref);

// Create the rules resource.
CustomBiddingAlgorithmRules response =
    service
        .customBiddingAlgorithms()
        .rules()
        .create(custom-bidding-algorithm-id, customBiddingAlgorithmRules)
        .setAdvertiserId(advertiser-id)
        .execute();

// Display the new rules resource name.
System.out.printf(
    "The following custom bidding algorithm rules object was created: %s%n",
    response.getName());

Python

# Create the custom bidding algorithm rules object.
rules_obj = {
    'rules': custom-bidding-algorithm-rules-ref
}

# Create the rules resource.
response = service.customBiddingAlgorithms().rules().create(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id,
    body=rules_obj).execute()

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

PHP

// Create the custom bidding algorithm rules object.
$customBiddingAlgorithmRules =
    new Google_Service_DisplayVideo_CustomBiddingAlgorithmRules();
$customBiddingAlgorithmRules->setRules(custom-bidding-algorithm-rules-ref);

// Set parameters for create rules request.
$optParams = array(
    'advertiserId' => advertiser-id
);

// Create the custom bidding algorithm rules resource.
$result = $this->service->customBiddingAlgorithms_rules->create(
    custom-bidding-algorithm-id,
    $customBiddingAlgorithmRules,
    $optParams
);

// Display the new custom bidding algorithm rules resource name.
printf('The following rules resource was created: %s.\n', $result->getName());

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

ルールが拒否された場合は、ルールオブジェクトの error から拒否の理由を取得します。不承認の場合は、AlgorithmRules オブジェクトを更新してエラーを修正し、ルール参照オブジェクトの取得からアップロードプロセスを繰り返します。

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

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

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

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

Java

// Create the line item structure.
LineItem lineItem = new LineItem();

// Create and set the bidding strategy structure.
BiddingStrategy biddingStrategy = new BiddingStrategy();
MaximizeSpendBidStrategy maxSpendBidStrategy =
    new MaximizeSpendBidStrategy()
        .setPerformanceGoalType(
            "BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO")
        .setCustomBiddingAlgorithmId(custom-bidding-algorithm-id);
biddingStrategy.setMaximizeSpendAutoBid(maxSpendBidStrategy);
lineItem.setBidStrategy(biddingStrategy);

// Configure the patch request and set update mask to only update
// the bid strategy.
LineItems.Patch request =
    service
        .advertisers()
        .lineItems()
        .patch(advertiser-id, line-item-id, lineItem)
        .setUpdateMask("bidStrategy");

// Update the line item.
LineItem response = request.execute();

// Display the custom bidding algorithm ID used in the new
// bid strategy.
System.out.printf(
    "LineItem %s now has a bid strategy utilizing custom "
        + "bidding algorithm %s%n",
    response.getName(),
    response
        .getBidStrategy()
        .getMaximizeSpendAutoBid()
        .getCustomBiddingAlgorithmId());

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"]}.')

PHP

// Create the line item structure.
$lineItem = new Google_Service_DisplayVideo_LineItem();

// Create and set the bidding strategy structure.
$biddingStrategy =  new Google_Service_DisplayVideo_BiddingStrategy();
$maximizeSpendBidStrategy =
    new Google_Service_DisplayVideo_MaximizeSpendBidStrategy();
$maximizeSpendBidStrategy->setPerformanceGoalType(
    'BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO'
);
$maximizeSpendBidStrategy->setCustomBiddingAlgorithmId(
    custom-bidding-algorithm-id
);
$biddingStrategy->setMaximizeSpendAutoBid($maximizeSpendBidStrategy);
$lineItem->setBidStrategy($biddingStrategy);

// Set update mask.
$optParams = array('updateMask' => 'bidStrategy');

// Update the line item.
$result = $this->service->advertisers_lineItems->patch(
    advertiser-id,
    line-item-id,
    $lineItem,
    $optParams
);

// Display the custom bidding algorithm ID used in the new bid strategy.
printf(
    'Line Item %s now has a bid strategy utilizing custom bidding algorithm %s.\n',
    $result['name'],
    $result['bidStrategy']['maximizeSpendBidStrategy']['customBiddingAlgorithmId']
);

YouTube とパートナーの広告申込情報を取得する

広告申込情報を有効にする

カスタム入札の実装 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

Java

Python

PHP

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

アルゴリズム ロジックをアップロードする

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

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

Java

Python

PHP

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

Java

Python

PHP

cURL

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

Java

Python

PHP

ルールをアップロードする

ルールリソースのロケーションを取得する

Java

Python

PHP

AlgorithmRules ファイルをアップロードする

Java

Python

PHP

cURL

rules オブジェクトを作成する

Java

Python

PHP

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

Java

Python

PHP

カスタム入札の実装

アルゴリズムロジックをアップロードする

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

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

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

`AlgorithmRules` ファイルをアップロードする