Visão geral

Os arquivos de dados estruturados (SDFs, na sigla em inglês) são formatados especialmente em valores separados por vírgula (CSV). arquivos usados para recuperar e atualizar dados sobre os Recursos do Video 360 no em massa. Com as campanhas a API do Video 360, é possível gerar e fazer o download de SDFs, permitindo que você recupere dados organizados e filtrados nas tabelas de Google Video 360 do Google Cloud.

Este guia descreve como criar uma operação de download de SDF, rastrear operação e faça o download dos SDFs resultantes.

Informações sobre o formato do SDF e o controle de versões podem ser encontradas no Documentação de referência do SDF.

Criar uma tarefa

Os SDFs são gerados por uma operação assíncrona, chamada de sdfdownloadtask. Ao criar essa tarefa, você define os parâmetros relacionados aos SDFs desejados. Isso é feito usando o método sdfdownloadtasks.create. A as subseções a seguir descrevem os parâmetros que você pode definir.

Especificar uma versão

O formato do Arquivo de Dados Estruturados é atualizado regularmente independentemente da Rede de Display e API Video 360, com novas versões lançadas e versões antigas descontinuados regularmente. Por isso, sempre recomendou que os usuários usassem a versão mais recente do SDF.

Defina a versão do SDF do SDF desejado usando o version no corpo da solicitação. Se não for definido ou definido como SDF_VERSION_UNSPECIFIED, a tarefa usará a versão SDF padrão da anunciante ou parceiro usado como contexto do conteúdo do SDF.

Observação: cada recurso de parceiro tem uma versão padrão do SDF configurada no "Detalhes básicos" configurações na API. A menos que seja configurado de outra forma, os anunciantes herdam esse padrão do parceiro pai.

Defina o contexto

É possível gerar um SDF contendo dados sobre quaisquer recursos disponíveis, mas qualquer SDF individual só pode retornar conteúdo dentro do contexto de um único parceiro ou anunciante. Esse contexto é definido no corpo da solicitação por a partnerId ou advertiserId. Exatamente um destes dois devem ser definidos.

Somente os recursos no contexto fornecido serão incluídos no SDF resultante. Se você tentar filtrar por um recurso que não pertence ao parceiro especificado anunciante, nem ele nem o conteúdo dele será incluído no resultados. Se você filtrar apenas por esses recursos não incluídos, os arquivos resultantes estará vazio. Tentativa de filtrar por recursos fora do contexto fornecido não retornará um erro, portanto, verifique se o contexto está correto.

Escolha o filtro certo

Além do contexto definido acima, é possível filtrar ainda mais o escopo dos gerou arquivos de dados estruturados especificando os tipos de arquivo que você deseja gerar e os recursos específicos ou a família de recursos que você quer incluir.

Observação :o tipo de um arquivo de dados estruturados determina o tipo de recurso que será preenchido esse arquivo. Cada tipo de arquivo tem uma estrutura de colunas diferente. refletindo as informações disponíveis para esse recurso.

Há três filtros disponíveis para uma sdfdownloadtask, cada um atendendo a um tipo específico de especificação. Só é possível atribuir um item a um único sdfdownloadtask:

ParentEntityFilter

ParentEntityFilter é o mais amplo dos disponíveis filtros.

Usando o campo fileType, é possível listar todos os itens tipos de arquivo que você quer gerar com a tarefa. Isso é obrigatório e, se deixado em branco ou definido como FILE_TYPE_UNSPECIFIED, seu sdfdownloadtask será concluído por engano.

Usar as APIs filterType e filterIds, é possível refinar ainda mais os resultados. filterType especifica o tipo de recursos para filtrar e filterIds identifica esses recursos pelo ID exclusivo deles. Os SDFs resultantes incluirão os recursos identificados por fileType que são os recursos ou filhos dos recursos identificados filterType e filterIds.

Observação: FILTER_TYPE_NONE não vai aplicar nenhum filtro à tarefa, mas só aplicável quando advertiserId é especificado. Caso contrário, será retornado um erro na criação da sdfdownloadtask.

IdFilter

O IdFilter filtra sua solicitação para incluir apenas os recursos identificados.

IdFilter tem um campo para cada tipo de SDF, exceto inventário. Fonte. Cada um desses campos é uma lista de IDs exclusivos que identificam o 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. Você não precisa solicitar uma campanha específica para solicitar um item de linha. contém e vice-versa. Os únicos tipos de arquivo gerados serão aqueles correspondentes aos recursos identificados no IdFilter.

InventorySourceFilter

InventorySourceFilter só permite a filtragem. e o download de SDFs que contêm recursos de origem de inventário. Ele é o único filtro que você pode usar para conseguir informações sobre seus recursos de origem de inventário.

InventorySourceFilter tem um singular inventorySourceIds em que você identifica o IDs dos recursos de origem de inventário que você quer incluir no SDF. Se o a lista fornecida para inventorySourceIds está vazia, todos as origens de inventário no contexto definido serão incluídas no SDF gerado.

Fazer uma solicitação

Depois de conhecer os parâmetros do SDF desejado, é possível criar a solicitação e criar o sdfdownloadtask.

Aviso: um único usuário está limitado a vinte sdfdownloadtasks em execução a qualquer uma vez. Se você tentar criar mais conteúdo, um erro será exibido.

Veja um exemplo de como criar uma sdfdownloadtask usando uma 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 acesse o caminho de download

Quando você cria um sdfdownloadtask, um objeto operation é retornados. Esta operação representa o status do seu SDF assíncrono no momento da criação. Você pode verificar a operação veja se ele foi concluído e está pronto para download, ou se gerou um erro, usando o método sdfdownloadtasks.operations.get.

Observação: dependendo do tamanho dos SDFs que estão sendo gerados, sua operação pode demorar desde alguns segundos até algumas horas. Para economizar cota, introduzir uma espera exponencial, como a mostrada no exemplo de código abaixo.

Após a conclusão, a operação retornada terá um valor não nulo done. A operação concluída incluirá um response ou error . Se estiver presente, o campo error terá uma Objeto Status que contém um código de erro e mensagem, que fornece detalhes do erro que o incidente. Se o campo response estiver presente, ele terá um objeto com um valor resourceName que identifica o para download.

Veja 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']
);