Os arquivos de dados estruturados (SDFs, na sigla em inglês) são arquivos de valores separados por vírgulas (CSV) formatados especialmente para recuperar e atualizar dados em massa sobre os recursos do Display & Video 360. Com a API Display & Video 360, é possível gerar e fazer o download de SDFs personalizados, permitindo que você recupere dados organizados e filtrados nos seus recursos do Display & Video 360.
Este guia descreve como criar uma operação de download de SDF, rastrear essa operação e fazer o download dos SDFs resultantes.
As informações sobre o formato e o controle de versões do SDF podem ser encontradas na documentação de referência do SDF.
Criar uma tarefa
Os SDFs são gerados por uma operação assíncrona, chamada sdfdownloadtask.
Ao criar essa tarefa, você define os parâmetros relacionados aos SDFs desejados.
Isso é feito usando o método sdfdownloadtasks.create. As
subseções a seguir descrevem os parâmetros que podem ser definidos.
Especificar uma versão
O formato do arquivo de dados estruturados é atualizado regularmente de maneira independente da API Display & Video 360, e novas versões são lançadas, e as antigas são descontinuadas regularmente. Por esse motivo, sempre recomendado que os usuários usem a versão mais recente do SDF.
Defina a versão do SDF do SDF desejado usando o campo version no corpo da solicitação. Se não for definida ou for definida
como SDF_VERSION_UNSPECIFIED, a tarefa vai usar a versão SDF padrão do
recurso de anunciante ou parceiro usado como o contexto do conteúdo do SDF.
Defina o contexto
É possível gerar um SDF com dados sobre quaisquer recursos disponíveis para você, mas
qualquer SDF individual só pode retornar conteúdo no contexto de um único
parceiro ou anunciante. Esse contexto é definido no corpo da solicitação pelo campo partnerId ou advertiserId. Exatamente um desses dois
campos precisa ser definido.
Somente os recursos dentro do contexto determinado serão incluídos no SDF resultante. Se você tentar filtrar por um recurso que não pertence ao parceiro ou anunciante especificado, nem ele nem o conteúdo dele serão incluídos nos resultados. Se você filtrar apenas por esses recursos não incluídos, os arquivos resultantes estarão vazios. A tentativa de filtrar por recursos fora do contexto fornecido não vai retornar um erro. Portanto, verifique se o contexto está correto.
Escolha o filtro certo
Além do conjunto de contexto acima, é possível filtrar ainda mais o escopo dos arquivos de dados estruturados gerados especificando os tipos de arquivo que você quer gerar e os recursos ou a família de recursos específicos que quer incluir.
Há três filtros disponíveis para um sdfdownloadtask, cada um atendendo a
um tipo específico de especificação. Só é possível atribuir um para um único
sdfdownloadtask.
ParentEntityFilter
ParentEntityFilter é o mais amplo dos filtros
disponíveis.
Usando o campo fileType, é possível listar todos os
tipos de arquivo que você quer gerar com sua tarefa. Isso é
obrigatório, e, se deixado em branco ou definido como FILE_TYPE_UNSPECIFIED, seu
sdfdownloadtask será concluído por engano.
Usando os campos filterType e filterIds, é possível refinar ainda mais seus resultados.
filterType especifica o tipo de
recursos que serão filtrados e filterIds
os identifica pelo ID exclusivo. Os SDFs resultantes incluirão
os recursos identificados por fileType que são
os recursos ou filhos dos recursos identificados por
filterType e filterIds.
IdFilter
IdFilter filtra a solicitação para incluir apenas os recursos
identificados.
IdFilter tem um campo para cada tipo de SDF, exceto a origem de
inventário. Cada um desses campos é uma lista de IDs exclusivos que identificam os
recursos específicos que você quer incluir no SDF gerado. Os IDs fornecidos
precisam estar dentro do conjunto de contexto, mas não precisam estar diretamente relacionados. Não é necessário solicitar uma campanha específica para solicitar o item de linha que ela contém, e vice-versa. Os únicos tipos de arquivo gerados serão aqueles
correspondentes aos recursos identificados em IdFilter.
InventorySourceFilter
O InventorySourceFilter só permite a filtragem
e o download de SDFs que contêm recursos de origem de inventário. Ele é o único filtro que pode ser usado para conseguir informações sobre seus recursos de origem de inventário.
InventorySourceFilter tem um campo
inventorySourceIds único em que você identifica os IDs
exclusivos dos recursos de origem de inventário que quer incluir no SDF. Se a
lista fornecida ao inventorySourceIds estiver vazia, todas
as origens de inventário no contexto definido vão ser incluídas no SDF gerado.
Fazer uma solicitação
Depois de conhecer os parâmetros do SDF, crie a solicitação
e o sdfdownloadtask.
Confira um exemplo de como criar uma sdfdownloadtask usando um
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());
Verifique sua solicitação e veja o caminho do download
Quando você cria uma sdfdownloadtask, um objeto de operação é retornado. Essa operação representa o status da operação assíncrona de geração de SDF no momento da criação. Use o método sdfdownloadtasks.operations.get para verificar se a operação foi
concluída e pronta para download ou se gerou um erro.
Após a conclusão, a operação retornada terá um campo
done não nulo. A operação concluída incluirá um campo response ou error. Se estiver presente, o campo error terá um objeto Status contendo um código de erro e uma mensagem, que fornece detalhes do erro ocorrido. Se o campo response estiver presente, ele
terá um objeto com um valor resourceName que identifica o arquivo
gerado para download.
Confira um exemplo de como verificar sua solicitação usando a espera exponencial:
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']
);