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 filterType
i filterIds
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 filterType
i filterIds
.
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
.
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 Status
z kodem błędu i komunikatem, 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'] );