Przegląd

Pliki uporządkowanych danych (SDF) to specjalnie sformatowane pliki z wartościami rozdzielanymi przecinkami (CSV) pliki używane do pobierania i aktualizowania danych o reklamach displayowych Zasoby Video 360 w masowych. W sieci reklamowej Video 360 API, można generować i pobierać niestandardowe pliki SDF, pozwala uzyskać uporządkowane, filtrowane dane z sieci reklamowej Film sferyczny i zasobami Google Cloud.

W tym przewodniku opisujemy, jak utworzyć operację pobierania SDF, śledzić ją i pobrać powstałe pliki SDF.

Informacje o formacie SDF i obsłudze wersji znajdziesz w Dokumentacja referencyjna SDF

Tworzenie zadania

Pliki SDF są generowane w ramach operacji asynchronicznej o nazwie sdfdownloadtask. Podczas tworzenia tego zadania definiujesz parametry związane z odpowiednimi plikami SDF. Odbywa się to metodą sdfdownloadtasks.create. Parametry, które można ustawić, są opisane w podsekcjach poniżej.

Określ wersję

Format pliku uporządkowanych danych jest regularnie aktualizowany niezależnie od Reklamy displayowe i Interfejs Video 360 API z nowymi i starymi wersjami regularnie wycofywane. Z tego powodu zawsze zalecamy korzystanie z najnowszej wersji pliku SDF.

Wersję pliku SDF wybranego pliku SDF możesz ustawić za pomocą version w treści żądania. Jeśli wartość nie jest ustawiona na SDF_VERSION_UNSPECIFIED, zadanie będzie korzystać z domyślnej wersji SDF pliku reklamodawca lub zasób partnera używany jako kontekst treści SDF.

Uwaga: każdy zasób partnera ma ustawioną domyślną wersję pliku SDF w „Informacje podstawowe” ustawień w interfejsie API. O ile nie skonfigurowano inaczej, reklamodawcy dziedziczą tę wartość domyślną od partnera nadrzędnego.

Określanie kontekstu

Możesz wygenerować plik SDF zawierający dane o dowolnych dostępnych zasobach, ale każdy pojedynczy plik SDF może zwrócić treści tylko w kontekście partnera lub reklamodawcy. Ten kontekst jest zdefiniowany w treści żądania przez partnerId lub advertiserId. Dokładnie 1 z tych 2 – musisz określić te pola.

W wynikowym pliku SDF zostaną uwzględnione tylko zasoby w danym kontekście. Jeśli próbujesz filtrować według zasobu, który nie należy do podanego partnera ani reklamodawcę, ani ani ona, ani jej treści nie zostaną uwzględnione w wyników. Jeśli filtrujesz tylko według tych nieuwzględnionych zasobów, wynikowe pliki – wartość będzie pusta. Próba filtrowania według zasobów spoza danego kontekstu nie zwróci błędu, sprawdź więc, czy kontekst jest Zgadza się.

Wybierz odpowiedni filtr

Oprócz podanego powyżej kontekstu możesz dodatkowo filtrować zakres aby wygenerować pliki uporządkowanych danych, określając typy plików, które chcesz utworzyć. oraz konkretne zasoby lub rodzinę zasobów, które chcesz uwzględnić.

Uwaga: typ pliku uporządkowanych danych określa typ wypełnianego zasobu ten plik. Każdy typ pliku ma inną strukturę kolumn wraz z zasobami dostępnymi w przypadku tych zasobów.

W przypadku sdfdownloadtask są dostępne 3 filtry, z których każdy odpowiada konkretnego typu specyfikacji. Możesz przypisać tylko jeden element sdfdownloadtask

ParentEntityFilter

ParentEntityFilter to najszersza dostępna filtry.

W polu fileType możesz wymienić wszystkie typy plików, które chcesz wygenerować w ramach zadania. To jest jest wymagane. Jeśli pozostawisz puste pole lub wartość FILE_TYPE_UNSPECIFIED, sdfdownloadtask zakończy się błędem.

