Panoramica

I file di dati strutturati (SDF) sono file con valori separati da virgole (CSV) con una formattazione speciale utilizzati per recuperare e aggiornare in blocco i dati sulle risorse di Display & Video 360. Tramite l'API Display & Video 360, puoi generare e scaricare SDF personalizzati, consentendoti di recuperare dati organizzati e filtrati sulle tue risorse Display & Video 360.

Questa guida descrive come creare un'operazione di download di SDF, monitorarla e scaricare i file SDF risultanti.

Le informazioni relative al formato e al controllo delle versioni dell'SDF sono disponibili nella documentazione di riferimento dell'SDF.

Creare un'attività

Gli SDF vengono generati da un'operazione asincrona, chiamata sdfdownloadtask. Quando crei questa attività, definisci i parametri relativi agli SDF che preferisci. Questa operazione viene eseguita tramite il metodo sdfdownloadtasks.create. Le seguenti sottosezioni descrivono i parametri che puoi impostare.

Specificare una versione

Il formato del file di dati strutturati viene aggiornato regolarmente indipendentemente dall'API Display & Video 360, con nuove versioni rilasciate e versioni precedenti ritirate regolarmente. Per questo motivo, è sempre consigliabile che gli utenti utilizzino la versione più recente di SDF.

Imposta la versione SDF dell'SDF che preferisci utilizzando il campo version nel corpo della richiesta. Se non impostato o impostato su SDF_VERSION_UNSPECIFIED, l'attività utilizzerà la versione SDF predefinita della risorsa dell'inserzionista o del partner utilizzata come contesto dei contenuti SDF.

Imposta il contesto

Puoi generare un file SDF contenente dati su qualsiasi risorsa a tua disposizione, ma qualsiasi file SDF individuale può restituire contenuti solo nel contesto di un singolo partner o inserzionista. Questo contesto è definito nel corpo della richiesta dal campo partnerId o advertiserId. Deve essere impostato esattamente uno di questi due campi.

Nel file SDF risultante verranno incluse solo le risorse all'interno del contesto specificato. Se tenti di filtrare in base a una risorsa che non è di proprietà del partner o dell'inserzionista specificato, né la risorsa né i contenuti al suo interno verranno inclusi nei risultati. Se filtri solo in base a queste risorse non incluse, i file risultanti saranno vuoti. Il tentativo di filtrare in base alle risorse al di fuori del contesto specificato non restituirà un errore, quindi assicurati che il contesto sia corretto.

Scegliere il filtro giusto

Oltre al contesto impostato sopra, puoi filtrare ulteriormente l'ambito dei file di dati strutturati generati specificando i tipi di file che vuoi generare e le risorse o la famiglia di risorse specifiche che vuoi includere.

Per un sdfdownloadtask sono disponibili tre filtri, ognuno dei quali è adatto a un tipo specifico di specifica. Puoi assegnarne solo uno per un singolo sdfdownloadtask.

ParentEntityFilter

ParentEntityFilter è il filtro più ampio disponibile.

Utilizzando il campo fileType, puoi elencare tutti i tipi di file che vuoi generare con l'attività. Questo campo è obbligatorio e, se lasciato vuoto o impostato su FILE_TYPE_UNSPECIFIED, il sdfdownloadtask verrà completato con errori.

Utilizzando i campi filterType e filterIds, puoi perfezionare ulteriormente i risultati. filterType specifica il tipo di risorse da filtrare e filterIds identifica queste risorse in base al loro ID univoco. I file SDF risultanti includeranno le risorse identificate da fileType che sono le risorse o le risorse secondarie delle risorse identificate da filterType e filterIds.

IdFilter

IdFilter filtra la richiesta in modo da includere solo le risorse identificate.

IdFilter ha un campo per ogni tipo di SDF, esclusa l'origine dell'inventario. Ciascuno di questi campi è un elenco di ID univoci che identificano le risorse specifiche che vuoi includere nel file SDF generato. Gli ID forniti devono rientrare nel contesto impostato, ma non devono essere correlati direttamente. Non è necessario richiedere una campagna specifica per richiedere un elemento pubblicitario che contiene e viceversa. Verranno generati solo i tipi di file corrispondenti alle risorse identificate in IdFilter.

InventorySourceFilter

InventorySourceFilter consente solo il filtraggio e il download degli SDF contenenti risorse di origine inventario. È l'unico filtro che puoi utilizzare per ottenere informazioni sulle risorse dell'origine inventario.

InventorySourceFilter ha un campo inventorySourceIds singolare in cui identifichi gli ID univoci delle risorse dell'origine dell'inventario che vuoi includere nel file SDF. Se l'elenco fornito a inventorySourceIds è vuoto, tutte le origini dell'inventario nel contesto impostato verranno incluse nel file SDF generato.

Fai una richiesta

Una volta che conosci i parametri del file SDF che ti interessa, puoi creare la richiesta e il sdfdownloadtask.

Ecco un esempio di come creare un sdfdownloadtask utilizzando 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());

Controllare la richiesta e ottenere il percorso di download

Quando crei un sdfdownloadtask, viene restituito un oggetto operazione. Questa operazione rappresenta lo stato dell'operazione di generazione asincrona di SDF al momento della creazione. Puoi controllare l'operazione per verificare se è stata completata ed è pronta per il download o se si è verificato un errore utilizzando il metodo sdfdownloadtasks.operations.get.

Al termine, l'operazione restituita avrà un campo done non nullo. L'operazione completata includerà un campo response o error. Se presente, il campo error conterrà un oggetto Status contenente un codice di errore e un messaggio, che fornisce i dettagli dell'errore che si è verificato. Se il campo response è presente, conterrà un oggetto con un valore resourceName che identifica il file generato per il download.

Ecco un esempio di come controllare la richiesta utilizzando il backoff esponenziale:

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