Przegląd

Pliki uporządkowanych danych (SDF) to specjalnie sformatowane pliki CSV (z wartościami rozdzielanymi przecinkami), które służą do zbiorczego pobierania i aktualizowania danych o zasobach Display & Video 360. Za pomocą interfejsu Display & Video 360 API możesz generować i pobierać dostosowane pliki SDF, co umożliwia pobieranie uporządkowanych i filtrowanych danych o zasobach Display & Video 360.

Z tego przewodnika dowiesz się, jak utworzyć operację pobierania pliku SDF, śledzić ją i pobrać wynikowe pliki SDF.

Informacje o formacie SDF i wersjach znajdziesz w dokumentacji referencyjnej SDF.

Tworzenie zadania

Pliki SDF są generowane przez operację asynchroniczną, zwaną sdfdownloadtask. Podczas tworzenia tego zadania określasz parametry dotyczące wybranych plików SDF. Odbywa się to za pomocą metody sdfdownloadtasks.create. W podsekcjach poniżej znajdziesz opis parametrów, które możesz ustawić.

Określanie wersji

Format pliku uporządkowanych danych jest regularnie aktualizowany niezależnie od interfejsu Display & Video 360 API. Nowe wersje są udostępniane, a starsze są regularnie wycofywane. Z tego powodu zawsze zalecamy korzystanie z najnowszej wersji plików SDF.

Wersję SDF wybranego pliku SDF ustawiasz za pomocą pola version w treści żądania. Jeśli nie zostanie ustawiona lub będzie miała wartość SDF_VERSION_UNSPECIFIED, zadanie będzie używać domyślnej wersji SDF zasobu reklamodawcy lub partnera używanego jako kontekst treści SDF.

Ustawianie kontekstu

Możesz wygenerować plik SDF zawierający dane o dowolnych dostępnych zasobach, ale każdy plik SDF może zwracać treści tylko w kontekście jednego partnera lub reklamodawcy. Ten kontekst jest definiowany w treści żądania przez pole partnerId lub advertiserId. Musisz ustawić dokładnie jedno z tych 2 pól.

Wynikowy plik SDF będzie zawierać tylko zasoby w danym kontekście. Jeśli spróbujesz filtrować według zasobu, który nie należy do określonego partnera lub reklamodawcy, ani on, ani zawarte w nim treści nie zostaną uwzględnione w wynikach. Jeśli filtrujesz tylko według tych nieuwzględnionych zasobów, wynikowe pliki będą puste. Próba filtrowania według zasobów spoza danego kontekstu nie spowoduje błędu, więc sprawdź, czy kontekst jest prawidłowy.

Wybierz odpowiedni filtr

Oprócz kontekstu ustawionego powyżej możesz dodatkowo filtrować zakres wygenerowanych plików danych strukturalnych, określając typy plików, które chcesz wygenerować, oraz konkretne zasoby lub rodziny zasobów, które chcesz uwzględnić.

W przypadku sdfdownloadtask dostępne są 3 filtry, z których każdy jest dostosowany do określonego typu specyfikacji. Możesz przypisać tylko 1 element do pojedynczego sdfdownloadtask.

ParentEntityFilter

ParentEntityFilter to najszerszy z dostępnych filtrów.

W polu fileType możesz wyświetlić listę wszystkich typów plików, które chcesz wygenerować w ramach zadania. Jest to wymagane. Jeśli to pole pozostanie puste lub będzie miało wartość FILE_TYPE_UNSPECIFIED, sdfdownloadtask zakończy się błędem.

Za pomocą pól filterTypefilterIds możesz dodatkowo zawęzić wyniki. filterType określa typ zasobów, według którego ma nastąpić filtrowanie, a filterIds identyfikuje te zasoby na podstawie ich unikalnego identyfikatora. Wynikowe pliki SDF będą zawierać zasoby zidentyfikowane przez fileType, które są zasobami lub elementami podrzędnymi zasobów zidentyfikowanych przez filterTypefilterIds.

IdFilter

IdFilter filtruje żądanie, aby uwzględniało tylko zidentyfikowane zasoby.

IdFilter ma pole dla każdego typu pliku SDF z wyjątkiem źródła danych o asortymencie. Każde z tych pól to lista unikalnych identyfikatorów określających zasoby, które chcesz uwzględnić w wygenerowanym pliku SDF. Podane identyfikatory muszą należeć do danego kontekstu, ale nie muszą być ze sobą bezpośrednio powiązane. Nie musisz prosić o konkretną kampanię, aby poprosić o zawarty w niej element zamówienia, i odwrotnie. Wygenerowane zostaną tylko te typy plików, które odpowiadają zasobom zidentyfikowanym w IdFilter.