Korzystanie z filterType oraz filterIds, możesz dodatkowo zawęzić wyniki. filterType określa typ zasoby, według których chcesz filtrować, i filterIds identyfikuje te zasoby według unikalnego identyfikatora. Utworzone pliki SDF zawierają zasoby określone przez fileType, które są: zasoby (lub ich elementy podrzędne) zasobów wskazanych przez filterType i filterIds.

Uwaga: FILTER_TYPE_NONE nie zastosuje żadnego filtra do zadania, a jedynie ma zastosowanie, gdy określono element advertiserId. W przeciwnym razie po utworzeniu elementu sdfdownloadtask pojawi się błąd.

IdFilter

IdFilter filtruje żądanie, tak aby uwzględniało tylko zasoby i identyfikacji.

IdFilter zawiera pole na każdy typ pliku SDF z wyjątkiem zasobów reklamowych Źródło. Każde z tych pól zawiera listę unikalnych identyfikatorów identyfikujących konkretne zasoby, które chcesz uwzględnić w wygenerowanym pliku SDF. Podane identyfikatory muszą należeć do ustawionego kontekstu, ale nie muszą być bezpośrednio powiązane. Ty nie muszą żądać konkretnej kampanii, by przesłać prośbę o element zamówienia i odwrotnie. Wygenerowane zostaną tylko następujące typy plików: odpowiadające zasobom wskazanym w dokumencie IdFilter.

InventorySourceFilter

InventorySourceFilter umożliwia tylko filtrowanie oraz pobierania plików SDF zawierających zasoby źródła zasobów reklamowych. Jest to jedyny filtr, za pomocą którego można uzyskać informacje o zasobach źródła zasobów reklamowych.

InventorySourceFilter ma liczbę pojedynczą inventorySourceIds, w którym identyfikujesz unikalny Identyfikatory zasobów źródeł zasobów reklamowych, które chcesz uwzględnić w pliku SDF. Jeśli lista podana do inventorySourceIds jest pusta, wszystkie źródła zasobów reklamowych w określonym kontekście zostaną uwzględnione w wygenerowanym pliku SDF.

Poproś

Po zapoznaniu się z parametrami odpowiedniego pliku SDF możesz utworzyć żądanie i utwórz sdfdownloadtask.

Ostrzeżenie: 1 użytkownik może mieć maksymalnie 20 uruchomionych aplikacji sdfdownloadtasks jednorazowo. Próba utworzenia kolejnych spowoduje zwrócenie błędu.

Oto przykład, jak utworzyć sdfdownloadtask za pomocą 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 uzyskiwanie ścieżki pobierania

Gdy tworzysz obiekt sdfdownloadtask, obiekt operation jest . Ta operacja reprezentuje stan asynchronicznego pliku SDF podczas tworzenia. Możesz sprawdzić swoją operację, aby: sprawdzić, czy przesyłanie zostało zakończone i jest gotowe do pobrania lub czy wystąpił błąd, używając metodę sdfdownloadtasks.operations.get.

Uwaga: w zależności od rozmiaru generowanych plików SDF operacja może potrwać może trwać od kilku sekund do kilku godzin. Aby oszczędzać limit, wprowadzamy zwiększony wykładniczy czas do ponowienia, taki jak ten widoczny w poniższym kodzie.

Po zakończeniu zwrócona operacja będzie miała wartość inną niż null done. Ukończona operacja będzie zawierać jeden z elementów: response lub error . Jeśli pole error jest obecne, Obiekt Status zawierający kod błędu i wiadomość zawierającą szczegóły błędu, który wystąpił . Jeśli pole response jest obecne, będzie miał obiekt z wartością resourceName, która identyfikuje wygenerowany do pobrania.

Oto przykład sposobu sprawdzenia żądania za pomocą wykładniczego 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']
);