ملفات البيانات المنظَّمة هي ملفات ملفّات CSV (قيم مفصولة بفواصل) منسَّقة بشكل خاص تُستخدَم لاسترداد بيانات عن موارد "مساحة العرض والفيديو 360" وتعديلها في الطريقة المجمّعة. من خلال Display & Video 360 API، يمكنك إنشاء ملفات 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'] );