Panoramica

I file di dati strutturati (SDF) sono file con valori separati da virgole (CSV) appositamente formattati per recuperare e aggiornare collettivamente i dati sulle risorse Display & Video 360. L'API Display & Video 360 ti consente di generare e scaricare SDF personalizzati, che ti consentono di recuperare dati organizzati e filtrati sulle tue risorse Display & Video 360.

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

Le informazioni relative al formato e al controllo delle versioni dei file SDF sono disponibili nella 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 ai file SDF desiderati. Questa operazione viene eseguita con il metodo sdfdownloadtasks.create. Le seguenti sottosezioni descrivono i parametri che puoi impostare.

Specifica una versione

Il formato File di dati strutturati viene regolarmente aggiornato indipendentemente dall'API Display & Video 360, con nuove versioni rilasciate e versioni precedenti ritirate regolarmente. Per questo motivo, consigliamo sempre agli utenti di utilizzare la versione più recente di SDF.

Puoi impostare la versione SDF del file SDF che ti interessa utilizzando il campo version nel corpo della richiesta. Se non viene configurato o se viene impostato su SDF_VERSION_UNSPECIFIED, l'attività utilizzerà la versione predefinita del file SDF dell'inserzionista o della risorsa partner usata come contesto dei contenuti del file SDF.

Nota: per ogni risorsa del partner è stata configurata una versione predefinita dell'SDF nelle impostazioni "Dettagli di base" dell'API. Se non diversamente configurato, gli inserzionisti ereditano questo valore predefinito dal partner principale.

Definisci il contesto

Puoi generare un SDF contenente dati relativi a qualsiasi risorsa disponibile, ma ogni singolo SDF può restituire contenuti solo nel contesto di un singolo partner o inserzionista. Questo contesto è definito nel corpo della richiesta dal campo partnerId o advertiserId. È necessario impostare 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 sottostanti verranno inclusi nei risultati. Se applichi il filtro solo in base a queste risorse non incluse, i file risultanti saranno vuoti. Il tentativo di filtrare in base a risorse esterne al contesto specificato non restituirà un errore, quindi assicurati di verificare che il contesto sia corretto.

Scegli 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.

Nota: il tipo di file di dati strutturati determina il tipo di risorsa che completa il file. Ogni tipo di file ha una struttura di colonne diversa che riflette le informazioni disponibili per la risorsa.

Sono disponibili tre filtri per un elemento sdfdownloadtask, ciascuno per un determinato tipo di specifica. Puoi assegnarne una sola per un singolo sdfdownloadtask.

ParentEntityFilter

ParentEntityFilter è il filtro più generico disponibili.

Il campo fileType ti consente di elencare tutti i tipi di file che vuoi generare con l'attività. Questo campo è obbligatorio e, se il campo viene lasciato vuoto o impostato su FILE_TYPE_UNSPECIFIED, il tuo sdfdownloadtask verrà completato per errore.

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

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

IdFilter

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

IdFilter ha un campo per ogni tipo di SDF, escluso 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 essere all'interno del contesto impostato, ma non devono essere direttamente correlati. Non è necessario richiedere una determinata campagna per richiedere un elemento pubblicitario che contiene e viceversa. Gli unici tipi di file generati saranno quelli corrispondenti alle risorse identificate in IdFilter.

InventorySourceFilter

InventorySourceFilter consente solo l'applicazione di filtri e download dei file SDF contenenti risorse di origine dell'inventario. È l'unico filtro che puoi utilizzare per ottenere informazioni sulle risorse dell'origine dell'inventario.

InventorySourceFilter ha un campo inventorySourceIds unico in cui puoi identificare 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 saranno incluse nel file SDF generato.

Fai una richiesta

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

Avviso: per un singolo utente viene eseguito un massimo di venti sdfdownloadtasks contemporaneamente. Se provi a crearne altri, verrà restituito 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());

Verifica la tua richiesta e ottieni il percorso di download

Quando crei un sdfdownloadtask, viene restituito un oggetto operation. Questa operazione rappresenta lo stato dell'operazione di generazione SDF asincrona al momento della creazione. Puoi controllare l'operazione per vedere se è stata completata, se è pronta 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 pochi secondi a diverse ore. Per risparmiare quota, introduci un backoff esponenziale come quello mostrato nell'esempio di codice riportato di seguito.

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

Ecco un esempio di come controllare una 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']
);