File Data Terstruktur (SDF) adalah nilai yang dipisahkan koma (CSV) yang diformat secara khusus file yang digunakan untuk mengambil dan memperbarui data Display & Referensi Video 360 dalam dalam jumlah besar. Melalui Display & Video 360 API, Anda dapat membuat dan mendownload SDF yang disesuaikan, yang memungkinkan Anda mengambil data yang teratur dan difilter di kampanye Display & Video 360 Google Cloud Platform.
Panduan ini menjelaskan cara membuat operasi Download SDF, melacak aktivitas tersebut operasi, dan mengunduh SDF yang dihasilkan.
Informasi mengenai format dan pembuatan versi SDF dapat ditemukan di Dokumentasi referensi SDF.
Membuat tugas
SDF dihasilkan oleh operasi asinkron, yang disebut sdfdownloadtask.
Saat membuat tugas ini, Anda harus menentukan parameter terkait SDF yang diinginkan.
Hal ini dilakukan melalui metode sdfdownloadtasks.create. Tujuan
subbagian berikut menjelaskan parameter yang dapat Anda tetapkan.
Menentukan versi
Format File Data Terstruktur diperbarui secara rutin secara terpisah dari Layar & Video 360 API, dengan versi baru yang dirilis dan versi lama tidak digunakan lagi secara rutin. Untuk alasan ini, selalu disarankan agar pengguna menggunakan versi SDF terbaru.
Anda menyetel versi SDF dari SDF yang diinginkan menggunakan
Kolom version dalam isi permintaan. Jika tidak ditetapkan atau ditetapkan
ke SDF_VERSION_UNSPECIFIED, tugas akan menggunakan versi SDF default dari
pengiklan atau partner yang digunakan sebagai konteks konten SDF.
Menetapkan konteks
Anda dapat membuat SDF yang berisi data
pada sumber daya apa pun yang tersedia, tetapi
setiap SDF hanya dapat mengembalikan konten dalam konteks satu
partner atau pengiklan. Konteks ini didefinisikan dalam isi permintaan oleh
partnerId atau
Kolom advertiserId. Tepat satu dari dua ini
harus ditetapkan.
Hanya resource dalam konteks yang diberikan yang akan disertakan dalam SDF yang dihasilkan. Jika Anda mencoba memfilter menurut resource yang tidak dimiliki oleh partner yang ditentukan atau pengiklan, baik produk itu maupun konten di bawahnya tidak akan disertakan dalam hasil pengujian tersebut. Jika hanya memfilter berdasarkan resource yang tidak disertakan ini, file yang dihasilkan akan kosong. Mencoba memfilter menurut resource di luar konteks yang ditentukan tidak akan menampilkan error, jadi pastikan untuk memeriksa bahwa konteks Anda sudah sesuai benar.
Pilih filter yang tepat
Selain konteks yang ditetapkan di atas, Anda dapat memfilter lebih lanjut cakupan membuat File Data Terstruktur dengan menentukan jenis file yang ingin Anda dihasilkan dan sumber daya tertentu atau kelompok sumber daya yang ingin Anda sertakan.
Ada tiga filter yang tersedia untuk sdfdownloadtask, masing-masing melayani
jenis spesifikasi tertentu. Anda hanya dapat menetapkan
satu untuk satu
sdfdownloadtask.
ParentEntityFilter
ParentEntityFilter adalah yang paling luas dari
filter.
Dengan menggunakan kolom fileType, Anda dapat mencantumkan semua hal yang diinginkan
jenis file yang ingin dibuat dengan tugas Anda. Ini adalah
diperlukan, dan jika dibiarkan kosong atau ditetapkan ke FILE_TYPE_UNSPECIFIED,
sdfdownloadtask akan selesai tanpa error.
Menggunakan filterType dan
Kolom filterIds, Anda dapat menyaring hasil lebih lanjut.
filterType menentukan jenis
resource untuk memfilter dan filterIds
mengidentifikasi resource
berdasarkan ID uniknya. SDF yang dihasilkan
akan mencakup
resource yang diidentifikasi oleh fileType yang
sumber daya atau turunan dari
sumber daya yang diidentifikasi oleh
filterType dan filterIds.
IdFilter
IdFilter memfilter permintaan Anda agar hanya menyertakan resource
teridentifikasi.
IdFilter memiliki kolom untuk setiap jenis SDF, tidak termasuk Inventaris
Sumber. Setiap {i>field<i} ini adalah daftar
ID unik yang mengidentifikasi
sumber daya tertentu yang ingin Anda sertakan
dalam SDF yang dihasilkan. ID yang diberikan
harus berada dalam konteks yang ditetapkan, tetapi mereka tidak harus berkaitan langsung. Anda
tidak perlu meminta kampanye tertentu untuk meminta kampanye item baris
termuat, dan sebaliknya. Satu-satunya jenis file yang
dibuat adalah jenis
sesuai dengan referensi yang diidentifikasi di IdFilter.
InventorySourceFilter
InventorySourceFilter hanya memungkinkan pemfilteran
dan mendownload SDF yang berisi resource Sumber Inventaris. Ini adalah satu-satunya
yang dapat Anda gunakan untuk mendapatkan informasi
tentang sumber daya Sumber Inventaris.
InventorySourceFilter memiliki bentuk tunggal
Kolom inventorySourceIds tempat Anda mengidentifikasi
ID resource sumber inventaris yang ingin Anda sertakan dalam SDF. Jika
daftar yang diberikan ke inventorySourceIds kosong, semua
sumber inventaris berdasarkan konteks yang ditetapkan akan disertakan dalam SDF yang dibuat.
Buat permintaan
Setelah mengetahui parameter SDF yang diinginkan, Anda dapat membuat permintaan
dan membuat sdfdownloadtask.
Berikut contoh cara membuat sdfdownloadtask menggunakan
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());
Memeriksa permintaan dan mendapatkan jalur download
Saat Anda membuat sdfdownloadtask, objek operation akan
dikembalikan. Operasi ini merepresentasikan status SDF asinkron Anda
pada saat pembuatan. Anda dapat memeriksa
operasi Anda untuk
melihat apakah paket telah selesai dan siap diunduh, atau menampilkan pesan {i>error<i}, menggunakan
metode sdfdownloadtasks.operations.get.
Setelah selesai, operasi yang dikembalikan akan memiliki nilai {i>non-null<i}
Kolom done. Operasi yang sudah selesai akan mencakup
response atau error
kolom tersebut. Jika ada, kolom error akan memiliki
Objek Status yang berisi kode error dan
pesan, yang memberikan detail error yang
terjadi. Jika ada kolom response,
akan memiliki objek dengan nilai resourceName yang mengidentifikasi objek yang dibuat
untuk diunduh.
Berikut adalah contoh cara memeriksa permintaan menggunakan backoff eksponensial:
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']
);