ディスプレイとVideo 360 API v2 は廃止されます。[ディスプレイとVideo 360 API v3 を使用してください。v2 から v3 への移行手順については、移行ガイドをご覧ください。

このページは Cloud Translation API によって翻訳されました。

概要

構造化データファイル（SDF）は、ディスプレイ＆ビデオ 360 リソースに関するデータを一括で取得および更新するために使用される、特別な形式のカンマ区切り値（CSV）ファイルです。Display & Video 360 API を使用すると、カスタマイズした SDF を生成してダウンロードできます。これにより、ディスプレイ＆ビデオ 360 リソースに関する整理されたフィルタ済みデータを取得できます。

このガイドでは、SDF ダウンロードオペレーションを作成し、そのオペレーションを追跡して、生成された SDF をダウンロードする方法について説明します。

SDF の形式とバージョニングについては、SDF リファレンスドキュメントをご覧ください。

タスクを作成する

SDF は、sdfdownloadtask と呼ばれる非同期オペレーションによって生成されます。このタスクを作成するときに、目的の SDF に関するパラメータを定義します。この処理は、sdfdownloadtasks.create メソッドを介して行われます。以降のサブセクションでは、設定可能なパラメータについて説明します。

バージョンを指定する

構造化データファイルの形式は、ディスプレイ＆ビデオ 360 API とは別に定期的に更新されます。新しいバージョンがリリースされ、古いバージョンは定期的に非推奨になります。そのため、常に最新バージョンの SDF を使用することをおすすめします。

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

コンテキストを設定する

利用可能なリソースに関するデータを含む SDF を生成できますが、個々の SDF で返されるコンテンツは、単一のパートナーまたは広告主のコンテキスト内のものだけです。このコンテキストは、リクエスト本文の partnerId フィールドまたは advertiserId フィールドで定義します。これらの 2 つのフィールドのいずれかを設定する必要があります。

生成される SDF には、指定されたコンテキスト内にあるリソースのみが含まれます。指定したパートナーまたは広告主が所有していないリソースでフィルタしようとすると、そのリソースとその下のコンテンツは結果に含まれません。これらの除外リソースのみでフィルタリングする場合、生成されるファイルは空になります。指定されたコンテキスト外のリソースでフィルタリングしようとしてもエラーは返されません。コンテキストが正しいことを確認してください。

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

上記のコンテキストに加えて、生成するファイルタイプと、含める特定のリソースまたはリソースファミリーを指定することで、生成される構造化データファイルのスコープをさらにフィルタできます。

sdfdownloadtask には 3 つのフィルタがあり、それぞれ特定の仕様タイプに対応しています。1 つの sdfdownloadtask に割り当てることができるのは 1 つのみです。

ParentEntityFilter

ParentEntityFilter は、使用可能なフィルタの中で最も幅広いフィルタです。

fileType フィールドを使用すると、タスクで生成するファイルタイプをすべて一覧表示できます。これは必須です。空のままにするか FILE_TYPE_UNSPECIFIED に設定すると、sdfdownloadtask がエラーで完了します。

filterType フィールドと filterIds フィールドを使用すると、結果をさらに絞り込むことができます。filterType は、フィルタするリソースのタイプを指定し、filterIds はこれらのリソースを一意の ID で識別します。生成された SDF には、filterType と filterIds で識別されたリソースの子リソースまたはリソースである fileType で識別されたリソースが含まれます。

IdFilter

IdFilter: 識別されたリソースのみを含むようにリクエストをフィルタします。

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

InventorySourceFilter

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

InventorySourceFilter には、SDF に含めるインベントリソースリソースの一意の ID を指定できる inventorySourceIds フィールドが 1 つあります。inventorySourceIds に指定されたリストが空の場合、設定されたコンテキスト内のすべての広告枠ソースが生成された SDF に含まれます。

リクエストを作成する

目的の SDF のパラメータがわかったら、リクエストを作成して sdfdownloadtask を作成できます。

ParentEntityFilter を使用して sdfdownloadtask を作成する方法の例を次に示します。

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 オブジェクトがあり、発生したエラーの詳細が示されます。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']
);

ファイルをダウンロードする

概要 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

タスクを作成する

バージョンを指定する

コンテキストを設定する

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

ParentEntityFilter

IdFilter

InventorySourceFilter

リクエストを作成する

Java

Python

PHP

リクエストを確認してダウンロード パスを取得する

Java

Python

PHP

概要

リクエストを確認してダウンロードパスを取得する