概览

结构化数据文件 (SDF) 是采用特殊格式的逗号分隔值 (CSV) 用于检索和更新展示广告和展示广告相关数据此类别中的 Video 360 资源 批量。通过展示广告和借助 Video 360 API，您可以生成和下载自定义的结构化数据文件 让您可以在展示广告网络和广告系列以及视频 360 资源。

本指南介绍了如何创建 SDF 下载操作， 操作，然后下载生成的结构化数据文件。

有关 SDF 格式和版本控制的信息，请参阅 SDF 参考文档。

创建任务

SDF 由异步操作（称为 sdfdownloadtask）生成。 创建此任务时，您需要定义与所需 SDF 相关的参数。 这是通过 sdfdownloadtasks.create 方法完成的。通过 以下小节介绍了您可以设置的参数。

指定版本

结构化数据文件格式会定期更新，独立于 展示广告与Video 360 API，包括新版本和旧版本 定期弃用。因此， 始终建议用户使用最新版本的 SDF。

您可以使用 version 字段。如果未设置或未设置 更改为SDF_VERSION_UNSPECIFIED，任务将使用 用作结构化数据文件内容上下文的广告客户或合作伙伴资源。

设定背景

您可以生成一个包含任何可用资源数据的 SDF，但 任何一个 SDF 都只能返回 合作伙伴或广告客户。此上下文在请求正文中通过 partnerId 或 advertiserId 字段中的值。这两个选项中的一个 字段。

只有给定情境内的资源才会包含在生成的 SDF 中。 如果您尝试按不归指定合作伙伴所有的资源进行过滤 该记录及其下的内容都不会包含在 结果。如果仅按这些未包含的资源进行过滤，则生成的文件 将为空。尝试按给定上下文之外的资源进行过滤 应用不会返回错误，因此请务必检查 正确。

选择合适的过滤条件

除了上面设置的上下文之外，您还可以进一步过滤 通过指定要 以及您想要包含的特定资源或资源系列。

sdfdownloadtask有三种可用的过滤条件，分别适用于 特定的规范类型。您只能为一项 sdfdownloadtask。

ParentEntityFilter

ParentEntityFilter 是最宽泛的可用选项 过滤器。

使用 fileType 字段，您可以列出所有需要 文件类型。这是 如果留空或设置为 FILE_TYPE_UNSPECIFIED，则 sdfdownloadtask将会出错。

使用 filterType 和 filterIds 字段中，您可以进一步优化结果。 filterType 指定 可作为过滤条件的资源和filterIds 通过唯一 ID 标识这些资源。所生成的结构化数据文件将包含 由 fileType 标识的属于 资源或其子资源（由 filterType和filterIds。

IdFilter

IdFilter 会过滤您的请求，使其仅包含相应资源 。

IdFilter 针对每种 SDF 类型（不包括“广告资源”）都有一个对应的字段 来源。其中每个字段都是一个具有唯一性的 ID 列表，用于标识 您想在生成的结构化数据文件中包含的特定资源提供的 ID 必须在上下文集中，但不需要直接相关。您 就不需要请求特定广告系列即可请求订单项 反之亦然。系统将仅生成以下文件类型 与 IdFilter 中标识的资源相对应。

InventorySourceFilter

InventorySourceFilter 仅允许进行过滤 以及下载包含广告资源来源资源的结构化数据文件它是唯一 可用于获取有关您的广告资源来源资源的信息的过滤条件。

InventorySourceFilter 包含单数 inventorySourceIds 字段中，用来标识 您想在 SDF 中添加的广告资源来源资源的 ID。如果 提供给inventorySourceIds的列表为空， 所设情境下的广告资源来源将会包含在生成的 SDF 中。

发出请求

知道所需 SDF 的参数后，您就可以构建请求了 并创建 sdfdownloadtask。

以下示例展示了如何使用sdfdownloadtask 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());

检查您的请求并获取下载路径

当您创建 sdfdownloadtask 时，operation 对象 返回。此操作表示异步 SDF 的状态 创建操作您可以检查您的操作， 查看下载是否已完成并可供下载 sdfdownloadtasks.operations.get 方法。

完成后，返回的操作将具有非 null 值 done 字段。完成的操作将包括 response 或 error 字段。如果存在，error 字段将包含一个 包含错误代码的 Status 对象； 消息，其中会提供导致错误 错误。如果存在 response 字段， 将有一个值为 resourceName 的对象，该对象用于标识生成的 文件以供下载。

以下示例展示了如何使用指数退避算法检查请求：

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']
);
下一页
下载文件