カスタム入札の実装

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

このページでは、Display & Video 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 フィールドに一覧表示されているすべての子広告主がアクセスし、変更を加えることができます。広告主が所有するアルゴリズムは、その広告主と親パートナーがアクセスして変更できますが、他の広告主と共有することはできません。

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

アップロードのアルゴリズム ロジック

カスタム入札アルゴリズムのタイプに応じて、次に、使用するアルゴリズムのロジックを記述できるスクリプトまたは rules オブジェクトを作成する必要があります。

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

スクリプトベースのカスタム入札アルゴリズムでは、ユーザー提供のスクリプトを使用してインプレッションの価値を評価します。シンプル スクリプトのサンプルと詳細フィールドの一覧については、ディスプレイ &ビデオ 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

ルール オブジェクトを作成する

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 とパートナーの広告申込情報を取得する
次へ
広告申込情報を有効にする