總覽

結構化資料檔案 (SDF) 採用特殊格式的逗號分隔值 (CSV) 用來擷取及更新多媒體廣告聯播網和 。透過多媒體廣告，您可以透過 Video 360 API 產生並下載自訂結構化資料檔案 擷取經過整理且經過篩選的資料影片 360 再複習一下，機構節點 是所有 Google Cloud Platform 資源的根節點

本指南將說明如何建立 SDF 下載作業，並追蹤 並下載產生的結構化資料檔案

如需瞭解 SDF 格式和版本管理，請前往 SDF 參考說明文件。

建立工作

SDF 是由名為 sdfdownloadtask 的非同步作業產生。 建立這項工作時，請定義所需結構化資料檔案的參數。 方法是透過 sdfdownloadtasks.create 方法完成。 下列子節將說明您可以設定的參數。

指定版本

結構化資料檔案格式會定期更新，不受 多媒體和Video 360 API，包含新版本和舊版本 會定期淘汰。因此 我們一律會建議使用者使用最新版的 SDF。

您需要使用 version 欄位。未設定或未設定 至 SDF_VERSION_UNSPECIFIED，這項工作會使用預設的 SDF 版本 做為 SDF 內容主題的廣告客戶或合作夥伴資源。

設定情境

您可產生含有可用資源資料的結構化資料檔案，但 任何個別 SDF 都只能傳回單一內容的 夥伴或廣告客戶這種背景是由 partnerId 或 advertiserId 欄位。恰好一個 就必須設定這些欄位。

只有指定環境中的資源才會納入產生的結構化資料檔案。 嘗試依非指定合作夥伴擁有的資源篩選時 廣告客戶或其下方的內容 也就是預測結果如果只依這些未包含的資源進行篩選，產生的檔案 將空白嘗試依指定情境外的資源篩選 不會傳回錯誤，因此請務必檢查您的內容 正確。

選擇適當的篩選器

除了上述情境設定之外，您還可以進一步篩選 方法是指定 和您要包含的特定資源或系列資源。

sdfdownloadtask 有三個可用的篩選器，每個篩選器都能支援 特定規格類型您只能為一項工作指派一個 ID sdfdownloadtask。

ParentEntityFilter

ParentEntityFilter 是最廣泛的 篩選器。

您可以使用 fileType 欄位列出所有需要的資訊 您想透過工作產生的檔案類型。這是 必要，如果留空或設為 FILE_TYPE_UNSPECIFIED，您的 sdfdownloadtask 會發生錯誤。

使用 filterType 和 filterIds 欄位，即可進一步縮小結果範圍。 filterType 會指定 資源，按filterIds篩選 以便依據專屬 ID 識別這些資源產生的結構化資料檔案包括 fileType 識別的資源 識別出資源 filterType和filterIds。

IdFilter

IdFilter 會篩選要求，只納入資源 找出問題所在

IdFilter 可為每個結構化資料檔案類型提供一個不含廣告空間的欄位 資料來源：每個欄位都屬於專屬 ID 清單，用來識別 新增要納入產生的結構化資料檔案提供的 ID 必須符合該情境元素，但不一定要直接相關。個人中心 不必請求特定廣告活動就能請求委刊項 包含，反之亦然才會產生的檔案類型 IdFilter 中識別的資源對應。

InventorySourceFilter

InventorySourceFilter 僅允許篩選 以及下載內含廣告空間來源資源的結構化資料檔案只有 篩選條件，您可以使用篩選條件取得廣告空間來源資源的資訊

InventorySourceFilter 具有單一 inventorySourceIds 欄位，可用來識別 您要在 SDF 中加入的廣告空間來源資源的 ID。如果 提供給 inventorySourceIds 的清單為空白。 系統會將您設定的結構定義下的廣告空間來源加到產生的 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 時，「作業」物件會是 。這項作業代表非同步結構化資料檔案的狀態 系統產生作業時您可以檢查作業 使用 Cloud Shell 指令列 sdfdownloadtasks.operations.get 方法。

完成後，傳回的作業會有非空值 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']
);
下一頁
下載檔案