طلبات مجمّعة

يعرض هذا المستند كيفية تجميع طلبات البيانات من واجهة برمجة التطبيقات معًا لتقليل عدد اتصالات HTTP. التي يتعين على عميلك إجراؤها.

يدور هذا المستند تحديدًا حول إجراء طلب مجمّع من خلال إرسال طلب HTTP. بدلاً من ذلك، إذا كنت تستخدم مكتبة برامج Google لإنشاء طلب مُجمَّع، يُرجى الاطّلاع على مستندات مكتبة البرامج.

نظرة عامة

ينتج عن كل اتصال HTTP للعميل مقدار معين من النفقات العامة. الشاشة تتيح واجهة برمجة التطبيقات Video 360 API التجميع للسماح للعميل بوضع العديد من طلبات البيانات من واجهة برمجة التطبيقات في طلب HTTP واحد.

أمثلة على الحالات التي قد تحتاج فيها إلى استخدام التجميع:

  • استرداد الموارد على مستوى عدة معلنين.
  • إنشاء الموارد أو تعديلها بشكل مجمّع
  • جارٍ تعديل الاستهداف على مستوى عناصر متعددة.

وفي كل حالة، بدلاً من إرسال كل استدعاء على حدة، يمكنك تجميعها معًا في طلب HTTP واحد. يجب أن تنتقل جميع الطلبات الداخلية إلى نفس واجهة برمجة تطبيقات Google.

الحد المسموح به هو 1000 مكالمة في طلب مُجمَّع واحد. إذا كان عليك إجراء مكالمات أكثر من ذلك، استخدِم طلبات مُجمَّعة متعددة.

ملاحظة: نظام الدُفعة لجهاز العرض تستخدم Video 360 API البنية نفسها التي يستخدمها نظام معالجة دُفعات OData، ولكن تختلف دلالات الدلالة.

تفاصيل الدفعة

يتألف الطلب المجمّع من طلبات بيانات متعددة من واجهة برمجة التطبيقات مدمجة في طلب HTTP واحد، ويمكن إرسال هذه الطلبات إلى batchPath المحدّد في مستند استكشاف واجهة برمجة التطبيقات. المسار التلقائي هو /batch/api_name/api_version. يصف هذا القسم بنية الدفعة بالتفصيل؛ لاحقًا، يوجد مثال.

ملاحظة: يتم احتساب مجموعة الطلبات البالغ عددها n المجمَّعة ضمن حدّ الاستخدام على أنّها n طلب، وليس كطلب واحد. يتم فصل الطلب المجمّع إلى مجموعة من الطلبات قبل معالجته.

تنسيق الطلب المجمّع

الطلب المجمّع هو طلب HTTP قياسي واحد يحتوي على العديد من وحدات العرض طلبات البيانات من واجهة برمجة التطبيقات للفيديوهات 360، باستخدام نوع المحتوى multipart/mixed وضمن طلب HTTP الرئيسي هذا، يحتوي كل جزء من الأجزاء على طلب HTTP مدمج.

يبدأ كل جزء بعنوان HTTP يتضمّن Content-Type: application/http خاص به. ويمكن أن يحتوي أيضًا على عنوان Content-ID اختياري. ومع ذلك، فإن رؤوس الجزء موجودة فقط لتمييز بداية الجزء؛ أنها منفصلة عن الطلب المتداخل. بعد أن يفتح الخادم الطلب المجمّع في طلبات منفصلة، يتم تجاهل عناوين الأجزاء.

النص الأساسي لكل جزء هو طلب HTTP كامل، يضم فعل وعنوان URL ورؤوس ونص. يجب أن يحتوي طلب HTTP فقط على جزء المسار من عنوان URL، غير مسموح بعناوين URL الكاملة في الطلبات المجمّعة.

تنطبق عناوين HTTP للطلب المجمّع الخارجي، باستثناء عناوين Content-، مثل Content-Type، على كل طلب في الدُفعة. إذا حددت عنوان HTTP معينًا في كل من الطلب الخارجي والاستدعاء الفردي، فإن قيمة عنوان الاستدعاء الفردي ستلغي قيمة رأس طلب الدفعة الخارجية. ولا تنطبق عناوين مكالمة فردية إلا على تلك المكالمة.

مثلاً، في حال توفير عنوان التفويض لاستدعاء معيّن، سيتم تطبيق هذا العنوان على ذلك الاستدعاء فقط. في حال توفير عنوان تفويض للطلب الخارجي، سيتم تطبيق هذا العنوان على جميع الطلبات الفردية ما لم يتم تجاوزه باستخدام عناوين التفويض الخاصة بها.

عندما يتلقى الخادم الطلب المجمّع، يطبق معلمات الاستعلام والعناوين الخاصة بالطلب الخارجي (حسب الحاجة) على كل جزء، ثم يعامل كل جزء كما لو كان طلب HTTP منفصلاً.

الرد على طلب مجمّع

استجابة الخادم هي استجابة HTTP عادية واحدة تتضمّن نوع محتوى multipart/mixed. وكل جزء هو الرد على أحد الطلبات في الطلب المجمّع، بنفس ترتيب الطلبات.

كما هو الحال مع الأجزاء في الطلب، يحتوي كل جزء استجابة على استجابة HTTP كاملة، بما في ذلك رمز الحالة والعناوين والنص. وكما هو الحال مع الأجزاء في الطلب، يسبق كل جزء استجابة عنوان Content-Type يشير إلى بداية الجزء.

إذا كان جزء معيّن من الطلب يتضمّن عنوان Content-ID، هذا يعني أنّ الجزء المقابل من الاستجابة له عنوان Content-ID مطابق، وتكون القيمة الأصلية مسبوقة بالسلسلة response-، كما هو موضّح في المثال التالي.

