تجميع طلبات البيانات من Google Analytics API

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

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

نظرة عامة

ينتج عن كل اتصال HTTP في العميل مقدار معين من النفقات العامة. تدعم واجهة برمجة تطبيقات Google Analytics ميزة التجميع، وذلك للسماح لعميلك بتقديم عدة طلبات بيانات من واجهة برمجة التطبيقات في طلب HTTP واحد.

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

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

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

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

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

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

ملاحظة: يتم احتساب مجموعة من طلبات 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 معيّنًا في كل من الطلب الخارجي والاستدعاء الفردي، ستلغي قيمة عنوان الاستدعاء الفردي قيمة عنوان طلب الدفعة الخارجية. وتنطبق رؤوس المكالمة الفردية على هذه المكالمة فقط.

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

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

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

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

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

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

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

مثال

يوضّح المثال التالي استخدام التجميع باستخدام Google Analytics API.

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

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 Analytics API ضمن الطلب المجمّع ضمن حصة المشروع اليومية. يمكن أن يقدّم المشروع تلقائيًا ما يصل إلى 50,000 طلب في اليوم، مع العلم أنّ تجميع الطلبات لن يساعدك في عدم تجاوز هذه الحصة.

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

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