Pliki uporządkowanych danych (SDF) to specjalnie sformatowane pliki CSV (z wartościami rozdzielanymi przecinkami) używane do zbiorczego pobierania i aktualizowania danych o zasobach Display & Video 360. Za pomocą interfejsu Display & Video 360 API możesz generować i pobierać niestandardowe pliki SDF, co umożliwia pobieranie uporządkowanych, odfiltrowanych danych z zasobów Display & Video 360.
Z tego przewodnika dowiesz się, jak utworzyć operację pobierania plików SDF, śledzić ją i pobrać wynikowe pliki SDF.
Informacje na temat formatu SDF i obsługi wersji znajdziesz w dokumentacji referencyjnej dotyczącej plików SDF.
Tworzenie zadania
Pliki SDF są generowane w wyniku operacji asynchronicznej o nazwie sdfdownloadtask.
Podczas tworzenia tego zadania określasz parametry dotyczące odpowiednich plików SDF.
Użyjesz do tego metody sdfdownloadtasks.create. W podsekcjach poniżej opisujemy parametry, które możesz ustawiać.
Określ wersję
Format pliku uporządkowanych danych jest regularnie aktualizowany niezależnie od interfejsu Display & Video 360 API. Jego nowe wersje są udostępniane i regularnie wycofywane. Z tego powodu zawsze zalecamy, aby użytkownicy korzystali z najnowszej wersji pliku SDF.
Wersję SDF pliku SDF ustaw, korzystając z pola version w treści żądania. Jeśli zasada jest nieskonfigurowana lub ma wartość SDF_VERSION_UNSPECIFIED, zadanie będzie używać domyślnej wersji pliku SDF zasobu reklamodawcy lub partnera używanego jako kontekst treści SDF.
Określ kontekst
Możesz wygenerować plik SDF zawierający dane dotyczące dowolnych dostępnych dla Ciebie zasobów, ale każdy plik SDF może zwracać treści tylko wtedy, gdy pochodzą z kontekstu jednego partnera lub reklamodawcy. Ten kontekst jest zdefiniowany w treści żądania za pomocą pola partnerId lub advertiserId. Trzeba ustawić
dokładnie jedno z tych pól.
W wynikowym pliku SDF zostaną uwzględnione tylko zasoby z danego kontekstu. Jeśli spróbujesz przefiltrować dane według zasobu, który nie należy do określonego partnera lub reklamodawcy, ani ten zasób, ani jego zawartość 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 zwróci błędu, dlatego sprawdź, czy kontekst jest prawidłowy.
Wybierz odpowiedni filtr
Oprócz powyższego kontekstu możesz dodatkowo filtrować zakres wygenerowanych plików uporządkowanych danych, określając typy plików, które chcesz wygenerować, oraz konkretne zasoby lub ich rodziny.
W przypadku atrybutu sdfdownloadtask dostępne są 3 filtry. Każdy z nich odpowiada konkretnemu typowi specyfikacji. Możesz przypisać tylko 1 plik na potrzeby obiektu sdfdownloadtask.
ParentEntityFilter
ParentEntityFilter to najszerszy z dostępnych filtrów.
W polu fileType możesz wymienić wszystkie typy plików, które chcesz wygenerować w ramach zadania. Jest to wymagane. Jeśli pozostawisz to pole puste lub ustawisz wartość FILE_TYPE_UNSPECIFIED, formuła sdfdownloadtask zakończy się błędem.
Aby jeszcze bardziej zawęzić wyniki, możesz użyć pól filterType i filterIds.
filterType określa typ zasobów, według których chcesz filtrować, a filterIds identyfikuje je według unikalnego identyfikatora. Powstałe pliki SDF będą zawierać zasoby zidentyfikowane przez fileType, które są zasobami lub zasobami podrzędnymi w stosunku do zasobów określonych przez filterType i filterIds.
IdFilter
IdFilter filtruje żądanie, tak aby uwzględniało tylko zidentyfikowane zasoby.
IdFilter ma pole dla każdego typu pliku SDF z wyjątkiem źródła zasobów reklamowych. Każde z tych pól to lista unikalnych identyfikatorów identyfikujących konkretne zasoby, które chcesz uwzględnić w wygenerowanym pliku SDF. Podane identyfikatory muszą występować w zbiorze kontekstu, ale nie muszą być bezpośrednio powiązane. Nie musisz prosić o konkretną kampanię, aby wysłać żądanie elementu zamówienia, który zawiera, i odwrotnie. Wygenerowane zostaną tylko typy plików odpowiadające zasobom wskazanym w IdFilter.
InventorySourceFilter
InventorySourceFilter umożliwia filtrowanie i pobieranie tylko plików SDF zawierających zasoby źródła zasobów reklamowych. Jest to jedyny filtr, którego możesz używać do uzyskania informacji o zasobach źródeł zasobów reklamowych.
InventorySourceFilter zawiera pojedyncze pole inventorySourceIds, w którym wskazuje unikalne identyfikatory zasobów źródła zasobów reklamowych, które chcesz uwzględnić w pliku SDF. Jeśli lista podana w pliku inventorySourceIds jest pusta, w wygenerowanym pliku SDF zostaną uwzględnione wszystkie źródła zasobów reklamowych pochodzące z określonego kontekstu.
Poproś
Gdy znasz już parametry odpowiedniego pliku SDF, możesz utworzyć żądanie i utworzyć plik sdfdownloadtask.
Oto przykład tworzenia 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 utworzysz sdfdownloadtask, zwracany jest obiekt operation. Ta operacja przedstawia stan asynchronicznego generowania pliku SDF w chwili jego utworzenia. Za pomocą metody sdfdownloadtasks.operations.get możesz sprawdzić, czy operacja została zakończona, czy jest gotowa do pobrania czy też wystąpił błąd.
Po zakończeniu zwrócona operacja będzie zawierać niepuste pole done. Zakończona operacja będzie zawierać pole response lub error. Jeśli pole error jest obecne, będzie zawierać obiekt Status zawierający kod błędu i komunikat ze szczegółowymi informacjami o wystąpionym błędzie. Jeśli pole response jest obecne, będzie ono zawierać obiekt z wartością resourceName, która identyfikuje wygenerowany plik do pobrania.
Oto przykład sprawdzania żądania za pomocą wykładniczego 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']
);