ملفات البيانات المنظَّمة (SDF) هي ملفات قيم مفصولة بفواصل (CSV) منسَّقة بشكل خاص، وتُستخدَم لاسترداد وتعديل البيانات الخاصة بموارد "مساحة العرض والفيديو 360" بشكل مجمّع. من خلال واجهة برمجة التطبيقات الخاصة بـ "مساحة العرض والفيديو 360"، يمكنك إنشاء وتنزيل ملفات SDF مخصّصة، ما يتيح لك استرداد بيانات منظَّمة ومفلترة حول مواردك على "مساحة العرض والفيديو 360".
يوضّح هذا الدليل كيفية إنشاء عملية تنزيل ملفات SDF وتتبُّع هذه العملية وتنزيل ملفات SDF الناتجة.
يمكنك الاطّلاع على معلومات حول تنسيق SDF وإصداراته في المستندات المرجعية لتنسيق SDF.
إنشاء مهمّة
يتم إنشاء ملفات SDF من خلال عملية غير متزامنة تُعرف باسم sdfdownloadtask
.
عند إنشاء هذه المهمة، عليك تحديد المَعلمات المتعلّقة بتنسيقات SDF المطلوبة.
يتم ذلك من خلال الطريقة sdfdownloadtasks.create
. توضّح الأقسام الفرعية التالية المَعلمات التي يمكنك ضبطها.
تحديد إصدار
يتم تعديل تنسيق ملف البيانات المنظَّمة بانتظام بشكل مستقل عن واجهة برمجة التطبيقات في "مساحة العرض والفيديو 360"، ويتم إصدار إصدارات جديدة وإيقاف الإصدارات السابقة نهائيًا بانتظام. لهذا السبب، ننصح المستخدمين دائمًا باستخدام أحدث إصدار من SDF.
يمكنك ضبط إصدار SDF الذي تريده باستخدام الحقل version
في نص الطلب. في حال عدم ضبط هذا الحقل أو ضبطه على SDF_VERSION_UNSPECIFIED
، ستستخدِم المهمة إصدار SDF التلقائي الخاص بمورد المعلِن أو الشريك المستخدَم كسياق لمحتوى SDF.
تحديد السياق
يمكنك إنشاء ملف SDF يحتوي على بيانات حول أي موارد متاحة لك، ولكن يمكن لأي ملف SDF فردي عرض المحتوى ضمن سياق شريك أو معلِن واحد فقط. يتم تحديد هذا السياق في نص الطلب باستخدام الحقل partnerId
أو الحقل advertiserId
. يجب ضبط أحد هذين الحقلين فقط.
سيتم تضمين الموارد التي تندرج ضمن السياق المحدّد فقط في ملف SDF الناتج. إذا حاولت الفلترة حسب مورد لا يملكه الشريك أو المعلِن المحدّد، لن يتم تضمين هذا المورد أو المحتوى الوارد ضمنه في النتائج. في حال الفلترة حسب هذه الموارد غير المضمّنة فقط، ستكون الملفات الناتجة فارغة. لن يؤدي محاولة الفلترة حسب الموارد خارج السياق المحدّد إلى عرض خطأ، لذا احرص على التحقّق من صحة السياق.
اختيار الفلتر المناسب
بالإضافة إلى السياق المحدّد أعلاه، يمكنك فلترة نطاق ملفات البيانات المنظَّمة التي تم إنشاؤها بشكل أكبر من خلال تحديد أنواع الملفات التي تريد إنشاءها والمراجع المحدّدة أو مجموعة المراجع التي تريد تضمينها.
تتوفّر ثلاثة فلاتر لـ sdfdownloadtask
، ويستهدف كل فلتر نوعًا معيّنًا من المواصفات. يمكنك تخصيص رقم واحد فقط لكل sdfdownloadtask
.
ParentEntityFilter
ParentEntityFilter
هو الفلتر الأوسع نطاقًا بين الفلاتر المتاحة.
باستخدام الحقل fileType
، يمكنك إدراج جميع أنواع الملفات المطلوبة التي تريد إنشاءها باستخدام مهمتك. هذه السمة مطلوبة، وفي حال تركها فارغة أو ضبطها على FILE_TYPE_UNSPECIFIED
، لن يكتمل sdfdownloadtask
وسيظهر خطأ.
باستخدام الحقلين filterType
وfilterIds
، يمكنك تحسين نتائجك بشكل أكبر.
تحدّد filterType
نوع الموارد المطلوب فلترتها، وتحدّد filterIds
تلك الموارد من خلال رقم التعريف الفريد الخاص بها. ستتضمّن ملفات SDF الناتجة الموارد المحدّدة بواسطة fileType
التي تكون إما الموارد أو العناصر التابعة للموارد المحدّدة بواسطة filterType
وfilterIds
.
IdFilter
تعمل الفلاتر في IdFilter
على فلترة طلبك لتضمين المراجع المحدّدة فقط.
يحتوي IdFilter
على حقل لكل نوع من أنواع SDF، باستثناء "مصدر المستودع الإعلاني". كل حقل من هذه الحقول هو قائمة بمعرّفات فريدة تحدّد المراجع المحدّدة التي تريد تضمينها في ملف SDF الذي تم إنشاؤه. يجب أن تكون أرقام التعريف المقدَّمة ضمن مجموعة السياق، ولكن ليس من الضروري أن تكون مرتبطة بشكل مباشر. ليس عليك طلب حملة معيّنة من أجل طلب عنصر سطر يتضمّنه، والعكس صحيح. ستكون أنواع الملفات التي يتم إنشاؤها هي فقط تلك التي تتوافق مع الموارد المحددة في IdFilter
.
InventorySourceFilter
لا يسمح InventorySourceFilter
إلا بفلترة وتنزيل ملفات SDF التي تحتوي على موارد "مصدر المساحة الإعلانية". وهو الفلتر الوحيد الذي يمكنك استخدامه للحصول على معلومات حول موارد "مصدر المستودع الإعلاني".
يحتوي InventorySourceFilter
على حقل inventorySourceIds
مفرد تحدّد فيه المعرّفات الفريدة لموارد مصدر المستودع التي تريد تضمينها في ملف SDF. إذا كانت القائمة المقدَّمة إلى 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
.
عند الانتهاء، سيتضمّن العملية التي تم إرجاعها الحقل 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'] );