العرض سيتم إيقاف الإصدار 2 من Video 360 API نهائيًا في 3 أيلول (سبتمبر) 2024. ويجب نقل البيانات إلى الإصدار 3 قبل ذلك التاريخ لتجنُّب انقطاع الخدمة.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

نظرة عامة

ملفات البيانات المنظَّمة (SDF) هي قيم مفصولة بفواصل (CSV) بشكل خاص. الملفات المستخدمة لاسترداد بيانات "حملات الشبكة الإعلانية" موارد الفيديو 360 في بشكل مجمّع. من خلال الشاشة Video 360 API، يمكنك إنشاء فيديوهات SDF مخصّصة وتنزيلها يسمح لك باسترداد البيانات المنظمة والمفلترة على الشبكة الإعلانية فيديو 360 الموارد.

يصف هذا الدليل كيفية إنشاء عملية تنزيل SDF، وتتبع ذلك وتنزيل ملفات SDF الناتجة.

يمكن العثور على معلومات بخصوص تنسيق SDF وإصداراته في المستندات المرجعية لـ "SDF":

إنشاء مهمّة

يتم إنشاء SDF من خلال عملية غير متزامنة تُسمى sdfdownloadtask. عند إنشاء هذه المهمة، يمكنك تحديد المعلمات المتعلقة بـ SDF المطلوبة. يتم ذلك من خلال الطريقة sdfdownloadtasks.create. تشير رسالة الأشكال البيانية تصف الأقسام الفرعية التالية المعاملات التي يمكنك تعيينها.

تحديد إصدار

يتم تعديل تنسيق ملف البيانات المنظَّمة بشكل منتظم بصرف النظر عن العرض واجهة برمجة تطبيقات Video 360 API، تحتوي على إصدارات جديدة وأخرى قديمة متوقّفة نهائيًا بانتظام. لهذا السبب، من ننصح المستخدمين دائمًا باستخدام أحدث إصدار من SDF.

يمكنك ضبط إصدار 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، يكون كائن operation عاد. تمثل هذه العملية حالة SDF غير المتزامن عملية الإنشاء في وقت الإنشاء. يمكنك التحقق من عملياتك تأكَّد مما إذا كان قد اكتمل وجاهز للتنزيل أو عرض رسالة خطأ باستخدام الطريقة sdfdownloadtasks.operations.get.

بعد الانتهاء، سيكون للعملية التي تم إرجاعها قيمة غير فارغة done. ستشمل العملية النهائية إما response أو error . في حال توفّره، سيحتوي الحقل error على كائن Status يحتوي على رمز خطأ message، التي توفر تفاصيل الخطأ الذي حدث. إذا كان الحقل 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']
);

تنزيل الملفات