实施自定义出价

您可以使用 Display & Video 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 字段中列出的任何子级广告客户访问和修改。 广告客户拥有的算法可由该广告客户及其父级合作伙伴访问和修改，但无法与其他广告客户共享。

如果您仅为单个广告客户使用该算法，请使用 advertiserId 字段将该广告客户指定为所有者。否则，请使用 partnerId 字段将广告客户的父级合作伙伴分配为所有者，并使用 sharedAdvertiserIds 字段向广告客户授予访问权限。

上传脚本

创建自定义出价算法后，请为该算法创建一个脚本以供使用。基于脚本的自定义出价算法采用用户提供的脚本来评估展示机会的价值。您可以通过 Display & Video 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 方法将脚本文件上传到 Display & Video 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 对象应仅包含 CustomBiddingScriptRef 对象作为 script 字段的分配值。这会将上传的脚本文件与新的脚本资源相关联。

以下示例展示了如何创建脚本文件：

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

创建自定义出价脚本资源后，Display & Video 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"]}.')