إدارة الحصة لواجهة برمجة التطبيقات Google Analytics Data API

منهاج قاضي، مسؤول علاقات المطوّرين، إحصاءات 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 من عدة حِزم من أجل [الرموز المميّزة للحصة][Google Analytics Data API Quotas]:

1. لكلّ موقع في اليوم
2. لكل موقع في الساعة
3. لكل مشروع ولكل موقع ولكل ساعة
4. الطلبات المتزامنة لكل موقع
5. أخطاء الخادم لكل مشروع لكل موقع كل ساعة

يتم التحقّق من هذه المجموعات الخمس في كل مرة يصل فيها طلب إلى Data API بشأن موقع. إذا كان أيّ من الحِزم فارغًا، سيتعذّر تنفيذ الطلب على الفور وسيظهر الخطأ 429. إذا لم تكن أي من الحِزم فارغة، سيتم استهلاك رمز مميّز واحد من حزمة الطلبات المتزامنة لكل موقع، ثم سيتم تنفيذ طلب البيانات من واجهة برمجة التطبيقات. استنادًا إلى مدى تعقيد الطلب، سيتم استهلاك عدد معيّن من الرموز المميزة من كل من المجموعات الثلاث الأولى بعد اكتمال التنفيذ. سيتم أيضًا تجديد الرمز المميّز للطلبات المتزامنة لكل موقع في هذا الوقت.

يضمن حصة المشروع الواحد لكل موقع لكل ساعة ألا يؤثر استنفاد الحصة لمستخدم واحد أو أكثر في المستخدمين الآخرين لتطبيقك. يشير المشروع هنا إلى مشروع Google Cloud Platform الخاص بتطبيقك. عادةً ما تكون حصة الموقع الواحد في الساعة أربعة أضعاف حصة المشروع الواحد في الموقع الواحد في الساعة. لذلك، يجب أن يتم الوصول إلى الموقع من خلال أربعة مشاريع مختلفة على الأقل قبل استنفاد حصة الموقع الواحد في الساعة. يضمن فرض الحصة على مستوى كل من المشروع والموقع أن تقتصر مشاكل الحصة على موقع واحد ولن تؤثر في المواقع الأخرى التي يصل إليها تطبيقك.

تحذير: ننصح المطوّرين بشدة بعدم تقسيم الرموز المميزة للحصة على عدة مشاريع لواجهة برمجة التطبيقات. ويشكّل ذلك مخالفة لبنود خدمة Google APIs.

تشير حصة أخطاء الخادم إلى استجابات واجهة برمجة التطبيقات التي تتضمّن الرمزين 500 أو 503. إذا كان تطبيقك يُنشئ عددًا كبيرًا جدًا من الأخطاء أثناء الوصول إلى موقع، سيؤدي ذلك إلى استنفاد حصة أخطاء الخادم لكل مشروع ولكل موقع في الساعة.

يتم تجديد جميع رموز الحصص إلى الحدّ الأقصى على فترات زمنية محدّدة. راجِع [حصص Google Analytics Data API] للحصول على معلومات محدّثة عن الحصص. على سبيل المثال، تحصل طرق Core على 1,250 رمزًا مميزًا للحصة في حزمة لكل مشروع ولكل موقع كل ساعة. بافتراض أنّ الطلب العادي من تطبيقك يستهلك 10 رموز مميّزة من الحصة، سيتمكّن تطبيقك من إجراء 125 طلبًا من Core في الساعة للموقع العادي، و10 أضعاف هذا المبلغ (1250 طلبًا من Core) لأي موقع على "إحصاءات 360". يُعدّ الحدّ الأعلى المسموح به للرموز المميّزة من المزايا الرئيسية لمواقع "إحصاءات Google‏ 360".

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

• طلب المزيد من السمات
• طلب نطاق زمني أعلى
• تضمين السمات التي تتضمّن عددًا أكبر من القيم
• طلب البحث في موقع يحتوي على عدد أكبر من الأحداث

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

ملاحظة: إذا كنت قد استخدمت Reporting API في Universal Analytics من قبل، ستلاحظ أنّ Reporting API فرضت الحصة على مستوى التطبيق/مشروع واجهة برمجة التطبيقات. أمّا بالنسبة إلى Data API، فيتم تطبيق الحصة على مستوى الموقع على "إحصاءات Google" وعلى مستوى مشروع واجهة برمجة التطبيقات.

مراقبة استخدام الحصة

