Aperçu

Les fichiers de données structurées (SDF) sont des fichiers de valeurs séparées par une virgule (CSV) au format spécial. Ils permettent de récupérer et de mettre à jour des données sur les ressources Display & Video 360 de manière groupée. L'API Display & Video 360 vous permet de générer et de télécharger des fichiers SDF personnalisés. Vous pouvez ainsi récupérer des données organisées et filtrées sur vos ressources Display & Video 360.

Ce guide explique comment créer une opération de téléchargement SDF, la suivre et télécharger les fichiers SDF obtenus.

Pour en savoir plus sur le format et le versionnage des fichiers de données structurées, consultez la documentation de référence sur les fichiers de données structurées.

Créer une tâche

Les SDF sont générés par une opération asynchrone appelée sdfdownloadtask. Lorsque vous créez cette tâche, vous définissez les paramètres concernant les SDF souhaités. Pour ce faire, utilisez la méthode sdfdownloadtasks.create. Les sous-sections suivantes décrivent les paramètres que vous pouvez définir.

Spécifier une version

Le format des fichiers de données structurées est régulièrement mis à jour indépendamment de l'API Display & Video 360. De nouvelles versions sont publiées et les versions antérieures sont régulièrement obsolètes. C'est pourquoi nous recommandons toujours aux utilisateurs d'utiliser la version la plus récente de SDF.

Vous définissez la version SDF de la structure SDF souhaitée à l'aide du champ version dans le corps de la requête. Si elle n'est pas définie ou est définie sur SDF_VERSION_UNSPECIFIED, la tâche utilise la version SDF par défaut de la ressource annonceur ou partenaire utilisée comme contexte du contenu SDF.

Définir le contexte

Vous pouvez générer un fichier SDF contenant des données sur toutes les ressources à votre disposition, mais chaque fichier SDF ne peut renvoyer du contenu que dans le contexte d'un seul partenaire ou annonceur. Ce contexte est défini dans le corps de la requête par le champ partnerId ou advertiserId. Un seul de ces deux champs doit être défini.

Seules les ressources du contexte donné seront incluses dans le fichier SDF obtenu. Si vous essayez de filtrer les résultats par une ressource qui n'appartient pas au partenaire ou à l'annonceur spécifié, ni la ressource ni le contenu qu'elle contient ne seront inclus dans les résultats. Si vous ne filtrez que par ces ressources non incluses, les fichiers obtenus seront vides. Si vous essayez de filtrer par ressources en dehors du contexte donné, aucune erreur ne sera renvoyée. Veillez donc à vérifier que votre contexte est correct.

Choisir le bon filtre

En plus du contexte défini ci-dessus, vous pouvez filtrer davantage la portée de vos fichiers de données structurées générés en spécifiant les types de fichiers que vous souhaitez générer et les ressources ou la famille de ressources spécifiques que vous souhaitez inclure.

Trois filtres sont disponibles pour un sdfdownloadtask. Chacun d'eux correspond à un type de spécification particulier. Vous ne pouvez en attribuer qu'un seul à un sdfdownloadtask.

ParentEntityFilter

ParentEntityFilter est le filtre le plus large disponible.

Le champ fileType vous permet de lister tous les types de fichiers que vous souhaitez générer avec votre tâche. Ce champ est obligatoire. Si vous le laissez vide ou le définissez sur FILE_TYPE_UNSPECIFIED, votre sdfdownloadtask se terminera avec une erreur.

Vous pouvez affiner davantage vos résultats à l'aide des champs filterType et filterIds. filterType spécifie le type de ressources à filtrer, et filterIds identifie ces ressources par leur ID unique. Les fichiers SDF obtenus incluront les ressources identifiées par fileType qui sont soit les ressources, soit les enfants des ressources identifiées par filterType et filterIds.

IdFilter

IdFilter filtre votre requête pour n'inclure que les ressources identifiées.

IdFilter comporte un champ pour chaque type de fichier de données structurées, à l'exception de la source d'inventaire. Chacun de ces champs est une liste d'ID uniques identifiant les ressources spécifiques que vous souhaitez inclure dans votre fichier SDF généré. Les ID fournis doivent se trouver dans l'ensemble de contexte, mais ils n'ont pas besoin d'être directement liés. Vous n'avez pas besoin de demander une campagne spécifique pour demander un élément de campagne qu'elle contient, et inversement. Seuls les types de fichiers correspondant aux ressources identifiées dans IdFilter seront générés.

InventorySourceFilter

InventorySourceFilter ne permet de filtrer et de télécharger que les fichiers SDF contenant des ressources de type "Source d'inventaire". Il s'agit du seul filtre que vous pouvez utiliser pour obtenir des informations sur vos ressources Inventory Source.

InventorySourceFilter comporte un champ inventorySourceIds au singulier dans lequel vous identifiez les ID uniques des ressources de source d'inventaire que vous souhaitez inclure dans votre fichier SDF. Si la liste fournie à inventorySourceIds est vide, toutes les sources d'inventaire dans le contexte défini seront incluses dans le fichier SDF généré.

Envoyer une requête

Une fois que vous connaissez les paramètres du fichier SDF souhaité, vous pouvez créer la requête et le sdfdownloadtask.

Voici un exemple de création d'un sdfdownloadtask à l'aide d'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());

Vérifier votre demande et obtenir le chemin de téléchargement

Lorsque vous créez un sdfdownloadtask, un objet opération est renvoyé. Cette opération représente l'état de votre opération de génération de fichier SDF asynchrone au moment de la création. Vous pouvez vérifier si votre opération est terminée et prête à être téléchargée, ou si elle a généré une erreur, à l'aide de la méthode sdfdownloadtasks.operations.get.

Une fois l'opération terminée, le champ done de l'opération renvoyée ne sera pas nul. L'opération terminée inclut un champ response ou error. Si le champ error est présent, il contient un objet Status avec un code d'erreur et un message qui fournit des détails sur l'erreur qui s'est produite. Si le champ response est présent, il contient un objet avec une valeur resourceName qui identifie le fichier généré à télécharger.

Voici un exemple de vérification de votre requête à l'aide d'un intervalle exponentiel entre les tentatives :

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