概要

構造化データファイル（SDF）は特殊な形式のカンマ区切り値（CSV） 使用されるファイルです。Google のビデオ 360 リソース できます。ディスプレイとVideo 360 API を使用して、カスタマイズされた SDF を生成、ダウンロードできます。 整理、フィルタリングされたデータをディスプレイ &ビデオ 360 で動画 360 説明します。

このガイドでは、SDF ファイルのダウンロード操作を作成し、 結果の SDF をダウンロードします。

SDF ファイルの形式とバージョニングに関する情報については、 SDF のリファレンス ドキュメント

タスクを作成する

SDF は、sdfdownloadtask という非同期オペレーションで生成されます。 このタスクを作成する際、必要な SDF に関するパラメータを定義します。 これを行うには sdfdownloadtasks.create メソッドを使用します。「 以降のサブセクションでは、設定できるパラメータについて説明します。

バージョンを指定する

構造化データファイルの形式は、 ディスプレイとVideo 360 API（新バージョンのリリースと旧バージョンを含む） 定期的に非推奨になります。このため、 常に最新バージョンの SDF を使用することを強く推奨します。

使用する SDF の SDF バージョンは、 リクエスト本文の version フィールド。未設定または設定した場合 SDF_VERSION_UNSPECIFIED に設定すると、デフォルトの SDF バージョンが使用されます。 広告主やパートナーのリソースを SDF コンテンツのコンテキストとして使用します。

コンテキストを設定する

利用可能なリソースについてのデータを含む SDF は生成できますが、 個々の SDF で返されるのは、1 つの 選択しますこのコンテキストは、リクエストの本文で次のいずれかによって定義されます。 partnerId または advertiserId フィールド。この 2 つのいずれか の各フィールドを設定する必要があります。

作成される SDF には、指定されたコンテキスト内のリソースのみが含まれます。 指定したパートナーが所有していないリソースでフィルタしようとした場合 そのコンテンツやその下のコンテンツは 表示されます。これらの含まれないリソースのみでフィルタすると、結果のファイルは は空になります。指定されたコンテキスト外のリソースでフィルタしようとした エラーは返されません。コンテキストが一致していることを 正解。

適切なフィルタを選択する

上記のコンテキストに加えて、コンテキストの範囲をさらにフィルタできます。 使用するファイル形式を指定して、生成された構造化データファイル 含める必要がある特定のリソースやリソースファミリーを指定します。

sdfdownloadtask には 3 つのフィルタがあり、それぞれに対応するフィルタが 特定の仕様タイプをモニタリングできます。1 つのシステムに対して割り当てることができるのは 1 つのみです sdfdownloadtask。

ParentEntityFilter

ParentEntityFilter は利用可能な中で最も広範です フィルタできます。

fileType フィールドを使用すると、必要なすべてのリソースを ファイル形式。これは、 必須です。空のままにするか FILE_TYPE_UNSPECIFIED に設定した場合は、 sdfdownloadtask は間違って完了します。

filterType と filterIds 個のフィールドで、結果をさらに絞り込むことができます。 filterType には、Cloud Storage の フィルタするリソースと、filterIds を使用します は、これらのリソースを一意の ID で識別します。作成された SDF ファイルには、 fileType で識別される、次のいずれかのリソース そのリソースの子または子孫を filterType、filterIds。

IdFilter

IdFilter は、リソースのみが含まれるようにリクエストをフィルタします。 特定できます。

IdFilter では、広告枠を除くすべての SDF タイプに対応するフィールドがある 出典。これらの各フィールドは、一意の ID のリストで、 追加したい特定のリソースを指定する 必要があります指定された ID コンテキスト セット内にある必要がありますが、直接関連している必要はありません。マイページ 特定のキャンペーンの広告申込情報をリクエストしなくても、 できます。その逆も同様です。生成されるファイル形式は、この IdFilter で識別されるリソースに対応する。

InventorySourceFilter

InventorySourceFilter ではフィルタのみを使用できます。 広告枠ソース リソースを含む SDF のダウンロードなど、これは、 フィルタを使って、広告枠ソースのリソースに関する情報を取得できます。

InventorySourceFilter は単数形です 一意の ID を識別する 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 を作成すると、オペレーション オブジェクトが作成されます。 返されます。このオペレーションは、非同期 SDF のステータスを表します。 作成時に生成されます。オペレーションの状況を 次のコマンドを使用して、ダウンロードが完了してダウンロード可能な状態になっているか、エラーがスローされたかを確認します。 sdfdownloadtasks.operations.get メソッド

終了すると、返されるオペレーションは null 以外の値になります。 done フィールド。完了するオペレーションには、次のいずれかが含まれます。 response または error 表示されます。存在する場合、error フィールドには エラーコードを含む Status オブジェクト。 message: 発生したエラーの詳細 発生しました。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']
);
次へ
ファイルをダウンロードする