لمراقبة استخدام الحصة المخصّصة ونقل هذه المعلومات إلى المستخدم النهائي، يمكنك إضافة "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، عليك تنفيذ طلب بيانات من واجهة برمجة التطبيقات بنجاح لاسترداد العنصر PropertyQuota. إذا استنفدت السمة سعة حزمة الرموز المميزة للحصة، سيتعذّر تنفيذ طلبك وسيظهر الخطأ 429، ولن يتضمّن الردّ العنصر PropertyQuota. إذا كنت متأثرًا بذلك وتعتقد أنّ تطبيقك سيستفيد من توفير طريقة منفصلة للوصول إلى معلومات الحصة، يُرجى النقر على +1 في طلب الميزة هذا في أداة تتبُّع المشاكل.

إدارة الحصص

ننصحك بتنفيذ أفضل الممارسات المتعلّقة بإدارة الحصص والموضّحة أدناه للاستفادة إلى أقصى حدّ من Data API. يمكن أيضًا أن تؤدي ترقية مواقعك إلى الإصدار 360 إلى زيادة كمية البيانات التي يمكن الوصول إليها من خلال واجهة برمجة التطبيقات.

أفضل الممارسات

هناك طريقتان بشكل عام لتقليل استخدام الحصة المخصّصة لتطبيقك:

• إرسال عدد أقل من طلبات بيانات من واجهة برمجة التطبيقات
• إرسال طلبات أقل تعقيدًا إلى واجهة برمجة التطبيقات

مع وضع هذين المبدأين في الاعتبار، إليك الممارسات التي يمكنك تنفيذها:

• التخزين المؤقت: سيؤدي تنفيذ طبقة تخزين مؤقت إلى تحسين قابلية الاستخدام وإدارة الحصة لتطبيقك. ستخزّن "إحصاءات Google" طلبات البيانات من واجهة برمجة التطبيقات مؤقتًا، ولكنّ الطلبات المتكرّرة ستؤدّي إلى استهلاك الرموز المميّزة للحصص. من خلال تخزين ردّ من واجهة برمجة التطبيقات مؤقتًا، يمكنك تقليل عدد الطلبات المتكرّرة بشكل كبير. على سبيل المثال، يمكن أن يكون وقت انتهاء صلاحية ذاكرة التخزين المؤقت للبيانات خلال اليوم في المواقع العادية 4 ساعات أو أكثر. اطّلِع على مقالة سرعة توفُّر البيانات في "إحصاءات Google".
• دمج الطلبات: حاوِل دمج عدة طلبات من واجهة برمجة التطبيقات في طلب واحد. على سبيل المثال، يمكن أن يؤدي تقديم 5 طلبات للحصول على بيانات خلال إطار زمني مدته يومان إلى استخدام 3 أضعاف رموز الحصة مقارنةً بطلب واحد لإطار زمني مدته 10 أيام. إذا كانت لديك طلبات متعدّدة تختلف في سمة واحدة فقط، ننصحك بدمجها في طلب واحد.
• تبسيط الطلبات: يجب أن تقتصر طلباتك على الحدّ الأدنى من البيانات التي يتطلّبها تطبيقك والمستخدم. سيؤدي العدد الكبير من الصفوف أو الأعمدة أو معايير الفلترة المعقّدة إلى استهلاك المزيد من رموز الحصة. عادةً ما تكون النطاقات الزمنية الأطول أكثر تكلفةً (على سبيل المثال، يمكن أن يؤدي تغيير النطاق الزمني من 28 يومًا إلى 365 يومًا إلى استهلاك 3 أضعاف رموز الحصة). يمكنك أيضًا استخدام سمات ذات عدد أقل من القيم الممكنة كلما أمكن ذلك (مثل طلب dateHour بدلاً من dateHourMinute).
• الاستخدام الفعّال لـ limit: لا يؤثّر تغيير limit في طلب البيانات من واجهة برمجة التطبيقات بشكل كبير في الرموز المميّزة المستخدَمة ضمن الحصة، وذلك بهدف تقليل عدد الصفوف التي يتم عرضها. على سبيل المثال، يمكن أن تستهلك 5 طلبات بحدود 10 آلاف صف خمسة أضعاف رموز الحصة مقارنةً بطلب واحد بحد 50 ألف صف.
• استخدام فئة الطريقة الصحيحة: كما ذكرنا أعلاه، يتم توزيع حدود الحصة على ثلاث فئات من الطرق. يمكن أن يساعدك استخدام الطريقة المناسبة لحالة الاستخدام المناسبة في توفير الحصة المخصّصة لفئات أخرى. على سبيل المثال، بدلاً من إنشاء مسار إحالة ناجحة خاص بك في تطبيقك باستخدام بيانات من طرق Core، استخدِم طريقة runFunnelReport لإنشاء مسارات الإحالة الناجحة.
• تعديل الإعدادات التلقائية: عند إنشاء التقارير أو تخصيصها على منصتك، قد لا يعدّل المستخدمون الخيارات التلقائية التي يعرضها تطبيقك، بل يغيّرونها فقط أثناء وقت التشغيل. على سبيل المثال، إذا كان تطبيقك يتضمّن نطاقًا زمنيًا تلقائيًا يبلغ 365 يومًا وكان المستخدِم يطّلع عادةً على تقرير لمدة 28 يومًا، سيؤدي ذلك إلى استهلاك حصة أكبر من الحصة المطلوبة بشكل منتظم. ننصحك بالحدّ من النطاقات والاختيارات في الإعدادات التلقائية والسماح للمستخدمين باختيار الإعدادات المثالية لحالات الاستخدام. أو في بعض الحالات، يمكنك أيضًا حصر الإعدادات التلقائية التي يمكن للمستخدمين تغييرها.
• وضع الطلبات في قائمة الانتظار والتحميل الكسول: يجب الانتباه إلى الحدّ الأقصى لعدد الرموز المميزة للطلبات المتزامنة لكل موقع. يجب ألا يرسل تطبيقك عددًا كبيرًا جدًا من الطلبات في الوقت نفسه. إذا كان تطبيقك يحتوي على عدد كبير من عناصر واجهة المستخدم التي تؤدي إلى عدد كبير من طلبات البيانات من واجهة برمجة التطبيقات، ننصحك بتقسيم واجهة المستخدم إلى صفحات، واستخدام التحميل الكسول، ووضع الطلبات في قائمة انتظار مع التراجع الأسي لإعادة المحاولة. استخدِم طريقة returnPropertyQuota لمراقبة استخدام الرمز المميّز لطلبات المتزامنة لكل موقع في تطبيقك بشكل مكثّف.

