تجميع طلبات البيانات من واجهة برمجة التطبيقات في "إحصاءات Google"

تم إيقاف نهج محدّد نهائيًا للتجميع، وهو "نقطة نهاية 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" البنية نفسها التي يستخدِمها نظام المعالجة المجمّعة لبيانات OData، ولكن تختلف الدلالة.

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

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

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

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

الطلب المجمّع هو طلب HTTP عادي واحد يحتوي على عدّة طلبات بيانات من Google Analytics API باستخدام نوع المحتوى 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/analytics/v3 HTTP/1.1
Host: www.googleapis.com
Content-length: 731
Content-type: multipart/mixed; boundary=batch_0123456789
Authorization: Bearer ya29.5gFZooleNoSpGqYOOF0eFciUGz1x26k9GagZoW7HJCogWlCoNOotxlZPo7bDbwo1ykDq
--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 68


{
 "name": "Campaign Group",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 67


{
 "name": "Campaign Type",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789--

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

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

HTTP/1.1 200 OK
Content-length: 1876
X-xss-protection: 1; mode=block
X-content-type-options: nosniff
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Vary: Origin,X-Origin
Server: GSE
Cache-control: private, max-age=0
Date: Wed, 02 Sep 2015 21:36:35 GMT
X-frame-options: SAMEORIGIN
Content-type: multipart/mixed; boundary=batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/L-Y_3uM9BpST8Sea-SJDRQ7N7vE"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 548

{"kind":"analytics#customDimension","id":"ga:dimension18","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Group","index":18,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:34.143Z","updated":"2015-09-02T21:36:34.143Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension18","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/VN-21fLS1T0Qko3pHEB5fi8vYJ8"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 547

{"kind":"analytics#customDimension","id":"ga:dimension19","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Type","index":19,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:35.099Z","updated":"2015-09-02T21:36:35.099Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension19","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q--

مكتبات العملاء

استخدِم أدلة مكتبة العملاء التالية للاطّلاع على كيفية تنفيذ التجميع بلغتك:

التجميع وحصة "إحصاءات Google"

يمكن أن يساهم التجميع في توفير النفقات العامة في إنشاء العديد من طلبات HTTP لكل طلب في "إحصاءات Google" ضمن طلب مجمّع، وسيتم احتساب هذه الطلبات ضمن الحصة اليومية للمشروع. وفقًا للإعدادات التلقائية، يمكن أن يقدّم المشروع ما يصل إلى 50,000 طلب في اليوم، لأنّ التجميع لن يساعدك على البقاء أقل من هذه الحصة.

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

ينطبق 1.5 طلب بحث في الثانية (QPS) لكل رقم تعريف حساب على طلبات الكتابة في واجهة برمجة التطبيقات للإدارة وطلبات الكتابة في واجهة برمجة التطبيقات لإدارة الحسابات. وبالتالي، قد لا يؤدي تجميع طلبات الكتابة هذه إلى تحسين مستوى الأداء.