Descripción general

Los archivos de datos estructurados (SDF) tienen un formato de valores separados por comas (CSV) con formato especial archivos utilizados para recuperar y actualizar datos sobre Display & Recursos de Video 360 en de forma masiva. A través de la pantalla y con la API de Video 360, puedes generar y descargar SDF personalizados, lo que te permite recuperar datos organizados y filtrados en tus campañas Video 360 de Google Cloud.

En esta guía, se describe cómo crear una operación de descarga de SDF, realizar un seguimiento de y descarga los SDF resultantes.

Puedes encontrar información sobre el formato y el control de versiones de SDF en la Documentación de referencia de SDF.

Cómo crear una tarea

Los SDF se generan mediante una operación asíncrona llamada sdfdownloadtask. Cuando crees esta tarea, definirás los parámetros en relación con tus SDF deseados. Esto se hace a través del método sdfdownloadtasks.create. El En las siguientes subsecciones, se describen los parámetros que puedes establecer.

Especifica una versión

El formato de archivo de datos estructurados se actualiza con regularidad, independientemente de la Anuncios gráficos y API de Video 360, con versiones nuevas lanzadas y versiones anteriores dejan de estar disponibles con regularidad. Por este motivo, es se recomienda que los usuarios usen la versión más reciente del SDF.

Debes configurar la versión de SDF del SDF que desees usando el version en el cuerpo de la solicitud. Si no se establece o no se establece a SDF_VERSION_UNSPECIFIED, la tarea usará la versión predeterminada de SDF de la recurso del anunciante o socio utilizado como contexto del contenido de SDF.

Establece el contexto

Puedes generar un SDF que contenga datos en cualquier recurso disponible para ti, pero Cualquier SDF individual solo puede devolver contenido dentro del contexto de un único socio o anunciante. Este contexto se define en el cuerpo de la solicitud por el partnerId o advertiserId. Exactamente uno de estos dos se deben configurar campos.

Solo los recursos dentro del contexto dado se incluirán en el SDF resultante. Si intentas filtrar por un recurso que no es propiedad del socio especificado ni de su contenido, ni esta ni su contenido se incluirán en las resultados. Si solo filtras por estos recursos no incluidos, los archivos resultantes estarán vacías. Intentar filtrar por recursos fuera del contexto dado no se mostrará un error, así que asegúrate de verificar que el contexto sea correcto

Elige el filtro adecuado

Además del contexto establecido anteriormente, puedes filtrar aún más el alcance de tus archivos de datos estructurados generados especificando los tipos de archivo que deseas generarás y los recursos específicos o la familia de recursos que quieres incluir.

Hay tres filtros disponibles para un sdfdownloadtask, cada uno destinado a para un tipo de especificación particular. Solo puedes asignar una por una sdfdownloadtask

ParentEntityFilter

ParentEntityFilter es el más amplio de los disponibles filtros.

Con el campo fileType, puedes enumerar todos los tipos de archivos que quieres generar con tu tarea. Este es obligatorio y, si se deja vacío o se establece en FILE_TYPE_UNSPECIFIED, el valor sdfdownloadtask se completará por error.

Con filterType y filterIds, puedes definir mejor los resultados. filterType especifica el tipo de recursos para filtrar y filterIds identifica esos recursos por su ID único. Los SDF resultantes incluirán los recursos identificados por fileType que son los recursos o elementos secundarios de los recursos identificados por filterType y filterIds.

IdFilter

IdFilter filtra tu solicitud para incluir solo los recursos. identificados.

IdFilter tiene un campo para cada tipo de SDF, excepto Inventory Fuente: Cada uno de estos campos es una lista de IDs únicos que identifican la recursos específicos que quieras incluir en tu SDF generado. Los IDs proporcionados deben estar dentro del contexto, pero no tienen que estar directamente relacionados. Tú no necesita solicitar una campaña específica para solicitar una línea de pedido, contiene y viceversa. Los únicos tipos de archivos generados serán de esos que corresponde a los recursos identificados en IdFilter.

InventorySourceFilter

InventorySourceFilter solo permite el filtrado y descarga de SDF que contengan recursos de fuentes de inventario. Es la única que puedes usar para obtener información sobre tus recursos de Fuente de inventario.

InventorySourceFilter tiene un signo singular inventorySourceIds en el que identificas Son los IDs de los recursos de fuente de inventario que quieres incluir en tu SDF. Si el botón lista proporcionada a inventorySourceIds está vacía, todas las fuentes de inventario bajo el contexto establecido se incluirán en el SDF generado.

Haz una solicitud

Una vez que conozcas los parámetros de tu SDF deseado, puedes crear la solicitud y crea el sdfdownloadtask.

Este es un ejemplo de cómo crear un sdfdownloadtask con un 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());

Cómo verificar tu solicitud y obtener la ruta de descarga

Cuando creas un sdfdownloadtask, se crea un objeto de operación que se devuelven. Esta operación representa el estado de tu SDF asíncrono. de generación de demanda en el momento de la creación. Puedes verificar tu operación para ver si se completó y está listo para descargar, o si arrojó un error mediante Usa el método sdfdownloadtasks.operations.get.

Al finalizar, la operación devuelta tendrá un valor done. La operación finalizada incluirá un response o error . Si está presente, el campo error tendrá un Un objeto Status que contiene un código de error y mensaje, que brinda detalles del error que para determinar si se produjo un error. Si el campo response está presente, tendrá un objeto con un valor resourceName que identifica la generación para descargarlo.

Este es un ejemplo de cómo verificar tu solicitud con la retirada 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']
);