Übersicht

Strukturierte Datendateien (Structured Data Files, SDFs) sind speziell formatierte kommagetrennte Werte (CSV) Dateien zum Abrufen und Aktualisieren von Daten zu Display- und Video 360-Ressourcen in Massenanzeige. Über die Display- und Video 360 API können Sie benutzerdefinierte strukturierte Datendateien, können Sie organisierte, gefilterte Daten auf Ihrem Display und Video 360 Ressourcen.

In diesem Leitfaden erfahren Sie, wie Sie einen SDF-Download-Vorgang erstellen. und laden Sie die SDFs herunter.

Informationen zum Format und zur Versionsverwaltung der strukturierten Datendateien finden Sie in der SDF-Referenzdokumentation

Aufgaben 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 strukturierten Datendateien. Dazu verwenden Sie die Methode sdfdownloadtasks.create. Die 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 vom Display- und Video 360 API mit veröffentlichten neuen und alten Versionen regelmäßig eingestellt. Aus diesem Grund Nutzern immer die neueste Version der strukturierten Datendateien empfohlen.

Die SDF-Version der gewünschten SDF legen Sie mithilfe der version im Anfragetext. Wenn nicht festgelegt oder festgelegt auf SDF_VERSION_UNSPECIFIED gesetzt ist, verwendet die Aufgabe die SDF-Standardversion des Ressource des Werbetreibenden oder Partners, die für den Inhalt der strukturierten Datendatei verwendet wird

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

Kontext festlegen

Sie können eine strukturierte Datendatei mit Daten zu allen Ihnen zur Verfügung stehenden Ressourcen erstellen. Jede einzelne strukturierte Datendatei kann Inhalte nur im Kontext einer einzelnen Partner oder Werbetreibenden. Dieser Kontext wird im Anfragetext entweder durch den partnerId oder advertiserId. Genau eines dieser beiden müssen festgelegt werden.

Nur Ressourcen im angegebenen Kontext werden in die erstellte strukturierte Datendatei aufgenommen. Wenn Sie versuchen, nach einer Ressource zu filtern, die nicht dem angegebenen Partner gehört werden weder sie noch der darunterliegende Content in das Ergebnisse. Wenn nur nach diesen nicht eingeschlossenen Ressourcen gefiltert wird, ist leer. Versuch, nach Ressourcen außerhalb des angegebenen Kontexts zu filtern wird keinen Fehler zurückgeben. Stellen Sie daher sicher, dass Ihr Kontext richtig.

Den richtigen Filter auswählen

Neben dem oben angegebenen Kontext können Sie den Umfang Ihrer die strukturierten Datendateien generiert, indem Sie die Dateitypen angeben, und die spezifischen Ressourcen oder Ressourcenfamilien, die Sie aufnehmen möchten.

Hinweis: Der Typ einer strukturierten Datendatei gibt den Ressourcentyp vor, der für diese Datei. Jeder Dateityp hat eine andere Spaltenstruktur. mit den für diese Ressource verfügbaren Informationen.

Für sdfdownloadtask sind drei Filter verfügbar, die jeweils für einen bestimmten Spezifikationstyp. Sie können einer einzelnen Person nur eine sdfdownloadtask

ParentEntityFilter

ParentEntityFilter ist die umfassendste der verfügbaren Filter.

Im Feld fileType können Sie alle gewünschten Dateitypen, die Sie mit Ihrer Aufgabe generieren möchten. Dies ist erforderlich. Wenn Sie das Feld leer oder auf FILE_TYPE_UNSPECIFIED festlegen, sdfdownloadtask wird versehentlich abgeschlossen.

Mithilfe von filterType und filterIds können Sie die Ergebnisse weiter verfeinern. filterType gibt den Typ der Ressourcen, nach denen gefiltert werden soll, und filterIds identifiziert diese Ressourcen anhand ihrer eindeutigen ID. Die erstellten strukturierten Datendateien enthalten Die von fileType identifizierten Ressourcen, die entweder die Ressourcen oder untergeordneten Ressourcen, filterType und filterIds.

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

IdFilter

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

In IdFilter gibt es ein Feld für jeden SDF-Typ, ausschließlich Inventar Quelle. Jedes dieser Felder ist eine Liste eindeutiger IDs zur Identifizierung der bestimmte Ressourcen, die Sie in die erstellte SDF aufnehmen möchten. Die angegebenen IDs müssen im Kontext liegen, aber nicht direkt zusammenhängen. Ich ohne eine bestimmte Kampagne anzufordern, um eine Werbebuchung anzufordern, und umgekehrt. Es werden nur die folgenden Dateitypen generiert: entspricht den in IdFilter angegebenen Ressourcen.

InventorySourceFilter

Bei InventorySourceFilter ist nur die Filterung möglich. und das Herunterladen von strukturierten Datendateien mit Inventarquellenressourcen. Es ist das einzige Filter, mit dem Sie Informationen zu Ihren Inventarquellenressourcen abrufen können.

InventorySourceFilter hat einen Singular inventorySourceIds-Feld, in dem Sie die eindeutige IDs der Inventarquellenressourcen, die Sie in die SDF aufnehmen möchten. Wenn die Die für inventorySourceIds bereitgestellte Liste ist leer, da alle Inventarquellen im festgelegten Kontext werden in die generierte strukturierte Datendatei aufgenommen.

Anfrage stellen

Sobald Sie die Parameter der gewünschten strukturierten Datendatei kennen, können Sie die Anfrage erstellen. und erstelle das sdfdownloadtask.

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

Hier ein Beispiel für das Erstellen 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, ist ein operation-Objekt zurückgegeben. Dieser Vorgang gibt den Status der asynchronen SDF-Datei wieder zum Zeitpunkt der Erstellung. Sie können den Vorgang überprüfen, um können Sie sehen, ob sie abgeschlossen ist und heruntergeladen werden kann oder ob ein Fehler Methode sdfdownloadtasks.operations.get

Hinweis :Je nach Größe der erstellten strukturierten Datendateien kann der Vorgang zwischen wenigen Sekunden und einigen Stunden. Um Kontingente zu sparen, führen Sie einen exponentiellen Backoff wie im Codebeispiel unten ein.

Nach Abschluss des Vorgangs hat der zurückgegebene Vorgang eine Nicht-Null-Werte. done-Feld. Der abgeschlossene Vorgang enthält entweder response oder error ein. Falls vorhanden, enthält das Feld error Status-Objekt mit einem Fehlercode und Nachricht mit Details zum Fehler, aufgetreten. Wenn das Feld response vorhanden ist, hat ein Objekt mit einem resourceName-Wert, der das generierte herunterladen können.

Hier ist ein Beispiel, 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']
);