إدارة تجربة المستخدم وتوقعاته

• تقديم ملاحظات للمستخدمين قبل تنفيذ طلبات بحث قد تؤدي إلى استخدام عدد كبير من الرموز المميزة على سبيل المثال، يمكن أن تستخدم الطلبات التي تتضمّن سمات متعدّدة ذات عدد كبير من القيم أو إطارًا زمنيًا كبيرًا عددًا كبيرًا من الرموز المميّزة. يمكن أن يؤدي تقديم تحذير وطلب تأكيد لهذه الطلبات إلى منع المستخدمين من إجراء تغييرات غير ضرورية على التقارير ومساعدتهم في حصر نطاق طلبات البحث.
• بالنسبة إلى حلول إعداد التقارير المخصّصة، يجب توفير طريقة تتيح للمستخدمين فهم استخدام طلبات البحث لكل عنصر في تقريرهم. على سبيل المثال، يمكنك تقديم عرض تصحيح الأخطاء يعرض استخدام الرمز المميز للحصة لكل عنصر من عناصر التقرير.
• تقديم ملاحظات حول نوع خطأ الحصة المحدّدة ووصف الإجراء الذي يجب أن يتخذه المستخدم
• بما أنّ مواقع "إحصاءات Google‏ 360" تحصل على حدّ حصة أكبر من 5 إلى 10 مرّات مقارنةً بالمواقع العادية، ستحصل على مرونة أكبر من خلال مواقع "إحصاءات Google‏ 360".

لا تتوفّر زيادات في حصص واجهة Data API تتجاوز الحدود التلقائية لواجهة Data API في "إحصاءات Google‏ 4". توفّر "إحصاءات Google‏ 360" حصصًا بحدود أعلى لمواقع "إحصاءات Google‏ 4". إذا كان المستخدمون يتجاوزون حدود الحصة حتى بعد تطبيق أفضل الممارسات، عليهم التفكير في ترقية مواقعهم إلى الإصدار 360. يتوفّر خيار آخر للمستخدمين وهو استخدام عمليات التصدير عبر BigQuery Export في "إحصاءات Google". سيسمح ذلك للمستخدمين بتصدير البيانات على مستوى الحدث إلى BigQuery وإجراء تحليلاتهم الخاصة.

إذا كانت لديك أسئلة أخرى حول حصص Data API، يمكنك الانتقال إلى GA Discord أو طرح سؤالك على Stack Overflow. إذا كانت لديك طلبات محدّدة بشأن ميزات Data API، يمكنك نشرها على أداة تتبُّع المشاكل.