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

"مينهاز كازي"، مسؤول علاقات المطوّرين، "إحصاءات Google" – شباط (فبراير) 2023

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

فهم نظام الحصص لواجهة برمجة التطبيقات لبيانات Google Analytics

نظرًا لاستخدام Google Analytics من قبل الملايين من المطورين والمستخدمين، تتوفر حصة على واجهة برمجة التطبيقات أن الطلبات تحمي النظام من معالجة بيانات أكثر مما يمكنه التعامل معها بما يضمن التوزيع العادل لموارد النظام. واجهة برمجة تطبيقات البيانات في Google تستخدِم مواقع "إحصاءات Google 4" نظامًا لحِزم الرموز المميّزة لإدارة حصص واجهة برمجة التطبيقات. إلى فهم المفهوم: تخيل أن هناك مجموعة بيانات يمكن أن تحمل الحد الأقصى عدد الرموز المميزة. سيتحقّق أيّ طلب من واجهة برمجة التطبيقات من الحزمة أولاً. إذا لم تكن هناك رموز مميزة متبقية، سيفشل الطلب. وبخلاف ذلك، سيتم تنفيذ الطلب واحدة أو أكثر من الرموز من الحزمة بناءً على درجة تعقيد الطلب. يتم تجديد الرموز المميّزة في الحزمة إلى الحد الأقصى عند القيمة الثابتة الفواصل الزمنية.

بناءً على طريقة Data API التي تستخدمها، هناك ثلاث حصص منفصلة الفئات:

  • الوقت الفعلي (لـ runRealtimeReport)
  • مسار الإحالة الناجحة (لـ runFunnelReport)
  • الأساسية (لجميع الطرق الأخرى)

وستتحقق طرق Data API من مجموعات بيانات متعددة الرموز المميّزة للحصة:

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

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

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

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

يتم تجديد كل الرموز المميّزة للحصة إلى الحدّ المسموح به على فترات زمنية محدّدة. ارجع إلى حصص البيانات في Google Analytics Data API للحصول على معلومات الحصص المحدَّثة. على سبيل المثال: تحصل الطرق الأساسية على 1,250 رمز مميّز للحصة في لكل مشروع لكل موقع في الساعة دُلو. لنفترض أن متوسط الطلب من تطبيقك يستهلك 10 حصص. فإن تطبيقك سيتمكن من تقديم 125 طلبًا أساسيًا في الساعة موقع عادي و10 أضعاف هذا المبلغ (1250 طلبًا أساسي) لأي إحصاءات Google موقع "إحصاءات 360". يعد الحد الأعلى للحصة المميزة هو أحد الأسباب الرئيسية ومزايا مواقع "إحصاءات 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، يمكنك توقّع مقدار الحصة التي يستهلكها الطلب ومقدار الحصة المتبقية للموقع. من المهم من الممكن أيضًا إظهار هذه المعلومات للمستخدم عبر تطبيقك من واجهة pyplot.

إدارة الحصص

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

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

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

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

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

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

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

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

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

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