Panoramica

I file di dati strutturati (SDF) sono valori separati da virgole (CSV) con formati speciali utilizzati per recuperare e aggiornare i dati relativi a Display & Risorse Video 360 in collettivo. Tramite il display e l'API Video 360, puoi generare e scaricare file SDF personalizzati, che ti consente di recuperare dati organizzati e filtrati sulle tue immagini Video a 360° Google Cloud.

Questa guida descrive come creare un'operazione di download di SDF, monitorare operativa e scaricare gli SDF risultanti.

Per informazioni sul formato e sul controllo delle versioni dei file SDF, consulta la documentazione di riferimento per i file SDF.

Creare un'attività

Gli SDF vengono generati da un'operazione asincrona, denominata sdfdownloadtask. Quando crei questa attività, definisci i parametri relativi agli SDF desiderati. A questo scopo, viene usato il metodo sdfdownloadtasks.create. La le seguenti sottosezioni descrivono i parametri che puoi impostare.

Specifica una versione

Il formato dei file di dati strutturati viene aggiornato regolarmente indipendentemente dal Display e API Video 360, con nuove versioni rilasciate e vecchie ritirate regolarmente. Per questo motivo, consigliamo sempre agli utenti di utilizzare la versione più recente di SDF.

Devi impostare la versione SDF dell'SDF desiderato utilizzando version nel corpo della richiesta. Se non impostato o impostato a SDF_VERSION_UNSPECIFIED, l'attività utilizzerà la versione predefinita dell'SDF risorsa dell'inserzionista o del partner utilizzata come contesto dei contenuti dei file SDF.

Nota: per ogni risorsa partner è impostata una versione SDF predefinita configurata nel "Dettagli di base" impostazioni nell'API. Se non diversamente configurato, gli inserzionisti ereditano questa impostazione predefinita dal proprio partner principale.

Definisci il contesto

Puoi generare un SDF contenente dati su qualsiasi risorsa a tua disposizione, ma un singolo SDF può restituire contenuti esclusivamente nel contesto di un singolo partner o inserzionista. Questo contesto viene definito nel corpo della richiesta da partnerId o advertiserId. Esattamente uno di questi due è necessario impostare i campi.

Nel file SDF risultante saranno incluse solo le risorse all'interno di un determinato contesto. Se tenti di filtrare in base a una risorsa che non è di proprietà del partner specificato o l'inserzionista, né questo né i relativi contenuti saranno inclusi nel che consentono di analizzare i dati e visualizzare i risultati. Se filtri solo in base a queste risorse non incluse, i file risultanti sarà vuoto. Tentativo di filtrare in base alle risorse esterne al contesto specificato non restituirà un errore, quindi assicurati di verificare che il tuo contesto sia risposta esatta.

Scegli il filtro giusto

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

Nota: il tipo di file di dati strutturati determina il tipo di risorsa da compilare quel file. Ogni tipo di file ha una struttura delle colonne diversa. informazioni disponibili per quella risorsa.

Sono disponibili tre filtri per sdfdownloadtask, ognuno dei quali si adatta un particolare tipo di specifica. Puoi assegnarne solo uno per singola sdfdownloadtask.

ParentEntityFilter

ParentEntityFilter è il più ampio filtri corretti.

Utilizzando il campo fileType, puoi elencare tutte le query i tipi di file che vuoi generare con l'attività. Questo è e, se lasciato vuoto o impostato su FILE_TYPE_UNSPECIFIED, il valore sdfdownloadtask verrà completato per errore.

Utilizzando i filterType e filterIds, puoi perfezionare ulteriormente i risultati. filterType specifica il tipo di risorse in base ai quali filtrare e filterIds identifica queste risorse tramite il loro ID univoco. Gli SDF risultanti includeranno le risorse identificate da fileType che sono le risorse o gli elementi secondari delle risorse identificate filterType e filterIds.

Nota: FILTER_TYPE_NONE non applicherà alcun filtro all'attività, ma solo applicabile quando è specificato advertiserId. In caso contrario, verrà restituito un errore al momento della creazione di sdfdownloadtask.

IdFilter

IdFilter filtra la richiesta per includere solo le risorse identificati.

IdFilter dispone di un campo per ogni tipo di SDF, escluso l'inventario Fonte. Ciascuno di questi campi è un elenco di ID univoci che identificano risorse specifiche che vuoi includere nel tuo SDF generato. Gli ID forniti devono rientrare nel contesto, ma non è necessario che siano direttamente correlate. Tu non hanno bisogno di una determinata campagna per richiedere un elemento pubblicitario, contiene e viceversa. Gli unici tipi di file generati saranno questi corrispondenti alle risorse identificate nella IdFilter.

InventorySourceFilter

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

InventorySourceFilter ha un singolare Campo inventorySourceIds in cui identifichi l'ID univoco Gli ID delle risorse dell'origine dell'inventario da includere nel file SDF. Se l'elenco fornito a inventorySourceIds è vuoto, le origini dell'inventario nel contesto impostato verranno incluse nell'SDF generato.

Fai una richiesta

Una volta identificati i parametri dell'SDF desiderato, puoi creare la richiesta e crea sdfdownloadtask.

Avviso: esiste un limite di venti sdfdownloadtasks di esecuzione per qualsiasi utente una volta sola. I tentativi di crearne altri restituiranno un errore.

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());

Controlla la richiesta e ottieni il percorso di download

Quando crei un sdfdownloadtask, viene generato un oggetto operation restituito. Questa operazione rappresenta lo stato del tuo SDF asincrono al momento della creazione. Puoi controllare l'operazione per verifica se l'aggiornamento è stato completato ed è pronto per il download o se ha generato un errore utilizzando il metodo sdfdownloadtasks.operations.get.

Nota: a seconda delle dimensioni degli SDF generati, l'operazione può richiedere da qualche secondo a qualche ora. Per risparmiare quota, Introduci un backoff esponenziale come quello illustrato nell'esempio di codice riportato di seguito.

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

Ecco un esempio di come verificare la tua 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']
);