Display & Video 360 API 第 3 版已停用。遷移至第 4 版。

本頁面由 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

建立規則物件

上傳 AlgorithmRules JSON 檔案後，請使用 customBiddingAlgorithms.rules.create 方法建立自訂出價演算法規則資源。在要求中傳遞的 CustomBiddingAlgorithmRules 物件，應只包含 CustomBiddingAlgorithmRulesRef 物件，做為 rules 欄位的指派值。這會將上傳的 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());

建立規則資源後，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

建立規則物件

Java

Python

PHP

指派自訂出價演算法

Java

Python

PHP

導入自訂出價

上傳 `AlgorithmRules` 檔案