مينهاز كازي، مسؤول علاقات المطوّرين، "إحصاءات Google" – شباط (فبراير) 2023
إذا كنت تطوِّر التطبيقات باستخدام Google Analytics Data API، عليك فهم كيفية عمل الحصص والحدود الخاصة بواجهة برمجة التطبيقات. إذا تم تصميم تطبيقك بشكل جيد، فمن غير المرجح أن يصل المستخدمون إلى حدود الحصة. تؤدي أيضًا بعض أفضل الممارسات ذات الصلة إلى طلبات بحث فعالة في واجهة برمجة التطبيقات. يمكن أن يؤدي ذلك إلى تسريع عملية إعداد التقارير ولوحات البيانات في تطبيقك، ما يؤدي إلى توفير تجربة مستخدم مرغوبة بشكل أكبر. تناقش هذه المقالة نظام الحصص وأفضل الممارسات لتنفيذ Google Analytics Data API.
فهم نظام الحصص لواجهة Google Analytics Data API
نظرًا لاستخدام "إحصاءات Google" من قِبل الملايين من المطوّرين والمستخدمين، فإن الحصة على طلبات واجهة برمجة التطبيقات تحمي النظام من معالجة بيانات أكثر مما يمكنه التعامل معها مع ضمان التوزيع العادل لموارد النظام. تستخدِم Data API لمواقع "إحصاءات Google 4" نظام حزمة للرموز المميّزة لإدارة حصص واجهة برمجة التطبيقات. لفهم المفهوم: تخيل أن هناك حزمة يمكنها استيعاب ما يصل إلى أقصى عدد من الرموز المميزة. سيتحقّق أي طلب من واجهة برمجة التطبيقات أولاً من الحزمة. وإذا لم تتبق أي رموز رموز مميزة، فسيفشل الطلب. بخلاف ذلك، سيتم تنفيذ الطلب وسيستهلك رمزًا مميزًا واحدًا أو أكثر من الحزمة اعتمادًا على مدى تعقيد الطلب. يتم تجديد الرموز المميزة في الحزمة إلى أقصى حد خلال فترات زمنية ثابتة.
اعتمادًا على طريقة Data API التي تستخدمها، هناك ثلاث فئات منفصلة للحصص:
- في الوقت الفعلي (للنطاق
runRealtimeReport) - مسار الإحالة الناجحة (للنطاق
runFunnelReport) - الأساسية (لجميع الطرق الأخرى)
وستتحقق طرق Data API من عدة مجموعات بيانات لرموز الحصص:
- لكل موقع في اليوم
- لكل موقع في الساعة
- لكل مشروع لكل موقع في الساعة
- الطلبات المتزامنة لكل موقع
- أخطاء الخادم لكل مشروع لكل موقع إلكتروني في الساعة
ويتم التحقّق من هذه المجموعات الخمس في أي وقت يأتي فيه طلب Data API لأحد المواقع. إذا كانت أي من الحِزم فارغة، سيتعذّر إتمام الطلب فورًا وسيظهر الخطأ 429. وإذا لم تكن أي من الحِزم فارغة، سيتم استهلاك رمز مميّز واحد من حزمة الطلبات المتزامنة لكل موقع وبعد ذلك سيتم تنفيذ طلب البيانات من واجهة برمجة التطبيقات. وبناءً على مدى تعقيد الطلب، سيتم استهلاك كمية معيّنة من الرموز المميّزة من كل مجموعة من المجموعات الثلاث الأولى بعد اكتمال التنفيذ. بالإضافة إلى ذلك، سيحصل الطلبات المتزامنة لكل موقع على رمز مميّز يتم تجديده في هذا الوقت.
تضمن الحصة لكل مشروع لكل موقع في الساعة أن استنفاد الحصة لمستخدم واحد أو أكثر لن يؤثر في المستخدمين الآخرين لتطبيقك. يشير مصطلح project هنا إلى مشروع Google Cloud Platform لتطبيقك. تكون الحصة لكل موقع في الساعة عادةً أربعة أضعاف الحصة لكل مشروع لكل موقع في الساعة. لذلك بالنسبة إلى المستخدمين النهائيين، يجب الوصول إلى الموقع من خلال أربعة مشاريع مختلفة على الأقل قبل استنفاد الحصة لكل موقع في الساعة. إنّ فرض الحصة على مستوى كلّ من المشروع والموقع يضمن أن تقتصر مشاكل الحصص على موقع واحد، ولا تؤثّر في المواقع الأخرى التي يصل تطبيقك إليها.
تشير حصة أخطاء الخادم إلى استجابات واجهة برمجة التطبيقات التي تتضمّن رمز 500 أو رمز 503. إذا كان تطبيقك ينشأ عددًا كبيرًا جدًا من الأخطاء أثناء الدخول إلى أحد المواقع، سيؤدي ذلك إلى استنفاد حصة أخطاء الخادم لكل مشروع لكل موقع في الساعة.
يتم تجديد جميع الرموز المميّزة للحصص بالحدّ الأقصى على الفترات الزمنية المذكورة. يُرجى الرجوع إلى حصص واجهة برمجة التطبيقات للبيانات في "إحصاءات Google" للاطّلاع على معلومات الحصص المحدَّثة. على سبيل المثال، تحصل طرق الأساسية على 1,250 رمزًا مميزًا للحصة في مجموعة البيانات لكل مشروع لكل موقع في الساعة. على افتراض أنّ متوسط الطلب الوارد من تطبيقك يستهلك 10 رموزًا مميّزة للحصص، سيتمكن تطبيقك من تقديم 125 طلبًا أساسيًا في الساعة لموقع عادي و10 أضعاف هذا العدد (1250 طلبًا أساسيًا) لأي موقع على "إحصاءات 360". يُعد الحدّ الأقصى المسموح به لعدد الرموز المميّزة للحصة أحد المزايا الرئيسية لمواقع "إحصاءات Google 360".
وبما أنّ استهلاك الرمز المميّز للحِزم الثلاث الأولى يعتمد على مدى تعقيد الطلب، يصعب التنبؤ باستخدام الرمز المميّز بدقة قبل تنفيذ الطلب. يؤدي ما يلي عادةً إلى زيادة مدى تعقيد الطلب، ما يؤدي إلى استخدام الرمز المميّز:
- جارٍ طلب المزيد من السمات
- الاستعلام عن نطاق زمني أعلى
- بما في ذلك السمات التي تتضمّن عددًا أكبر من القيم الفريدة للسمة
- طلب البحث عن موقع يتضمّن عدد أحداث أعلى
وبالتالي، قد يؤدي طلب البحث نفسه لموقعَين مختلفَين إلى استخدام رمز مميّز مختلف تمامًا لأنّ عدد القيم الفريدة للسمات قد يختلف أو يختلف عدد الزيارات. مع ذلك، يمكنك أن تتوقّع أن تستخدم المواقع التي لها مستويات مماثلة من عدد الزيارات وإعدادات مشابهة للرموز المميّزة نفسها. يمكنك استخدام هذا الافتراض للتنبؤ باستخدام الرمز المميز للعميل أثناء مراحل التخطيط وتصميم التطبيق.
رصد استخدام الحصة
لمراقبة استخدام الحصة ونقل هذه المعلومات إلى المستخدم النهائي، يمكنك إضافة
"returnPropertyQuota": true إلى نص طلب واجهة برمجة التطبيقات. سيؤدي ذلك إلى عرض العنصر PropertyQuota مع استجابة واجهة برمجة التطبيقات. سيحتوي العنصر PropertyQuota على مبالغ الاستهلاك وحالة الحصة المتبقية لكلّ مجموعات البيانات الخمس. في ما يلي مثال على نص الطلب والاستجابة له:
الطلب
{
"dimensions": [
{
"name": "medium"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "yesterday"
}
],
"returnPropertyQuota": true
}
الرد
{
"dimensionHeaders": [
{
"name": "medium"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
...
"propertyQuota": {
"tokensPerDay": {
"consumed": 1,
"remaining": 24997
},
"tokensPerHour": {
"consumed": 1,
"remaining": 4997
},
"concurrentRequests": {
"consumed": 0,
"remaining": 10
},
"serverErrorsPerProjectPerHour": {
"consumed": 0,
"remaining": 10
},
"potentiallyThresholdedRequestsPerHour": {
"consumed": 0,
"remaining": 120
},
"tokensPerProjectPerHour": {
"consumed": 1,
"remaining": 1247
}
},
"kind": "analyticsData#runReport",
...
}
وبالتالي، بعد كل طلب ناجح من خلال Data API، يمكنك توقّع معرفة مقدار الحصّة التي تم استهلاكها ومقدار الحصة المتبقية للموقع. من الممكن أيضًا عرض هذه المعلومات للمستخدم عبر واجهة التطبيق.
إدارة الحصص
ننصحك بتنفيذ أفضل الممارسات المتعلّقة بإدارة الحصص والمفصّلة أدناه للاستفادة إلى أقصى حد من Data API. ويمكن أيضًا أن تؤدي ترقية مواقعك إلى الإصدار 360 إلى زيادة كمية البيانات التي يتم الوصول إليها من خلال واجهة برمجة التطبيقات.
أفضل الممارسات
هناك طريقتان على نطاق واسع لتقليل استخدام الحصة لتطبيقك:
- إرسال عدد أقل من طلبات البيانات من واجهة برمجة التطبيقات
- إرسال طلبات أقل تعقيدًا من واجهة برمجة التطبيقات
مع أخذ هذين المبدأين في الاعتبار، إليك الممارسات التي يمكنك تنفيذها:
- التخزين المؤقت: سيستفيد تنفيذ طبقة تخزين مؤقت من قابلية الاستخدام وإدارة الحصص لتطبيقك. ستعمل خدمة "إحصاءات Google" نفسها على تخزين طلبات واجهة برمجة التطبيقات مؤقتًا ولكن ستظل الطلبات المتكررة تخضع للحصة. ومن خلال التخزين المؤقت لاستجابة واجهة برمجة التطبيقات، يمكنك تقليل عدد الطلبات المتكرّرة إلى حد كبير. على سبيل المثال، يمكن أن تستغرق بيانات اليوم الواحد للمواقع العادية 4 ساعات أو وقت انتهاء صلاحية ذاكرة التخزين المؤقت. اطّلع على حداثة البيانات في "إحصاءات Google".
- دمج الطلبات: حاوِل دمج عدة طلبات من واجهة برمجة التطبيقات في طلب واحد. على سبيل المثال، يمكن استخدام 3 أضع��ف الرموز المميّزة للحصة في 5 طلبات بيانات خلال فترة زمنية تبلغ يومين مقارنةً بطلب واحد خلال إطار زمني مدته 10 أيام. إذا كانت لديك طلبات متعددة تختلف حسب بُعد واحد فقط، حاوِل دمجها في طلب واحد.
- تبسيط الطلبات: احرص على أن تقتصر طلباتك على الحد الأدنى من كمية البيانات التي يتطلبها التطبيق والمستخدم. سيؤدي العدد الكبير من الصفوف/الأعمدة أو معايير
التصفية المعقدة إلى استهلاك المزيد من رموز الحصة. عادةً ما تكون النطاقات الزمنية الأطول أكثر تكلفة (على سبيل المثال، قد يؤدي تغيير النطاق الزمني من 28 يومًا إلى 365 يومًا إلى استهلاك 3 أضعاف الرموز المميّزة للحصة). يمكنك أيضًا استخدام سمات تتضمّن عددًا أقل من القيم كلما أمكن ذلك (مثل طلب
dateHourبدلاً منdateHourMinute). - الاستخدام الفعّال لـ
limit: لا يؤثر تغييرlimitفي طلب واجهة برمجة التطبيقات لتقليل عدد الصفوف المعروضة بشكل كبير في رموز الحصص التي يتم استهلاكها. على سبيل المثال، إذا كان الحدّ الأقصى المسموح به لعدد الصفوف هو 10 آلاف صف، يمكن أن يستهلك هذا البرنامج خمسة أضعاف الرموز المميّزة للحصة مقارنةً بطلب واحد يتضمّن الحد الأقصى المسموح به لعدد الصفوف. - استخدام فئة الطريقة الصحيحة: كما هو موضّح أعلاه، تنتشر حدود الحصة على ثلاث فئات للطرق. يمكن أن يؤدي استخدام الطريقة الصحيحة لحالة
الاستخدام الصحيحة إلى توفير الحصة في الفئات الأخرى. على سبيل المثال، بدلاً من إنشاء مسار إحالة ناجحة خاص بك في تطبيقك باستخدام البيانات من الطرق الأساسية، استخدِم طريقة
runFunnelReportلإنشاء مسارات الإحالات الناجحة. - تعديل الإعدادات التلقائية: عند كتابة التقارير أو تخصيصها على منصتك، قد لا يعدِّل المستخدمون الخيارات التلقائية التي يقدّمها تطبيقك ويغيّرونها فقط في وقت التشغيل. إذا كان لتطبيقك النطاق الزمني التلقائي وهو 365 يومًا وكان المستخدم يطّلع عادةً على تقرير 28 يومًا، سيؤدي ذلك إلى استهلاك حصة أكبر مما هو مطلوب بشكل منتظم. ننصحك بتقييد النطاقات والخيارات في الإعدادات التلقائية والسماح للمستخدمين باختيار الإعدادات الأفضل لحالات الاستخدام لديهم. أو في بعض الحالات، يمكنك أيضًا تحديد الإعدادات الافتراضية التي يمكن للمستخدمين تغييرها.
- إضافة الطلبات إلى قائمة المحتوى التالي والتحميل الكسول: ضَع في اعتبارك حدّ الرموز المميّزة للطلبات المتزامنة لكل موقع. يجب ألا يرسل تطبيقك عددًا كبيرًا جدًا من الطلبات في وقت واحد إذا كان تطبيقك يحتوي على عدد كبير من عناصر واجهة المستخدم التي تؤدي إلى عدد كبير من طلبات واجهة برمجة التطبيقات، ننصحك بتقسيم واجهة المستخدم إلى صفحات، والتحميل الكسول، والإضافة إلى قائمة الطلبات باستخدام خوارزمية الرقود الأسي في إعادة المحاولة. استخدم طريقة
returnPropertyQuotaلمراقبة استخدام الرمز المميز للطلبات المتزامنة لكل موقع في تطبيقك بشكل دقيق.
إدارة تجربة المستخدم وتوقعاته
- يمكنك تقديم ملاحظات للمستخدمين قبل تنفيذ طلبات البحث التي يُحتمَل أن تستخدم رموزًا مميزة بشكل كبير. على سبيل المثال، إنّ طلبات البحث ذات السمات المتعددة التي تتضمّن عددًا كبيرًا من القيم أو التي لها إطار زمني كبير يمكنها استخدام عدد كبير من الرموز المميّزة. إنّ عرض تحذير ومطالبة تأكيدية لطلبات البحث هذه قد يمنع المستخدمين من إجراء تغييرات غير ضرورية على التقارير، ويساعدهم في حصر نطاق طلبات البحث هذه في نطاق طلباتهم.
- بالنسبة إلى حلول إعداد التقارير المخصّصة، وفِّر طريقة للمستخدمين لفهم استخدام طلب البحث لكل عنصر في تقريرهم. على سبيل المثال، يمكنك توفير عرض تصحيح أخطاء يسرد استخدام الرمز المميّز للحصة لكل عنصر في التقرير.
- قدم ملاحظات حول النوع المحدد من خطأ الحصة ووصف إجراء المستخدم.
- بما أنّ مواقع "إحصاءات Google 360" تحصل على حدّ أقصى للحصة من 5 إلى 10 أضعاف مقارنةً بالمواقع العادية، يمكنك الاستفادة من مرونة أكبر باستخدام مواقع "إحصاءات Google 360".
لا تتوفّر زيادة حصص واجهة برمجة التطبيقات التي تتجاوز الحدود التلقائية في Data API لخدمة "إحصاءات Google 4". يوفّر "إحصاءات Google 360" حصصًا أعلى لمواقع "إحصاءات Google 4". إذا كان المستخدمون يبلغون حدود الحصة المسموح بها حتى بعد تنفيذ أفضل الممارسات، عليهم التفكير في ترقية مواقعهم إلى الإصدار 360. يتوفّر خيار آخر للمستخدمين وهو استخدام أداة BigQuery Export في "إحصاءات Google". سيسمح ذلك للمستخدمين بتصدير البيانات على مستوى الحدث إلى BigQuery وإجراء تحليلهم الخاص.
إذا كانت لديك أسئلة إضافية حول حصص واجهة برمجة التطبيقات، يمكنك الانتقال إلى موقع GA Discord أو طرحه على الموقع الإلكتروني Stack Overflow. إذا كانت لديك طلبات ميزات محددة بشأن Data API، يمكنك نشرها على أداة تتبّع المشاكل.