Übersicht

Strukturierte Datendateien (Structured Data Files, SDFs) sind speziell formatierte CSV-Dateien (Comma Separated Values), mit denen Daten zu Display & Video 360-Ressourcen im Bulk abgerufen und aktualisiert werden können. Über die Display & Video 360 API können Sie benutzerdefinierte SDFs erstellen und herunterladen, um organisierte, gefilterte Daten zu Ihren Display & Video 360-Ressourcen abzurufen.

In diesem Leitfaden wird beschrieben, wie Sie einen SDF-Downloadvorgang erstellen, diesen Vorgang verfolgen und die resultierenden SDFs herunterladen.

Informationen zum Format und zur Versionsverwaltung von SDFs finden Sie in der Referenzdokumentation zu SDFs.

Eine Aufgabe erstellen

SDFs werden durch einen asynchronen Vorgang generiert, der als sdfdownloadtask bezeichnet wird. Beim Erstellen dieser Aufgabe definieren Sie die Parameter für die gewünschten SDFs. Dazu verwenden Sie die Methode sdfdownloadtasks.create. In den folgenden Unterabschnitten werden die Parameter beschrieben, die Sie festlegen können.

Version angeben

Das Dateiformat für strukturierte Daten wird regelmäßig unabhängig von der Display & Video 360 API aktualisiert. Dabei werden neue Versionen veröffentlicht und alte Versionen werden regelmäßig verworfen. Aus diesem Grund wird immer empfohlen, Nutzern die neueste Version der SDFs zu verwenden.

Legen Sie im Feld version im Anfragetext die SDF-Version der gewünschten SDF fest. Wenn die Richtlinie nicht konfiguriert oder auf SDF_VERSION_UNSPECIFIED gesetzt ist, wird für die Aufgabe die SDF-Standardversion der Werbetreibenden- oder Partnerressource verwendet, die im Kontext des SDF-Inhalts verwendet wird.

Hinweis :Für jede Partnerressource ist in den Einstellungen unter „Allgemeine Angaben“ in der API eine festgelegte SDF-Standardversion konfiguriert. Sofern nicht anders konfiguriert, übernehmen Werbetreibende die Standardeinstellung vom übergeordneten Partner.

Kontext festlegen

Sie können eine SDF mit Daten zu allen verfügbaren Ressourcen generieren. Jede einzelne SDF kann jedoch nur Inhalte im Kontext eines einzelnen Partners oder Werbetreibenden zurückgeben. Dieser Kontext wird im Anfragetext über das Feld partnerId oder advertiserId definiert. Genau eines dieser beiden Felder muss festgelegt werden.

Nur Ressourcen im angegebenen Kontext werden in die SDF aufgenommen. Wenn Sie nach einer Ressource filtern, die nicht zum angegebenen Partner oder Werbetreibenden gehört, werden weder diese noch der ihr untergeordnete Inhalt in den Ergebnissen berücksichtigt. Wenn nur nach diesen nicht enthaltenen Ressourcen gefiltert wird, sind die resultierenden Dateien leer. Wenn Sie nach Ressourcen außerhalb des angegebenen Kontexts filtern, wird kein Fehler zurückgegeben. Prüfen Sie daher, ob Ihr Kontext korrekt ist.

Den richtigen Filter auswählen

Zusätzlich zu dem oben festgelegten Kontext können Sie den Umfang der generierten Dateien mit strukturierten Daten weiter filtern, indem Sie die zu generierenden Dateitypen und die spezifischen Ressourcen oder Ressourcenfamilien angeben, die Sie einschließen möchten.

Hinweis: Der Typ einer strukturierten Datendatei bestimmt den Ressourcentyp, mit dem diese Datei ausgefüllt wird. Jeder Dateityp hat eine andere Spaltenstruktur, die die für diese Ressource verfügbaren Informationen widerspiegelt.

Für sdfdownloadtask sind drei Filter verfügbar, die sich jeweils auf einen bestimmten Spezifikationstyp beziehen. Sie können nur einen für eine einzelne sdfdownloadtask zuweisen.

ParentEntityFilter

ParentEntityFilter ist der umfassendste der verfügbaren Filter.

