إرسال طلبات مجمّعة

تم إيقاف نهج محدّد نهائيًا للتجميع، وهو "نقطة نهاية HTTP الشاملة" (www.googleapis.com/batch)، في 12 آب (أغسطس) 2020، كما أعلنّا في مدوّنة Google Developers. ما زالت هناك طرق أخرى للتجميع تعمل، كما هو موثّق في بقية هذه الصفحة. إذا كان الرمز يستخدم نقطة نهاية HTTP مجمّعة شاملة، يمكنك الاطّلاع على مشاركة المدونة للحصول على تعليمات حول الانتقال إلى استخدام طرق أخرى، مثل نقاط نهاية HTTP المجمّعة لواجهة برمجة التطبيقات (www.googleapis.com/batch/API/VERSION).

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

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

نظرة عامة

ينتج عن كل اتصال HTTP يؤديه العميل تكاليف معيّنة. تتيح واجهة برمجة التطبيقات لتقرير تجارب إعلانات Google التجميع، للسماح لعميلك بوضع العديد من طلبات البيانات من واجهة برمجة التطبيقات في طلب HTTP واحد.

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

• لقد بدأت للتو استخدام واجهة برمجة التطبيقات ولديك عدد كبير من البيانات لتحميلها.
• أجرى مستخدم تغييرات على البيانات أثناء عدم اتصال تطبيقك بالإنترنت (بدون اتصال بالإنترنت)، لذا يحتاج تطبيقك إلى مزامنة بياناته المحلية مع الخادم من خلال إرسال الكثير من التحديثات والحذف.

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

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

ملاحظة: يستخدم النظام المجمّع لواجهة برمجة التطبيقات لتقرير تجارب إعلانات Google البنية نفسها التي يعمل بها نظام المعالجة المجمّعة لبيانات البيانات، إلا أن الدلالة تختلف.

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

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

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

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

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

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

يشكّل نص كل جزء بحد ذاته طلب HTTP كاملاً، مع ما يخصه من فعل وعنوان URL ورؤوس ونص. يجب أن يحتوي طلب HTTP فقط على جزء المسار من عنوان URL، ولا يُسمح بعناوين URL الكاملة في الطلبات المجمّعة.

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

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

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

الاستجابة لطلب مجمّع

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

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

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

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

مثال

يوضّح المثال التالي استخدام التجميع مع واجهة برمجة التطبيقات لتقرير تجارب إعلانات Google.

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

  POST /batch/v1?key=key HTTP/1.1
  Content-Type: multipart/mixed; boundary=batch_aer

  --batch_aer
  Content-Type: application/http
  Content-ID: id1

  GET /v1/sites/http%3A%2F%2F/site1%2F HTTP/1.1

  --batch_aer
  Content-Type: application/http
  Content-ID: id2

  GET /v1/sites/http%3A%2F%2F/site2%2F HTTP/1.1

  --batch_aer--
  

مثال على استجابة مجمّعة

هذا هو الرد على نموذج الطلب في القسم السابق.

  HTTP/1.1 200 OK
  Content-Type: multipart/mixed; boundary=batch_aer

  --batch_aer
  Content-Type: application/http
  Content-ID: response-id1

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "reviewedSite": "site1",
    "mobileSummary": {
      "lastChangeTime": "2019-02-05T09:46:26.521747Z",
      "betterAdsStatus": "PASSING",
      "reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site1/",
      "filterStatus": "OFF"
    },
    "desktopSummary": {
      "lastChangeTime": "2019-02-07T23:07:29.017206Z",
      "betterAdsStatus": "FAILING",
      "enforcementTime": "2018-02-15T15:00:00Z",
      "reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site1/",
      "filterStatus": "ON"
    }
  }

  --batch_aer
  Content-Type: application/http
  Content-ID: response-id2

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "reviewedSite": "site2",
    "mobileSummary": {
      "lastChangeTime": "2018-03-06T16:06:33.375851Z",
      "betterAdsStatus": "PASSING",
      "reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site2/",
      "filterStatus": "OFF"
    },
    "desktopSummary": {
      "lastChangeTime": "2018-03-06T16:06:33.375851Z",
      "betterAdsStatus": "PASSING",
      "reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site2/",
      "filterStatus": "OFF"
    }
  }

  --batch_aer--