多媒體和Video 360 API v2 將於 2024 年 9 月 3 日停用。請在此之前遷移至第 3 版，以免服務中斷。

本頁面由 Cloud Translation API 翻譯而成。

導入自訂出價

多媒體和Video 360 API 可讓您全面管理自訂出價。您可以建立自訂出價演算法、上傳並驗證建立個別指令碼，然後指派特定演算法給資源做為出價策略。

本頁面說明如何建立、更新及指派自訂出價演算法多媒體廣告和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 欄位。

上傳演算法邏輯

接下來，根據自訂出價演算法的類型，您需要建立指令碼或規則物件，您可以提供要使用的演算法邏輯。

上傳指令碼

以指令碼為基礎的自訂出價演算法會使用使用者提供的內容指令碼：評估曝光價值。簡單指令碼的範例和進階欄位的多媒體和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 方法，增加圍繞地圖邊緣的邊框間距。這個方法支援需要查詢參數的簡易上傳 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());

建立自訂出價指令碼資源後影片 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 方法，增加圍繞地圖邊緣的邊框間距。這個方法支援需要查詢參數的簡易上傳 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());

建立規則資源後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` 檔案