Mit dem Feld fileType können Sie alle gewünschten Dateitypen auflisten, die Sie mit Ihrer Aufgabe generieren möchten. Dies ist erforderlich. Wenn Sie das Feld auf FILE_TYPE_UNSPECIFIED setzen oder leer lassen, wird sdfdownloadtask fälschlicherweise ausgeführt.

Mit den Feldern filterType und filterIds können Sie die Ergebnisse weiter eingrenzen. filterType gibt den Ressourcentyp an, nach dem gefiltert werden soll. filterIds identifiziert diese Ressourcen anhand ihrer eindeutigen ID. Die resultierenden SDFs enthalten die von fileType identifizierten Ressourcen, die entweder die Ressourcen oder die untergeordneten Ressourcen der von filterType und filterIds angegebenen Ressourcen sind.

Hinweis: FILTER_TYPE_NONE wendet keinen Filter auf die Aufgabe an. Dieses wird jedoch nur angewendet, wenn advertiserId angegeben ist. Andernfalls wird beim Erstellen von sdfdownloadtask ein Fehler zurückgegeben.

IdFilter

IdFilter filtert Ihre Anfrage so, dass nur die identifizierten Ressourcen enthalten sind.

In IdFilter gibt es für jeden SDF-Typ ein Feld ohne Inventarquelle. Jedes dieser Felder ist eine Liste eindeutiger IDs für die Ressourcen, die Sie in die generierte SDF aufnehmen möchten. Die angegebenen IDs müssen sich innerhalb des Kontextsatzes befinden, müssen aber nicht direkt miteinander verknüpft sein. Sie müssen keine bestimmte Kampagne anfordern, um eine darin enthaltene Werbebuchung anzufordern, und umgekehrt. Es werden nur Dateitypen generiert, die den in IdFilter angegebenen Ressourcen entsprechen.

InventorySourceFilter

Mit InventorySourceFilter können nur SDFs mit Inventarquellenressourcen gefiltert und heruntergeladen werden. Es ist der einzige Filter, den Sie verwenden können, um Informationen zu Ihren Inventarquellenressourcen zu erhalten.

InventorySourceFilter hat ein einzelnes Feld inventorySourceIds, in dem Sie die eindeutigen IDs der Inventarquellenressourcen angeben, die in die SDF aufgenommen werden sollen. Wenn die für inventorySourceIds bereitgestellte Liste leer ist, werden alle Inventarquellen unter dem festgelegten Kontext in die generierte SDF aufgenommen.

Anfrage stellen

Wenn Sie die Parameter der gewünschten SDF kennen, können Sie die Anfrage mit dem sdfdownloadtask erstellen.

Warnung: Für einen einzelnen Nutzer können maximal 20 sdfdownloadtasks gleichzeitig ausgeführt werden. Beim Versuch, weitere zu erstellen, wird ein Fehler zurückgegeben.

Hier ist ein Beispiel dafür, wie ein sdfdownloadtask mit einem ParentEntityFilter erstellt wird:

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());

Anfrage prüfen und Downloadpfad abrufen

Wenn Sie ein sdfdownloadtask erstellen, wird ein operation-Objekt zurückgegeben. Dieser Vorgang stellt den Status des asynchronen Generierungsvorgangs für SDFs zum Zeitpunkt der Erstellung dar. Mit der Methode sdfdownloadtasks.operations.get können Sie prüfen, ob der Vorgang abgeschlossen wurde und zum Download bereit ist oder ein Fehler ausgegeben hat.

Hinweis: Je nach Größe der generierten SDFs kann der Vorgang zwischen wenigen Sekunden und mehreren Stunden dauern. Um das Kontingent zu schonen, sollten Sie einen exponentiellen Backoff wie im folgenden Codebeispiel gezeigt einrichten.

Nach Abschluss hat der zurückgegebene Vorgang das Feld done ungleich null. Der abgeschlossene Vorgang enthält entweder das Feld response oder error. Falls vorhanden, enthält das Feld error ein Status-Objekt mit einem Fehlercode und einer Nachricht mit Details zum aufgetretenen Fehler. Wenn das Feld response vorhanden ist, enthält es ein Objekt mit einem resourceName-Wert, das die generierte Datei zum Download identifiziert.

Hier ein Beispiel dafür, wie Sie Ihre Anfrage mithilfe des exponentiellen Backoffs prüfen können:

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