Übersicht

Strukturierte Datendateien (SDFs) sind CSV-Dateien (Comma-Separated Values) mit speziellem Format, mit denen Daten zu Display & Video 360-Ressourcen im Bulk-Verfahren abgerufen und aktualisiert werden können. Mit der Display & Video 360 API können Sie benutzerdefinierte SDFs generieren 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 SDF-Format und zur Versionierung finden Sie in der SDF-Referenzdokumentation.

Aufgaben erstellen

SDFs werden durch einen asynchronen Vorgang namens sdfdownloadtask generiert. Beim Erstellen dieser Aufgabe definieren Sie die Parameter für die gewünschten SDFs. Dies geschieht über die Methode sdfdownloadtasks.create. In den folgenden Unterabschnitten werden die Parameter beschrieben, die Sie festlegen können.

Version angeben

Das Format der strukturierten Datendatei wird unabhängig von der Display & Video 360 API regelmäßig aktualisiert. Es werden neue Versionen veröffentlicht und alte Versionen regelmäßig eingestellt. Aus diesem Grund wird immer die Verwendung der neuesten SDF-Version empfohlen.

Die SDF-Version des gewünschten SDF legen Sie mit dem Feld version im Anfragetext fest. Wenn das Attribut nicht festgelegt oder auf SDF_VERSION_UNSPECIFIED gesetzt ist, wird für die Aufgabe die Standard-SDF-Version der Werbetreibenden- oder Partnerressource verwendet, die als Kontext der SDF-Inhalte verwendet wird.

Hinweis :Für jede Partnerressource ist in den Einstellungen „Allgemeine Angaben“ in der API eine Standard-SDF-Version konfiguriert. Sofern nicht anders konfiguriert, übernehmen Werbetreibende diese Standardeinstellung von ihrem übergeordneten Partner.

Kontext festlegen

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

Nur Ressourcen im angegebenen Kontext werden in die resultierende SDF-Datei aufgenommen. Wenn Sie versuchen, nach einer Ressource zu filtern, die nicht dem angegebenen Partner oder Werbetreibenden gehört, werden weder die Ressource noch die zugehörigen Inhalte in den Ergebnissen berücksichtigt. Wenn Sie nur nach diesen nicht enthaltenen Ressourcen filtern, sind die resultierenden Dateien leer. Wenn Sie versuchen, nach Ressourcen außerhalb des angegebenen Kontexts zu filtern, wird kein Fehler zurückgegeben. Achten Sie also darauf, dass der Kontext korrekt ist.

Den richtigen Filter auswählen

Zusätzlich zum oben festgelegten Kontext können Sie den Umfang der generierten strukturierten Datendateien weiter filtern, indem Sie die Dateitypen angeben, die Sie generieren möchten, und die Ressourcen oder Ressourcengruppen, die Sie einschließen möchten.

Hinweis: Der Typ einer strukturierten Datendatei bestimmt den Ressourcentyp, der in diese Datei eingefügt wird. Jeder Dateityp hat eine andere Spaltenstruktur, die die für diese Ressource verfügbaren Informationen widerspiegelt.

Für sdfdownloadtask gibt es drei Filter, die jeweils für einen bestimmten Spezifikationstyp geeignet sind. Sie können nur eine für eine einzelne sdfdownloadtask zuweisen.

ParentEntityFilter

ParentEntityFilter ist der breiteste der verfügbaren Filter.

Im Feld fileType können Sie alle gewünschten Dateitypen auflisten, die mit Ihrer Aufgabe generiert werden sollen. Diese Angabe ist erforderlich. Wenn Sie das Feld leer lassen oder auf FILE_TYPE_UNSPECIFIED festlegen, wird die sdfdownloadtask mit einem Fehler abgeschlossen.

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

Hinweis :Mit FILTER_TYPE_NONE wird kein Filter auf die Aufgabe angewendet. Diese Option ist nur dann gültig, wenn advertiserId angegeben ist. Andernfalls wird beim Erstellen der sdfdownloadtask ein Fehler zurückgegeben.

IdFilter

Mit IdFilter wird Ihre Anfrage so gefiltert, dass nur die angegebenen Ressourcen berücksichtigt werden.

IdFilter hat ein Feld für jeden SDF-Typ, mit Ausnahme von „Inventarquelle“. Jedes dieser Felder ist eine Liste eindeutiger IDs, die die Ressourcen angeben, die in den generierten SDF aufgenommen werden sollen. Die angegebenen IDs müssen zum Kontext gehören, müssen aber nicht direkt miteinander in Beziehung stehen. Sie müssen keine bestimmte Kampagne anfordern, um eine darin enthaltene Werbebuchung anzufordern, und umgekehrt. Es werden nur Dateitypen generiert, die den in der IdFilter angegebenen Ressourcen entsprechen.

InventorySourceFilter

Mit InventorySourceFilter können nur SDFs mit Inventarquellen gefiltert und heruntergeladen werden. Es ist der einzige Filter, mit dem Sie Informationen zu den Ressourcen Ihrer Inventarquelle abrufen können.

InventorySourceFilter hat ein einzelnes Feld inventorySourceIds, in dem Sie die eindeutigen IDs der Inventarquellenressourcen angeben, die Sie in Ihren SDF aufnehmen möchten. Wenn die für inventorySourceIds angegebene Liste leer ist, werden alle Inventarquellen im festgelegten Kontext in das generierte SDF aufgenommen.

Anfrage stellen

Sobald Sie die Parameter des gewünschten SDF kennen, können Sie die Anfrage erstellen und die sdfdownloadtask erstellen.

Warnung: Ein einzelner Nutzer kann maximal 20 sdfdownloadtasks gleichzeitig ausführen. Bei weiteren Versuchen wird ein Fehler zurückgegeben.

Hier ein Beispiel für die Erstellung eines sdfdownloadtask mit einem 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());

Anfrage prüfen und Downloadpfad abrufen

Wenn Sie ein sdfdownloadtask erstellen, wird ein Vorgang-Objekt zurückgegeben. Dieser Vorgang gibt den Status des asynchronen SDF-Generierungsvorgangs zum Zeitpunkt der Erstellung an. Mit der Methode sdfdownloadtasks.operations.get kannst du prüfen, ob der Vorgang abgeschlossen ist und zum Download bereitsteht oder ob ein Fehler aufgetreten ist.

Hinweis: Je nach Größe der generierten SDFs kann der Vorgang einige Sekunden bis hin zu mehreren Stunden dauern. Um das Kontingent zu schonen, sollten Sie eine exponentielle Backoff-Zeit wie im folgenden Codebeispiel einführen.

Nach Abschluss enthält der zurückgegebene Vorgang ein Feld done, das nicht null ist. 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 Meldung, die Details zum aufgetretenen Fehler enthält. Wenn das Feld response vorhanden ist, enthält es ein Objekt mit dem Wert resourceName, der die generierte Datei für den Download identifiziert.

Hier ein Beispiel für die Überprüfung einer Anfrage mit exponentiellem Backoff:

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