Les fichiers de données structurées (SDF, Structured Data Files) sont des fichiers CSV (valeurs séparées par une virgule) avec une mise en forme spéciale qui permettent de récupérer et de mettre à jour des données sur les ressources Display & Video 360 de manière groupée. Via l'API Display & Video 360, vous pouvez générer et télécharger des fichiers SDF personnalisés, ce qui vous permet de 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 de fichiers SDF, suivre cette opération et télécharger les fichiers SDF générés.
Vous trouverez des informations sur ce format et la gestion des versions dans la documentation de référence sur les fichiers SDF.
Créer une tâche
Les fichiers SDF sont générés par une opération asynchrone, appelée sdfdownloadtask.
Lors de la création de cette tâche, vous devez définir les paramètres relatifs aux fichiers SDF que vous souhaitez utiliser.
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 de fichier 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 anciennes versions sont régulièrement obsolètes. Pour cette raison, il est toujours recommandé aux utilisateurs d'utiliser la version la plus récente des fichiers SDF.
Vous définissez la version des fichiers SDF de votre choix à l'aide du champ version dans le corps de la requête. Si cette valeur n'est pas définie ou définie sur SDF_VERSION_UNSPECIFIED, la tâche utilisera la version SDF par défaut de l'annonceur ou de la ressource 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 un fichier SDF ne peut afficher du contenu que pour 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 associées au contexte donné seront incluses dans le fichier SDF généré. Si vous tentez de filtrer les données en fonction d'une ressource qui n'est pas détenue par le partenaire ou l'annonceur spécifié, ni cette ressource ni son contenu associé ne seront inclus dans les résultats. Si vous filtrez uniquement ces ressources non incluses, les fichiers obtenus seront vides. Toute 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 de l'ensemble de contextes ci-dessus, vous pouvez filtrer davantage le champ d'application des 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 famille de ressources spécifiques que vous souhaitez inclure.
Trois filtres sont disponibles pour une sdfdownloadtask, chacun correspondant à un type de spécification particulier. Vous ne pouvez en attribuer qu'un pour un seul élément sdfdownloadtask.
ParentEntityFilter
ParentEntityFilter est le plus large des filtres disponibles.
Le champ fileType vous permet de répertorier tous les types de fichiers que vous souhaitez générer avec votre tâche. Cette étape est obligatoire. Si elle est laissée vide ou définie sur FILE_TYPE_UNSPECIFIED, votre sdfdownloadtask se terminera par erreur.
Vous pouvez affiner davantage vos résultats à l'aide des champs filterType et filterIds.
filterType spécifie le type de ressources à utiliser pour filtrer, et filterIds les identifie par leur identifiant unique. Les fichiers SDF générés incluent les ressources identifiées par fileType, qui sont les ressources ou 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 SDF, à 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 le 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. Les seuls types de fichiers générés seront ceux correspondant aux ressources identifiées dans le IdFilter.
InventorySourceFilter
InventorySourceFilter permet uniquement de filtrer et de télécharger des fichiers SDF contenant des ressources de source d'inventaire. C'est le seul filtre que vous pouvez utiliser pour obtenir des informations sur vos ressources de source d'inventaire.
InventorySourceFilter comporte un champ inventorySourceIds unique 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 construire la requête et créer 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 requête et obtenir le chemin de téléchargement
Lorsque vous créez une sdfdownloadtask, un objet operation est renvoyé. Cette opération représente l'état de votre opération de génération de fichiers SDF asynchrones au moment de la création. Vous pouvez utiliser la méthode sdfdownloadtasks.operations.get pour vérifier si votre opération est terminée et si elle est prête à être téléchargée, ou si une erreur a été générée.
À la fin de l'opération, l'opération renvoyée comporte un champ done non nul. L'opération terminée inclura un champ response ou error. S'il est présent, le champ error comportera un objet Status contenant un code d'erreur et un message, qui fournissent des détails sur l'erreur qui s'est produite. Si le champ response est présent, il comporte 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']
);