স্ট্রাকচার্ড ডেটা ফাইল (SDFs) হল বিশেষভাবে ফরম্যাট করা কমা-সেপারেটেড ভ্যালু (CSV) ফাইল যা প্রচুর পরিমাণে Display & Video 360 রিসোর্স সম্পর্কে ডেটা পুনরুদ্ধার এবং আপডেট করতে ব্যবহৃত হয়। Display & Video 360 API-এর মাধ্যমে, আপনি কাস্টমাইজড SDF তৈরি এবং ডাউনলোড করতে পারেন, যা আপনাকে আপনার Display & Video 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 ফিল্ড দ্বারা অনুরোধের অংশে সংজ্ঞায়িত করা হয়েছে। ঠিক এই দুটি ক্ষেত্রের একটি সেট করা আবশ্যক.
শুধুমাত্র প্রদত্ত প্রেক্ষাপটের মধ্যে থাকা সংস্থানগুলি ফলস্বরূপ SDF-এ অন্তর্ভুক্ত করা হবে৷ আপনি যদি এমন একটি সংস্থান দ্বারা ফিল্টার করার চেষ্টা করেন যা নির্দিষ্ট অংশীদার বা বিজ্ঞাপনদাতার মালিকানাধীন নয়, তবে এটি বা এটির অধীনে থাকা বিষয়বস্তুও ফলাফলে অন্তর্ভুক্ত হবে না। যদি শুধুমাত্র এই অন্তর্ভূক্ত সংস্থানগুলি দ্বারা ফিল্টার করা হয়, ফলে ফাইলগুলি খালি হবে৷ প্রদত্ত প্রসঙ্গের বাইরে সংস্থান দ্বারা ফিল্টার করার চেষ্টা করা কোনও ত্রুটি ফেরত দেবে না , তাই আপনার প্রসঙ্গটি সঠিক কিনা তা নিশ্চিত করুন।
সঠিক ফিল্টার চয়ন করুন
উপরে সেট করা প্রসঙ্গ ছাড়াও, আপনি যে ফাইলগুলি তৈরি করতে চান এবং যে নির্দিষ্ট সংস্থান বা সংস্থানগুলি আপনি অন্তর্ভুক্ত করতে চান তা নির্দিষ্ট করে আপনার জেনারেট করা স্ট্রাকচার্ড ডেটা ফাইলগুলির সুযোগকে আরও ফিল্টার করতে পারেন।
একটি sdfdownloadtask এর জন্য তিনটি উপলব্ধ ফিল্টার রয়েছে, প্রতিটি একটি নির্দিষ্ট স্পেসিফিকেশন টাইপ পূরণ করে। আপনি একটি একক sdfdownloadtask এর জন্য শুধুমাত্র একটি বরাদ্দ করতে পারেন।
ParentEntityFilter
ParentEntityFilter উপলব্ধ ফিল্টারগুলির মধ্যে সবচেয়ে বিস্তৃত।
fileType ক্ষেত্রটি ব্যবহার করে, আপনি আপনার টাস্কের সাথে তৈরি করতে চান এমন সমস্ত পছন্দসই ফাইল প্রকারের তালিকা করতে পারেন। এটি প্রয়োজন, এবং যদি খালি রাখা হয় বা FILE_TYPE_UNSPECIFIED তে সেট করা হয়, আপনার sdfdownloadtask ভুলবশত সম্পূর্ণ হবে৷
filterType এবং filterIds ক্ষেত্রগুলি ব্যবহার করে, আপনি আপনার ফলাফলগুলিকে আরও পরিমার্জিত করতে পারেন৷ filterType দ্বারা ফিল্টার করার জন্য সংস্থানগুলির ধরন নির্দিষ্ট করে এবং filterIds তাদের অনন্য আইডি দ্বারা সেই সংস্থানগুলি সনাক্ত করে। ফলস্বরূপ SDFs fileType দ্বারা চিহ্নিত সংস্থানগুলিকে অন্তর্ভুক্ত করবে যা হয় সম্পদ বা filterType এবং filterIds দ্বারা চিহ্নিত সংস্থানগুলির সন্তান৷
আইডিফিল্টার
IdFilter শুধুমাত্র চিহ্নিত সম্পদ অন্তর্ভুক্ত করার জন্য আপনার অনুরোধ ফিল্টার করে।
IdFilter প্রতিটি SDF প্রকারের জন্য একটি ক্ষেত্র রয়েছে, ইনভেন্টরি উত্স ব্যতীত৷ এই ক্ষেত্রগুলির প্রত্যেকটি অনন্য আইডিগুলির একটি তালিকা যা নির্দিষ্ট সংস্থানগুলিকে চিহ্নিত করে যা আপনি আপনার তৈরি SDF-এ অন্তর্ভুক্ত করতে চান৷ প্রদত্ত আইডিগুলি অবশ্যই প্রসঙ্গ সেটের মধ্যে থাকতে হবে, তবে তাদের সরাসরি সম্পর্কিত হতে হবে না। এটিতে থাকা একটি লাইন আইটেম অনুরোধ করার জন্য আপনাকে একটি নির্দিষ্ট প্রচারাভিযানের অনুরোধ করার প্রয়োজন নেই এবং এর বিপরীতে। IdFilter এ চিহ্নিত সংস্থানগুলির সাথে সংশ্লিষ্ট ফাইলের ধরনগুলিই তৈরি করা হবে৷
ইনভেন্টরি সোর্স ফিল্টার
InventorySourceFilter শুধুমাত্র ইনভেন্টরি সোর্স রিসোর্স ধারণকারী SDF ফিল্টারিং এবং ডাউনলোড করার অনুমতি দেয়। এটি একমাত্র ফিল্টার যা আপনি আপনার ইনভেন্টরি সোর্স সংস্থানগুলির তথ্য পেতে ব্যবহার করতে পারেন৷
InventorySourceFilter একটি একক inventorySourceIds ক্ষেত্র রয়েছে যেখানে আপনি আপনার SDF-এ যে ইনভেন্টরি সোর্স রিসোর্সগুলি অন্তর্ভুক্ত করতে চান তার অনন্য আইডি শনাক্ত করেন৷ inventorySourceIds দেওয়া তালিকা খালি থাকলে, সেট প্রেক্ষাপটের অধীনে সমস্ত ইনভেন্টরি উত্স জেনারেট করা SDF-এ অন্তর্ভুক্ত করা হবে।
একটি অনুরোধ করুন
একবার আপনি আপনার পছন্দসই SDF-এর পরামিতিগুলি জানলে, আপনি অনুরোধটি তৈরি করতে এবং sdfdownloadtask তৈরি করতে পারেন।
একটি ParentEntityFilter ব্যবহার করে কিভাবে একটি sdfdownloadtask তৈরি করতে হয় তার একটি উদাহরণ এখানে দেওয়া হল:
জাভা
// 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());
পাইথন
# 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"])
পিএইচপি
// 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 পদ্ধতিটি ব্যবহার করে আপনি আপনার অপারেশনটি পরীক্ষা করে দেখতে পারেন যে এটি সম্পূর্ণ হয়েছে এবং ডাউনলোডের জন্য প্রস্তুত কিনা বা একটি ত্রুটি ছুঁড়েছে।
সমাপ্তির পরে, ফিরে আসা ক্রিয়াকলাপে একটি নন-নাল done ফিল্ড থাকবে। সমাপ্ত অপারেশন হয় একটি response বা error ক্ষেত্র অন্তর্ভুক্ত করা হবে. যদি উপস্থিত থাকে, error ক্ষেত্রটিতে একটি Status অবজেক্ট থাকবে যার মধ্যে একটি ত্রুটি কোড এবং বার্তা রয়েছে, যা ঘটে যাওয়া ত্রুটির বিশদ প্রদান করে। যদি response ক্ষেত্রটি উপস্থিত থাকে তবে এটিতে একটি resourceName মান সহ একটি বস্তু থাকবে যা ডাউনলোডের জন্য উত্পন্ন ফাইলটিকে সনাক্ত করে৷
সূচকীয় ব্যাকঅফ ব্যবহার করে কীভাবে আপনার অনুরোধটি পরীক্ষা করবেন তার একটি উদাহরণ এখানে রয়েছে:
জাভা
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());
পাইথন
# 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))
পিএইচপি
// 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']
);