Présentation

Les fichiers de données structurées (SDF, Structured Data Files) sont des fichiers CSV (valeurs séparées par une virgule) dans un format spécifique. fichiers utilisés pour récupérer et mettre à jour les données sur Display & Ressources Video 360 dans de façon groupée. Via le Réseau Display et l'API Video 360, vous pouvez générer et télécharger des fichiers SDF personnalisés, Vous pouvez ainsi récupérer des données filtrées et organisées sur vos campagnes Video 360 ressources.

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

Pour en savoir plus sur le format des fichiers SDF et la gestion des versions, consultez le Documentation de référence sur les fichiers SDF.

Créer une tâche

Les fichiers de données structurées sont générés par une opération asynchrone, appelée sdfdownloadtask. Lors de la création de cette tâche, vous définissez les paramètres concernant les fichiers de données structurées de votre choix. Pour ce faire, utilisez la méthode sdfdownloadtasks.create. La Les sous-sections suivantes décrivent les paramètres que vous pouvez définir.

Spécifier une version

Le format du fichier de données structurées est régulièrement mis à jour indépendamment Display & API Video 360, nouvelles versions et anciennes versions publiées obsolète régulièrement. Pour cette raison, il est a toujours recommandé aux utilisateurs d'utiliser la version la plus récente des fichiers SDF.

Définissez la version SDF du fichier SDF de votre choix à l'aide du version dans le corps de la requête. Si aucune valeur n'est définie sur SDF_VERSION_UNSPECIFIED, la tâche utilisera la version par défaut du fichier ressource d'annonceur ou de partenaire utilisée comme contexte du contenu du fichier SDF.

Remarque :Pour chaque ressource de partenaire, une version de fichier SDF par défaut est configurée dans le "Informations de base" dans l'API. Sauf configuration contraire, les annonceurs héritent de cette valeur par défaut de leur partenaire parent.

Définissez le contexte

Vous pouvez générer un fichier de données structurées contenant des données sur toutes les ressources un fichier de données structurées ne peut renvoyer que du contenu associé à un seul le partenaire ou l'annonceur. Ce contexte est défini dans le corps de la requête par le partnerId ou advertiserId. Exactement une de ces deux options les champs doivent être définis.

Seules les ressources correspondant au contexte donné seront incluses dans le fichier de données structurées généré. Si vous tentez de filtrer les données en fonction d'une ressource qui n'appartient pas au partenaire spécifié ni l'annonceur, ni celui-ci, ni le contenu sous celui-ci ne seront inclus dans résultats. Si vous n'effectuez un filtrage qu'en fonction de ces ressources non incluses, les fichiers obtenus est vide. Tentative de filtrage par ressources en dehors du contexte donné ne renverra pas d'erreur. Assurez-vous donc que votre contexte est Correct.

Choisir le bon filtre

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

Remarque :Le type d'un fichier de données structurées détermine le type de ressource qui renseigne ce fichier. Chaque type de fichier possède une structure de colonne différente reflétant les informations disponibles pour cette ressource.

Trois filtres sont disponibles pour un sdfdownloadtask, chacun adapté à un type de spécification particulier. Vous ne pouvez en attribuer qu'un sdfdownloadtask

ParentEntityFilter

ParentEntityFilter est la valeur la plus large parmi les valeurs disponibles. des filtres.

Le champ fileType vous permet de lister tous les éléments types de fichiers que vous souhaitez générer avec votre tâche. C'est obligatoire. Si vous ne renseignez pas ce champ ou si elle est définie sur FILE_TYPE_UNSPECIFIED, sdfdownloadtask va aboutir à une erreur.

Utiliser filterType et filterIds, vous pouvez affiner davantage vos résultats. filterType spécifie le type de ressources avec filtre et filterIds identifie ces ressources par leur identifiant unique. Les fichiers de données structurées ainsi obtenus incluent les ressources identifiées par fileType qui sont les ressources ou enfants des ressources identifiées par filterType et filterIds.

Remarque :FILTER_TYPE_NONE n'applique aucun filtre à la tâche, mais n'est applicable lorsque advertiserId est spécifié. Sinon, une erreur sera renvoyée lors de la création de sdfdownloadtask.

IdFilter

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

IdFilter comporte un champ pour chaque type de fichier, à l'exception de l'inventaire Source : Chacun de ces champs est une liste d'identifiants uniques identifiant le les ressources spécifiques que vous souhaitez inclure dans le fichier SDF généré. ID fournis doivent être comprises dans le contexte, mais elles n'ont pas besoin d'être directement liées. Toi n'ont pas besoin de demander une campagne spécifique pour demander un élément de campagne, contient, et inversement. Les seuls types de fichiers générés correspondant aux ressources identifiées dans le IdFilter.

InventorySourceFilter

InventorySourceFilter permet uniquement le filtrage et le téléchargement de fichiers SDF contenant des ressources de source d'inventaire. C'est la seule que vous pouvez utiliser pour obtenir des informations sur vos ressources de source d'inventaire.

InventorySourceFilter a un singulier champ inventorySourceIds dans lequel vous identifiez l'unique ID des ressources de la source d'inventaire que vous souhaitez inclure dans votre fichier SDF. Si le la liste fournie à inventorySourceIds est vide, 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 de données structurées souhaité, vous pouvez créer la demande et créer le sdfdownloadtask.

Avertissement: Un même utilisateur est limité à 20 sdfdownloadtasks exécutions une seule fois. Si vous essayez d'en créer d'autres, une erreur sera renvoyée.

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 requête et obtenir le chemin de téléchargement

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

Remarque :Selon la taille des fichiers SDF générés, l'opération peut prendre de quelques secondes à quelques heures. Pour limiter votre quota, introduisez un intervalle exponentiel entre les tentatives, comme celui présenté dans l'exemple de code ci-dessous.

Une fois l'opération terminée, l'opération renvoyée aura une valeur done. Une fois terminée, l'opération inclut : un response ou un error . S'il est présent, le champ error présente une Un objet Status contenant un code d'erreur et message, qui fournit des informations sur l'erreur s'est produit. Si le champ response est présent, il possède un objet avec une valeur resourceName qui identifie l'objet généré à télécharger.

Voici un exemple de vérification de la 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']
);