Wdrażanie stawek niestandardowych

Interfejs Display & Video 360 API umożliwia pełne zarządzanie wdrożeniami ustalania stawek niestandardowych. Możesz tworzyć algorytmy ustalania stawek niestandardowych, przesyłać i weryfikować poszczególne skrypty oraz przypisywać określony algorytm do zasobu jako jego strategię ustalania stawek.

Z tego artykułu dowiesz się, jak tworzyć, aktualizować i przypisywać algorytmy ustalania stawek niestandardowych za pomocą interfejsu Display & Video 360 API. Każda sekcja zawiera przykładowy kod.

Tworzenie algorytmu ustalania stawek niestandardowych

Obiekt CustomBiddingAlgorithm to pojedynczy algorytm, który możesz przypisać do elementu zamówienia, aby używać go w jego strategii ustalania stawek. Ten obiekt zawiera szczegółowe informacje o algorytmie, np. customBiddingAlgorithmType i entityStatus, a także elementy readinessState i suspensionState wygenerowane dla poszczególnych modeli poszczególnych reklamodawców. Jako zasoby podrzędne dla algorytmu możesz tworzyć obiekty CustomBiddingScript i CustomBiddingAlgorithmRules.

Oto przykład tworzenia algorytmu ustalania stawek niestandardowych na podstawie skryptu:

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']);

Zarządzaj dostępem do algorytmu

Algorytmy ustalania stawek niestandardowych mogą należeć do partnera lub reklamodawcy. Algorytmy należące do partnera są dostępne i modyfikowane przez niego oraz wszystkich reklamodawców podrzędnych wymienionych w polu sharedAdvertiserIds. Algorytmy należące do reklamodawcy mogą być dostępne dla tego reklamodawcy i jego partnera nadrzędnego, ale nie mogą być udostępniane innym reklamodawcom.

Jeśli używasz algorytmu tylko w przypadku 1 reklamodawcy, przypisz mu rolę właściciela w polu advertiserId. W przeciwnym razie przypisz w polu partnerId nadrzędnego partnera reklamodawców jako właściciela i przyznaj reklamodawcom dostęp za pomocą pola sharedAdvertiserIds.

Logika algorytmu przesyłania

W zależności od typu algorytmu ustalania stawek niestandardowych musisz utworzyć obiekt skrypt lub reguły, w którym podasz logikę wykorzystywane przez algorytm.

Prześlij skrypt

Algorytmy ustalania stawek niestandardowych oparte na skryptach wykorzystują skrypty dostarczone przez użytkownika, które oceniają wartość wyświetleń. Przykłady prostych skryptów i lista zaawansowanych pól są dostępne w Centrum pomocy Display & Video 360.

W sekcjach poniżej dowiesz się, jak dodać nowy lub zaktualizowany skrypt do algorytmu ustalania stawek niestandardowych.

Pobieranie lokalizacji zasobu skryptu

Najpierw pobierz lokalizację zasobu w ramach zasobu algorytmu ustalania stawek niestandardowych, korzystając z metody customBiddingAlgorithms.uploadScript. To żądanie zwraca obiekt CustomBiddingScriptRef z nazwą zasobu. Możesz przesłać plik skryptu do lokalizacji określonej przez nazwę zasobu. Następnie użyj obiektu referencyjnego skryptu ustalania stawek niestandardowych, aby utworzyć zasób skryptu.

Oto przykład pobierania dostępnej lokalizacji zasobu:

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

Prześlij plik skryptu

Po pobraniu dostępnej lokalizacji zasobu prześlij do niej plik skryptu w systemie Display & Video 360, korzystając z metody media.upload. Ta metoda obsługuje proste przesyłanie, które wymaga parametru zapytania uploadType=media.

Oto przykład, jak przesłać plik skryptu z pobranym obiektem referencyjnym niestandardowego skryptu ustalania stawek:

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

Tworzenie obiektu skryptu

Po przesłaniu pliku skryptu utwórz zasób skryptu ustalania stawek niestandardowych za pomocą metody customBiddingAlgorithms.scripts.create. Obiekt CustomBiddingScript przekazany w żądaniu powinien zawierać tylko obiekt CustomBiddingScriptRef jako przypisaną wartość pola script. Spowoduje to powiązanie przesłanego pliku skryptu z nowym zasobem skryptu.

Oto przykład tworzenia zasobu skryptu:

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

