導入自訂出價

您可以使用 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"]}.')