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

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

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

نظرة عامة

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

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

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

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

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

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

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

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

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