構造化データファイル（SDF）は、特別な形式のカンマ区切り値（CSV）ファイルで、ディスプレイ &ビデオ 360 のリソースに関するデータをまとめて取得、更新するために使用します。また、カスタマイズした SDF ファイルを生成、ダウンロードし、ディスプレイ&ビデオ 360 リソース上でフィルタして整理されたデータを取得できます。
このガイドでは、SDF のダウンロード オペレーションの作成方法、そのオペレーションのトラッキング方法、作成された SDF ファイルのダウンロード方法について説明します。
SDF の形式とバージョニングについては、SDF ファイルのリファレンス ドキュメントをご覧ください。
タスクを作成する
SDF は、sdfdownloadtask と呼ばれる非同期処理によって生成されます。このタスクを作成する際に、目的の SDF ファイルに関するパラメータを定義します。
そのためには、sdfdownloadtasks.create メソッドを使用します。以降のサブセクションでは、設定できるパラメータについて説明します。
バージョンを指定する
構造化データファイル形式は、Display & Video 360 API とは関係なく定期的に更新され、新しいバージョンがリリースされ、古いバージョンは定期的にサポート終了となります。そのため、常に最新バージョンの SDF を使用することをおすすめします。
リクエスト本文の version フィールドで、目的の SDF の SDF バージョンを設定します。このポリシーを設定しないか SDF_VERSION_UNSPECIFIED に設定した場合、タスクでは SDF コンテンツのコンテキストとして使用される広告主またはパートナー リソースのデフォルトの SDF バージョンが使用されます。
コンテキストを決める
利用可能なリソースのデータを含む SDF を生成できますが、個々の SDF が返すことができるコンテンツは、単一のパートナーまたは広告主に関するものに限られます。このコンテキストは、リクエストの本文で partnerId フィールドまたは advertiserId フィールドによって定義されます。この 2 つのフィールドのいずれか 1 つのみを設定する必要があります。
指定したコンテキスト内のリソースのみが、SDF ファイルが作成されます。 指定したパートナーまたは広告主が所有していないリソースでフィルタしようとすると、そのリソースも、その下のコンテンツも結果に含まれません。これらの除外されたリソースだけでフィルタすると、生成されるファイルは空になります。指定されたコンテキスト以外のリソースでフィルタリングしようとすると、エラーは返されません。コンテキストが正しいことを確認してください。
適切なフィルタを選択する
前述のコンテキスト セットに加えて、生成するファイル形式と、含める特定のリソースまたはリソース ファミリーを指定することで、生成される構造化データファイルの範囲をさらにフィルタリングできます。
sdfdownloadtask には 3 つのフィルタがあり、それぞれ特定の仕様タイプに対応しています。1 つの sdfdownloadtask に割り当てることができるのは 1 つのみです。
ParentEntityFilter
ParentEntityFilter は、使用可能なフィルタの中で最も広い範囲です。
fileType フィールドを使用すると、タスクで生成するすべてのファイル形式を一覧表示できます。これは必須であり、空のままにするか FILE_TYPE_UNSPECIFIED に設定すると、sdfdownloadtask はエラーで完了します。
filterType フィールドと filterIds フィールドを使用すると、結果をさらに絞り込むことができます。filterType は、フィルタするリソースのタイプを指定し、filterIds を一意の ID でそれらのリソースを識別します。作成された SDF ファイルには、fileType で識別されるリソースが含まれます。これらは、filterType と filterIds で識別されるリソースの子か、そのリソースです。
IdFilter
IdFilter は、識別されたリソースのみが含まれるようにリクエストをフィルタします。
IdFilter には、広告枠ソースを除くすべての SDF タイプに対応するフィールドがあります。各フィールドは、生成された SDF に含める特定のリソースを識別する一意の ID のリストです。指定する ID はコンテキスト セット内に存在する必要がありますが、直接関連付ける必要はありません。それに含まれる広告申込情報をリクエストするために、特定のキャンペーンをリクエストする必要はありません。その逆も同様です。生成されるファイル形式は、IdFilter で指定されたリソースに対応するファイル形式のみです。
InventorySourceFilter
InventorySourceFilter では、広告枠ソース リソースを含む SDF のフィルタリングとダウンロードのみが許可されます。これは、広告枠ソースのリソースに関する情報を取得するために使用できる唯一のフィルタです。
InventorySourceFilter には単一の inventorySourceIds フィールドがあります。このフィールドは、SDF ファイルに含めるインベントリ ソース リソースの一意の ID を指定します。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']
);