InventorySourceFilter

InventorySourceFilter umożliwia tylko filtrowanie i pobieranie plików SDF zawierających zasoby źródła zasobów reklamowych. Jest to jedyny filtr, którego możesz używać do uzyskiwania informacji o zasobach Źródło zasobów reklamowych.

InventorySourceFilter ma pole pojedyncze inventorySourceIds, w którym określasz unikalne identyfikatory zasobów źródła zasobów reklamowych, które chcesz uwzględnić w pliku SDF. Jeśli lista podana w parametrze inventorySourceIds jest pusta, w wygenerowanym pliku SDF zostaną uwzględnione wszystkie źródła zasobów reklamowych w ustawionym kontekście.

Poproś

Gdy poznasz parametry wybranego pliku SDF, możesz utworzyć żądanie i plik sdfdownloadtask.

Ten przykład pokazuje, jak utworzyć obiekt sdfdownloadtask za pomocą elementu ParentEntityFilter:

Java

// Create the filter structure
ParentEntityFilter parentEntityFilter = new ParentEntityFilter();
parentEntityFilter.setFileType(sdf-file-type-list);
parentEntityFilter.setFilterType(sdfFilterType);
parentEntityFilter.setFilterIds(filter-id-list);

// Configure the sdfdownloadtasks.create request
Sdfdownloadtasks.Create request =
   service
       .sdfdownloadtasks()
       .create(
           new CreateSdfDownloadTaskRequest()
               .setVersion(sdfVersion)
               .setAdvertiserId(advertiserId)
               .setParentEntityFilter(parentEntityFilter)
       );

// Create the sdfdownloadtask
Operation operationResponse = request.execute();

System.out.printf("Operation %s was created.\n",
   operationResponse.getName());

Python

# Configure the sdfdownloadtasks.create request
createSdfDownloadTaskRequest = {
    'version': sdf-version,
    'advertiserId': advertiser-id,
    'parentEntityFilter': {
        'fileType': sdf-file-type-list,
        'filterType': sdf-filter-type,
        'filterIds': filter-id-list
    }
}

# Create the sdfdownloadtask
operation = service.sdfdownloadtasks().create(
    body=createSdfDownloadTaskRequest).execute();

print("Operation %s was created." % operation["name"])

PHP

// Create the sdfdownloadtasks.create request structure
$createSdfDownloadTaskRequest =
    new Google_Service_DisplayVideo_CreateSdfDownloadTaskRequest();
$createSdfDownloadTaskRequest->setAdvertiserId(advertiser-id);
$createSdfDownloadTaskRequest->setVersion(sdf-version);

// Create and set the parent entity filter
$parentEntityFilter = new Google_Service_DisplayVideo_ParentEntityFilter();
$parentEntityFilter->setFileType(sdf-file-type-list);
$parentEntityFilter->setFilterType(sdf-filter-type);
if (!empty(filter-id-list)) {
    $parentEntityFilter->setFilterIds(filter-id-list);
}
$createSdfDownloadTaskRequest->setParentEntityFilter($parentEntityFilter);

// Call the API, creating the SDF Download Task.
$operation = $this->service->sdfdownloadtasks->create(
    $createSdfDownloadTaskRequest
);

printf('Operation %s was created.\n', $operation->getName());

Sprawdzanie żądania i pobieranie ścieżki pobierania

Gdy tworzysz sdfdownloadtask, zwracany jest obiekt operation. Ta operacja przedstawia stan asynchronicznej operacji generowania pliku SDF w momencie tworzenia. Możesz sprawdzić, czy operacja została zakończona i jest gotowa do pobrania, czy też wystąpił błąd, korzystając z metody sdfdownloadtasks.operations.get.

wprowadź wycofywanie wykładnicze, takie jak w przykładowym kodzie poniżej.

Po zakończeniu zwrócona operacja będzie miała pole done o wartości innej niż null. Zakończona operacja będzie zawierać pole response lub error. Jeśli występuje pole error, zawiera ono obiekt Statuskodem błędukomunikatem, który zawiera szczegóły błędu, jaki wystąpił. Jeśli pole response jest obecne, będzie zawierać obiekt z wartością resourceName, która identyfikuje wygenerowany plik do pobrania.

Oto przykład sprawdzania żądania za pomocą wzrastającego czasu do ponowienia:

Java

String operationName = operationResponse.getName();