Gdy utworzysz zasób skryptu ustalania stawek niestandardowych, Display & Video 360 przetwarza ten skrypt, by zapewnić, że będzie można go używać do oceniania wyświetleń. Pobierz stan przetwarzania za pomocą pola state obiektu skryptu. Po zaakceptowaniu nowego skryptu algorytm ustalania stawek niestandardowych zaczyna używać skryptu do oceniania wartości wyświetleń. Dzieje się to natychmiast, więc zanim utworzysz nowy zasób skryptu, musisz zaktualizować algorytm.

Reguły przesyłania

Algorytmy ustalania stawek niestandardowych na podstawie reguł oceniają wartość wyświetlenia za pomocą funkcji dostępnych w obiekcie AlgorithmRules.

Obiekty AlgorithmRules są przesyłane w pliku JSON, a następnie wiązane z algorytmem ustalania stawek niestandardowych za pomocą obiektu CustomBiddingAlgorithmRules.

Pobieranie lokalizacji zasobu reguł

Najpierw pobierz lokalizację zasobu w ramach zasobu algorytmu ustalania stawek niestandardowych, korzystając z metody customBiddingAlgorithms.uploadRules. To żądanie zwraca obiekt CustomBiddingAlgorithmsRulesRef z nazwą zasobu. Plik reguł możesz przesłać do lokalizacji określonej przez nazwę zasobu. Następnie użyj obiektu referencyjnego algorytmu ustalania stawek niestandardowych, aby utworzyć zasób reguł.

Oto przykład pobierania dostępnej lokalizacji zasobu:

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

Prześlij plik AlgorithmRules

Po pobraniu dostępnej lokalizacji zasobu prześlij plik reguł do tej lokalizacji w systemie Display & Video 360, korzystając z metody media.upload. Ta metoda obsługuje proste przesyłanie, które wymaga parametru zapytania uploadType=media.

Oto przykład przesyłania pliku AlgorithmRules z pobranym obiektem referencyjnym reguł algorytmu ustalania stawek niestandardowych:

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

Tworzenie obiektu reguł

Po przesłaniu pliku JSON AlgorithmRules utwórz zasób reguł algorytmu ustalania stawek niestandardowych za pomocą metody customBiddingAlgorithms.rules.create. Obiekt CustomBiddingAlgorithmRules przekazany w żądaniu powinien zawierać tylko obiekt CustomBiddingAlgorithmRulesRef jako przypisaną wartość pola rules. Spowoduje to powiązanie przesłanego pliku JSON AlgorithmRules z nowym zasobem reguł.

Oto przykład tworzenia zasobu reguł:

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

Gdy utworzysz zasób reguł, Display & Video 360 przetworzy zestaw reguł, by umożliwić korzystanie z niego do oceniania wyświetleń. Pobierz stan tego przetwarzania za pomocą pola state obiektu reguł. Po zaakceptowaniu nowych reguł algorytm ustalania stawek niestandardowych zaczyna od razu używać ich do oceny wartości wyświetleń.

Jeśli reguły zostaną odrzucone, pobierz przyczynę odrzucenia z właściwości error obiektu reguł. W przypadku odrzucenia zaktualizuj obiekt AlgorithmRules, aby naprawić błąd, i powtórz proces przesyłania, zaczynając od pobrania obiektu referencyjnego reguł.

Przypisywanie algorytmu ustalania stawek niestandardowych

Gdy utworzysz algorytm ustalania stawek niestandardowych, prześlesz zaakceptowane zasady i spełnisz niezbędne wymagania, możesz przypisać ten algorytm do strategii ustalania stawek elementu zamówienia lub zamówienia reklamowego.

W strategiach ustalania stawek pod kątem maksymalizacji wydatków i celu skuteczności możesz ich używać, przypisując BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO i identyfikator algorytmu ustalania stawek niestandardowych do pól performanceGoalType i customBiddingAlgorithmId. W zależności od strategii ustalania stawek inne parametry stawki mogą być dostępne lub wymagane.

Oto przykład tego, jak zaktualizować element zamówienia, aby korzystać ze strategii ustalania stawek Maksymalizacja wydatków z danym algorytmem ustalania stawek niestandardowych:

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']
);
Wstecz
Pobierz elementy zamówienia typu YouTube i sieć partnerów wideo Google
Dalej
Aktywowanie elementu zamówienia