API Display & Video 360 v2 больше не используется. Вместо этого используйте Display & Video 360 API v3 . Инструкции по переходу с версии 2 на версию 3 см. в нашем руководстве по миграции .

Эта страница переведена с помощью Cloud Translation API.

Внедрение специальных ставок

API Display & Video 360 позволяет полностью управлять реализацией специальных ставок . Вы можете создавать собственные алгоритмы назначения ставок, загружать и проверять отдельные сценарии, а также назначать ресурсу определенный алгоритм в качестве стратегии назначения ставок.

На этой странице описано, как создавать, обновлять и назначать специальные алгоритмы назначения ставок с помощью API Display & Video 360. В каждом разделе приведен пример кода.

Создайте собственный алгоритм назначения ставок

Объект CustomBiddingAlgorithm представляет собой отдельный алгоритм, который можно назначить позиции для использования в ее стратегии назначения ставок. Этот объект содержит подробные сведения об алгоритме, такие как customBiddingAlgorithmType entityStatus , а также readinessState и suspensionState для каждой созданной модели соответствующего рекламодателя. Вы можете создать объекты CustomBiddingScript и CustomBiddingAlgorithmRules в качестве дочерних ресурсов для использования алгоритмом.

Ниже приведен пример создания алгоритма специального назначения ставок на основе скрипта:

Ява

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

Питон

# 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 с именем ресурса . Вы можете загрузить файл сценария в место, указанное именем ресурса. Затем используйте объект ссылки на сценарий специального назначения ставок, чтобы создать ресурс сценария .

Вот пример того, как получить доступное местоположение ресурса:

Ява

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

Питон

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

Загрузите файл сценария

После получения доступного местоположения ресурса загрузите файл сценария в это место в системе Display & Video 360 с помощью метода media.upload . Этот метод поддерживает простую загрузку , для которой требуется параметр запроса uploadType=media .

Ниже приведен пример загрузки файла сценария с учетом полученного справочного объекта сценария специального назначения ставок:

Ява

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

Питон

# 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 --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 . Это связывает загруженный файл сценария с новым ресурсом сценария.

Вот пример того, как создать ресурс скрипта:

Ява

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

Питон

# 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 с именем ресурса . Вы можете загрузить файл правил в место, указанное именем ресурса. Затем используйте объект ссылки на правила алгоритма специального назначения ставок, чтобы создать ресурс правил .

Вот пример того, как получить доступное местоположение ресурса:

Ява

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

Питон

# 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`

После получения доступного местоположения ресурса загрузите файл правил в это место в системе Display & Video 360 с помощью метода media.upload . Этот метод поддерживает простую загрузку , для которой требуется параметр запроса uploadType=media .

Ниже приведен пример загрузки файла AlgorithmRules с использованием полученного справочного объекта правил специального алгоритма назначения ставок:

Ява

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

Питон

# 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 --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

Создать объект правил

После загрузки JSON-файла AlgorithmRules создайте ресурс правил специального алгоритма назначения ставок с помощью метода customBiddingAlgorithms.rules.create . Объект CustomBiddingAlgorithmRules , передаваемый в запросе, должен включать только объект CustomBiddingAlgorithmRulesRef в качестве назначенного значения поля rules . Это связывает загруженный файл AlgorithmRules JSON с новым ресурсом правил.

Вот пример того, как создать ресурс правил:

Ява

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

Питон

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

После того как вы создадите ресурс правил, Дисплей и Видео 360 обрабатывает набор правил, чтобы убедиться, что его можно успешно использовать для оценки показов. Получите состояние этой обработки через поле state объекта правил. Как только новые правила будут приняты, алгоритм специального назначения ставок немедленно начнет использовать эти правила для оценки ценности показов.

Если правила отклонены, извлеките причину отклонения из error объекта правил. В случае отклонения обновите объект AlgorithmRules , чтобы исправить ошибку, и повторите процесс загрузки, начиная с получения объекта ссылки на правила .

Назначьте специальный алгоритм назначения ставок

После того как вы создадите собственный алгоритм назначения ставок, загрузите принятую логику и выполните необходимые требования , вы сможете назначить свой собственный алгоритм назначения ставок стратегии назначения ставок позиции или заказа на размещение.

Вы можете использовать специальные алгоритмы назначения ставок в стратегиях максимизации затрат и достижения цели по эффективности , назначив BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO и идентификатор специального алгоритма назначения полям performanceGoalType и customBiddingAlgorithmId соответственно. В зависимости от стратегии назначения ставок могут быть доступны или необходимы другие параметры ставок.

Ниже приведен пример того, как обновить позицию, чтобы использовать стратегию максимальной ставки с заданным специальным алгоритмом назначения ставок:

Ява

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

Питон

# 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 и партнеров

Активировать позицию

Внедрение специальных ставок

Создайте собственный алгоритм назначения ставок

Ява

Питон

PHP

Управление доступом к алгоритму

Загрузить логику алгоритма

Загрузить скрипт

Получить расположение ресурса скрипта

Ява

Питон

PHP

Загрузите файл сценария

Ява

Питон

PHP

КУЛЬ

Создайте объект сценария

Ява

Питон

PHP

Правила загрузки

Получить расположение ресурса правил

Ява

Питон

PHP

Загрузите файл AlgorithmRules

Ява

Питон

PHP

КУЛЬ

Создать объект правил

Ява

Питон

PHP

Назначьте специальный алгоритм назначения ставок

Ява

Питон

PHP

Загрузите файл `AlgorithmRules`