// Configure the Operations.get request
Sdfdownloadtasks.Operations.Get operationRequest =
   service
       .sdfdownloadtasks()
       .operations()
       .get(operationName);

// Configure exponential backoff for checking the status of our operation
ExponentialBackOff backOff = new ExponentialBackOff.Builder()
   .setInitialIntervalMillis(5000) // setting initial interval to five seconds
   .setMaxIntervalMillis(300000)  // setting max interval to five minutes
   .setMaxElapsedTimeMillis(18000000) // setting max elapsed time to five hours
   .build();

while (operationResponse.getDone() == null) {
 long backoffMillis = backOff.nextBackOffMillis();
 if (backoffMillis == ExponentialBackOff.STOP) {
   System.out.printf("The operation has taken more than five hours to
       complete.\n");
   return;
 }
 Thread.sleep(backoffMillis);

 // Get current status of operation
 operationResponse = operationRequest.execute();
}

// Check if the operation finished with an error and return
if (operationResponse.getError() != null) {
 System.out.printf("The operation finished in error with code %s: %s\n",
     operationResponse.getError().getCode(), operationResponse.getError()
         .getMessage());
 return;
}

System.out.printf(
    "The operation completed successfully. Resource %s was created.\n",
    operationResponse.getResponse().get("resourceName").toString());

Python

# The following values control retry behavior while
# the report is processing.
# Minimum amount of time between polling requests. Defaults to 5 seconds.
min_retry_interval = 5
# Maximum amount of time between polling requests. Defaults to 5 minutes.
max_retry_interval = 5 * 60
# Maximum amount of time to spend polling. Defaults to 5 hours.
max_retry_elapsed_time = 5 * 60 * 60

# Configure the Operations.get request
get_request = service.sdfdownloadtasks().operations().get(
  name=operation["name"]
)

sleep = 0
start_time = time.time()
while True:
  # Get current status of operation
  operation = get_request.execute()

  if "done" in operation:
    if "error" in operation:
      print("The operation finished in error with code %s: %s" % (
            operation["error"]["code"],
            operation["error"]["message"]))
    else:
      print("The operation completed successfully. Resource %s was created."
            % operation["response"]["resourceName"])
    break
  elif time.time() - start_time > max_retry_elapsed_time:
    print("Generation deadline exceeded.")

  sleep = next_sleep_interval(sleep)
  print("Operation still running, sleeping for %d seconds." % sleep)
  time.sleep(sleep)

def next_sleep_interval(previous_sleep_interval):
  """Calculates the next sleep interval based on the previous."""
  min_interval = previous_sleep_interval or min_retry_interval
  max_interval = previous_sleep_interval * 3 or min_retry_interval
  return min(max_retry_interval, random.randint(min_interval, max_interval))

PHP

// The following values control retry behavior
// while the task is processing.
// Minimum amount of time between polling requests. Defaults to 5 seconds.
$minRetryInterval = 5;
// Maximum amount of time between polling requests. Defaults to 5 minutes.
$maxRetryInterval = 300;
// Maximum amount of time to spend polling. Defaults to 5 hours.
$maxRetryElapsedTime = 18000;

$operationName = $operation->getName();

$sleepInterval = 0;
$startTime = time();

while (!$operation->getDone()) {
    if ($sleepInterval != 0) {
        printf(
            'The operation is still running, sleeping for %d seconds\n',
            $sleepInterval
        );
    }

    // Sleep before retrieving the SDF Download Task again.
    sleep($sleepInterval);

    // Call the API, retrieving the SDF Download Task.
    $operation = $this->service->sdfdownloadtasks_operations->get(
        $operation->getName()
    );

    // If the operation has exceeded the set deadline, throw an exception.
    if (time() - $startTime > $maxRetryElapsedTime) {
        printf('SDF download task processing deadline exceeded\n');
        throw new Exception(
            'Long-running operation processing deadline exceeded'
        );
    }

    // Generate the next sleep interval using exponential backoff logic.
    $sleepInterval = min(
        $maxRetryInterval,
        rand(
            max($minRetryInterval, $previousSleepInterval),
            max($minRetryInterval, $previousSleepInterval * 3)
        )
    );
}

// If the operation finished with an error, throw an exception.
if($operation->getError() !== null) {
    $error = $operation->getError();
    printf(
        'The operation finished in error with code %s: %s\n',
        $error->getCode(),
        $error->getMessage()
    );
    throw new Exception($error->getMessage());
}

// Print successfully generated resource.
$response = $operation->getResponse();
printf(
    'The operation completed successfully. Resource %s was '
        . 'created. Ready to download.\n',
    $response['resourceName']
);