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