Display & Video 360 API v3 已停用。迁移到 v4。

此页面由 Cloud Translation API 翻译。

实施自定义出价

借助 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 字段向广告客户授予访问权限。

上传算法逻辑

接下来，您需要根据自定义出价算法的类型创建脚本或规则对象，以便为算法提供要使用的逻辑。

上传脚本

基于脚本的自定义出价算法会使用用户提供的脚本来评估展示机会的价值。如需查看简单脚本示例和高级字段列表，请访问 Display & Video 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 方法将脚本文件上传到 Display & Video 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 对象应仅包含 CustomBiddingScriptRef 对象作为 script 字段的指定值。这会将上传的脚本文件与新的脚本资源相关联。

以下示例展示了如何创建脚本资源：

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

您创建自定义出价脚本资源后，Display & Video 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 方法将规则文件上传到 Display & Video 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 对象应仅包含 CustomBiddingAlgorithmRulesRef 对象作为 rules 字段的指定值。这会将上传的 AlgorithmRules JSON 文件与新的规则资源相关联。

以下示例展示了如何创建 Rules 资源：

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

您创建规则资源后，Display & Video 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` 文件