ملاحظة: قد يُجري الخادم مكالماتك بأي ترتيب. لا تعتمد على تنفيذها بالترتيب الذي حدّدتها. إذا كنت تريد التأكّد من إجراء مكالمتَين بترتيب معيّن، لا يمكنك إرسالهما في طلب واحد. بدلاً من ذلك، أرسِل الردّ الأول وحده، ثم انتظِر الرد على الرسالة الأولى قبل إرسال الردّ الثاني.

مثال

يوضح المثال التالي استخدام التجميع مع الشاشة Video 360 API:

مثال على طلب مجمّع

POST /batch HTTP/1.1
Host: displayvideo.googleapis.com
Authorization: Bearer your_auth_code
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length

--batch_foobarbaz
Content-Type: application/http
Content-Transfer-Encoding: binary
MIME-Version: 1.0
Content-ID: <item1:12930812@displayvideo.example.com>

PATCH /v1/advertisers/advertiser_id?updateMask=displayName&fields=advertiserId,displayName HTTP/1.1
Content-Type: application/json; charset=UTF-8
Authorization: Bearer your_auth_code

{
  "displayName": "Updated Advertiser Name"
}
--batch_foobarbaz
Content-Type: application/http
Content-Transfer-Encoding: binary
MIME-Version: 1.0
Content-ID: <item2:12930812@displayvideo.example.com>

PATCH /v1/advertisers/advertiser_id/lineItems/line_item_id?updateMask=displayName&fields=lineItemId,displayName HTTP/1.1
Content-Type: application/json; charset=UTF-8
Authorization: Bearer your_auth_code

{
  "displayName": "Updated Line Item Name"
}

--batch_foobarbaz--

مثال على الرد المجمّع

هذه هي الاستجابة للطلب النموذجي في القسم السابق.

HTTP/1.1 200
Content-Length: response_total_content_length
Content-Type: multipart/mixed; boundary=batch_foobarbaz

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item1:12930812@displayvideo.example.com>

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: response_part_1_content_length

{
  "advertiserId": advertiser_id,
  "displayName": "Updated Advertiser Name"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:12930812@displayvideo.example.com>

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: response_part_2_content_length

{
  "lineItemId": line_item_id,
  "displayName": "Updated Line Item Name"
}

--batch_foobarbaz--

استخدام مكتبات العملاء

توضح نماذج التعليمات البرمجية التالية كيفية تقديم طلبات مجمّعة باستخدام مكتبات عملاء Google APIs اطّلِع على أدلة البدء السريع ذات الصلة لمعرفة المزيد عن كيفية تثبيت المكتبات وإعدادها.

Java

Long advertiserId = advertiser-id;
List<Long> lineItemIds = Arrays.asList(line-item-id-1, line-item-id-2);

BatchRequest batch = service.batch();
JsonBatchCallback<LineItem> callback = new JsonBatchCallback<LineItem>() {
  public void onSuccess(LineItem lineItem, HttpHeaders responseHeaders) {
    System.out.printf("Line Item '%s' is now active.\n",
        lineItem.getName());
  }

  public void onFailure (GoogleJsonError error, HttpHeaders responseHeaders)
      throws IOException{
    System.out.printf("Error activating line item: %s\n", error.getMessage());
  }
};

LineItem activatedLineItem = new LineItem().setEntityStatus("ENTITY_STATUS_ACTIVE");

for (Long lineItemId: lineItemIds) {
  service.advertisers().lineItems().patch(advertiserId, lineItemId, activatedLineItem)
      .setUpdateMask("entityStatus").queue(batch, callback);
}
batch.execute();

Python

advertiser_id = advertiser-id
line_item_ids = [line-item-id-1, line-item-id-2]

def callback(request_id, response, exception):
    if exception is not None:
        print('Error activating line item "%s": %s' %
              request_id, exception)
    else:
        print('Line item "%s" is now active.' %
              response.get('name'))

batch = service.new_batch_http_request(callback=callback)

line_item_obj = {
    'entityStatus': 'ENTITY_STATUS_ACTIVE'
}

for line_item_id in line_item_ids:
    request = service.advertisers().lineItems().patch(
        advertiserId=advertiser_id,
        lineItemId=line_item_id,
        updateMask="entityStatus",
        body=line_item_obj
    )
    batch.add(request, request_id=line_item_id)

batch.execute()

PHP

$advertiserId = advertiser-id;
$lineItemIds = array(line-item-id-1, line-item-id-2);

// Enable batching on client and create current batch
$service->getClient()->setUseBatch(true);
$batch = $service->createBatch();

// Create line item with updated fields
$updatedLineItem = new Google_Service_DisplayVideo_LineItem();
$updatedLineItem->setEntityStatus('ENTITY_STATUS_ACTIVE');

// Create request parameter array with update mask
$optParams = array('updateMask' => 'entityStatus');

// Add each patch request to the batch
foreach($lineItemIds as $lineItemId) {
    $request = $this->service->advertisers_lineItems->patch(
        $advertiserId,
        $lineItemId,
        $updatedLineItem,
        $optParams
    );
    $requestId = $lineItemId;
    $batch->add($request, $requestId);
}

// Execute batch request
$results = $batch->execute();

// Iterate through results
foreach($results as $responseId => $lineItem) {
    $lineItemId = substr($responseId, strlen('response-') + 1);
    if ($lineItem instanceof Google_Service_Exception) {
        $e = $lineItem;
        printf(
            "Error activating line item '%s': %s\n",
            $lineItemId,
            $e->getMessage()
        );
    } else {
        printf("Line item '%s' is now active.\n", $lineItem->getName());
    }
}
$service->getClient()->setUseBatch(false);