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

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

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

نظرة عامة

يؤدي كل اتصال HTTP يجريه العميل إلى حدوث قدر معيّن من الحمل الزائد. تتيح واجهة Google Ad Experience Report API إمكانية تجميع الطلبات، ما يسمح لبرنامجك بوضع عدة طلبات من واجهة برمجة التطبيقات في طلب HTTP واحد.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

عندما يتلقّى الخادم الطلب المجمّع، يطبّق مَعلمات طلب البحث والرؤوس الخاصة بالطلب الخارجي (حسب الاقتضاء) على كل جزء، ثم يتعامل مع كل جزء كما لو كان طلب 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--