حدود Data API والحصص

تنطبق الحدود والحصص التالية على Data API.

كيفية تطبيق الحصص

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

• الطلبات التي تمت المصادقة عليها باستخدام بيانات اعتماد OAuth 2.0
• الطلبات التي تمت المصادقة عليها باستخدام مفتاح واجهة برمجة التطبيقات فقط

تُستخدَم مفاتيح واجهة برمجة التطبيقات لربط طلب بمشروع معيّن على Google Cloud لأغراض الحصة والفوترة. سيتم احتساب جميع طلبات بيانات من واجهة برمجة التطبيقات التي يتم إجراؤها باستخدام بيانات الاعتماد أو مفتاح واجهة برمجة التطبيقات من مشروعك ضمن الحصص السارية على مشروعك وموقع على "إحصاءات Google".

فئات الحصص

تتضمّن Data API أربع فئات لحصص الطلبات، وهي: التعريف والوقت الفعلي ومسار الإحالة الناجحة والمحادثة.

تستهلك طلبات بيانات من واجهة برمجة التطبيقات الموجّهة إلى طرق التعريف حصص التعريف. تستهلك طلبات بيانات من واجهة برمجة التطبيقات الموجّهة إلى طرق الوقت الفعلي حصص الوقت الفعلي. تستهلك طلبات بيانات من واجهة برمجة التطبيقات الموجّهة إلى طرق مسار الإحالة الناجحة حصص مسار الإحالة الناجحة. تستهلك طلبات بيانات من واجهة برمجة التطبيقات الموجّهة إلى طرق المحادثة حصص المحادثة. يستهلك كل طلب نوعًا واحدًا فقط من الحصص.

حصص مواقع "إحصاءات Google"

تستهلك جميع الطلبات حصص المواقع.

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

يُسمح للمواقع بـ 120 طلبًا في الساعة قد يتم تطبيق حدود عليها. قد يتم تطبيق حدود على السمات userAgeBracket وuserGender وbrandingInterest وaudienceId وaudienceName. يتم تطبيق الحدود لمنع أي شخص يطّلع على تقرير من استنتاج الخصائص الديمغرافية أو اهتمامات مستخدمين فرديين.

حصة الرموز المميّزة للموقع

يتم استهلاك الرموز المميّزة مع كل طلب يتم إرساله إلى Google Analytics Data API v1. يعتمد عدد الرموز المميّزة التي يتم احتسابها على مدى تعقيد الطلب. في حين أنّ معظم الطلبات ستفرض 10 رموز مميّزة أو أقل، ستستهلك الطلبات الأكثر تعقيدًا (مثل طلبات chat في "Ask Advisor") المزيد من الرموز.

العوامل التي تؤثر في استهلاك الرموز المميّزة

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

• عدد الصفوف: طلب عدد أكبر من الصفوف
• عدد السمات والمقاييس: تضمين عدد أكبر من السمات والمقاييس
• مدى تعقيد الفلتر: استخدام تعبيرات فلتر معقّدة
• طول النطاق الزمني: إجراء طلبات بحث على فترات زمنية أطول
• عدد القيم الفريدة للبيانات: يمكن أن تؤدي السمات التي تتضمّن عددًا كبيرًا من القيم الفريدة (مثل pagePath والسمات المخصّصة) إلى زيادة تكلفة الرموز المميّزة بشكلٍ كبير.
• عدد الأحداث في الموقع: قد تستهلك طلبات البحث في المواقع التي تتضمّن عددًا أكبر من الأحداث رموزًا مميّزة أكثر من طلب البحث نفسه في موقع يتضمّن بيانات أقل.

مراقبة استخدام الرموز المميّزة

إنّ الطريقة الأكثر فعالية لتحديد تكلفة الرموز المميّزة لطلبات بيانات من واجهة برمجة التطبيقات المحدّدة هي تضمين المَعلمة "returnPropertyQuota": true في نص الطلب (المتوفّرة في runReport و batchRunReports و runPivotReport و batchRunPivotReports و runRealtimeReport و runFunnelReport). سيتضمّن ردّ من واجهة برمجة التطبيقات بعد ذلك العنصر PropertyQuota الذي يوضّح الرموز المميّزة التي استهلكها هذا الطلب المحدّد وأرصدة الحصص المتبقية.

مثال على طلب يتضمّن returnPropertyQuota

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [
    { "startDate": "7daysAgo", "endDate": "yesterday" }
  ],
  "dimensions": [
    { "name": "country" }
  ],
  "metrics": [
    { "name": "activeUsers" }
  ],
  "returnPropertyQuota": true
}

مثال على حمولة استجابة propertyQuota

عند ضبط "returnPropertyQuota": true، تتضمّن الاستجابة عنصر propertyQuota يحتوي كل حقل فيه على QuotaStatus مع consumed وremaining عددَين صحيحَين:

{
  "dimensionHeaders": [
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "activeUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "United States" }],
      "metricValues": [{ "value": "4820" }]
    }
  ],
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 199999
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 39999
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 13999
    }
  }
}

يقابل كل حقل في propertyQuota حصة في حصص مواقع "إحصاءات Google". يتم خصم تكلفة الرموز المميّزة لطلب بيانات من واجهة برمجة التطبيقات في الوقت نفسه من tokensPerDay وtokensPerHour وtokensPerProjectPerHour. إذا وصل أيّ من نطاقات الحصص إلى 0 متبقٍّ، ستعرض الطلبات اللاحقة الموجّهة إلى هذا الموقع خطأً هو 429 RESOURCE_EXHAUSTED.

أفضل الممارسات لتجنُّب أخطاء 429 RESOURCE_EXHAUSTED

• مراقبة remaining الأرصدة بشكلٍ ديناميكي: يمكنك فحص propertyQuota.tokensPerProjectPerHour.remaining و propertyQuota.tokensPerHour.remaining في الردود، وتقليل عدد المهام غير العاجلة في الخلفية أو إيقافها مؤقتًا عندما تنخفض الرموز المميّزة المتبقية عن حدّ الأمان.
• طلبات البحث المجمّعة: استخدِم batchRunReports أو batchRunPivotReports لتجميع ما يصل إلى 5 تقارير في طلب HTTP واحد وتقليل النفقات العامة لعمليات تبادل البيانات عبر HTTP (يُرجى العِلم أنّ كل تقرير في مجموعة لا يزال يُحتسب بشكلٍ فردي ضمن حصص الرموز المميّزة وconcurrentRequests).
• تقليل مدى تعقيد طلب البحث وعدد القيم الفريدة للسمة: يمكنك حصر الطلبات في السمات والمقاييس التي تحتاج إليها فقط، وتقصير dateRanges حيثما أمكن، وتجنُّب الجمع بين سمات متعدّدة تتضمّن عددًا كبيرًا من القيم الفريدة (مثل pagePath أو fullPageUrl) في طلبات البحث المتكرّرة.
• التحكّم في تزامن الطلبات: يمكنك وضع الطلبات في قائمة الانتظار أو الحدّ من حجم مجموعة العاملين لكي تبقى الطلبات قيد التنفيذ أقل من الحدّ الأقصى لـ concurrentRequests (10 للمواقع العادية و50 لمواقع "إحصاءات 360").
• تنفيذ خوارزمية الرقود الأسي الثنائي مع حدود لإعادة المحاولة: إذا تعذّر تنفيذ طلب بسبب 429 RESOURCE_EXHAUSTED أو 500 INTERNAL أو 503 UNAVAILABLE، أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي المقتطعة كما هو موضّح في استجابات الأخطاء.

استهلاك الرموز المميّزة للمحادثة ومراقبتها

بالنسبة إلى طلبات chat في "Ask Advisor"، تمثّل الرموز المميّزة تكاليف الحوسبة والاستدلال واسترجاع البيانات الأساسية للنموذج. يتأثر استهلاك الرموز المميّزة للمحادثة بما يلي:

• نطاق طلب البحث والتحليل: مدى تعقيد التحليل المطلوب ونطاقه
• الرموز المميّزة لمدخلات النموذج ومخرجاته: حجم البيانات السياقية التي تتم معالجتها والردّ السردي الذي يتم إنشاؤه
• رموز مميّزة للتفكير: خطوات الاستدلال التي يتطلّبها النموذج لتجميع النتائج.
• وقت استجابة التنفيذ: وقت المعالجة المطلوب لنماذج استكشاف البيانات المتعدّدة الخطوات

لمراقبة استخدام الرموز المميّزة للمحادثة، اضبط "returnPropertyQuota": true في ChatRequest. ستتضمّن الاستجابة العنصر PropertyChatQuota الذي يحتوي على الحقلَين tokensPerDay و tokensPerHour مع الأرصدة المستخدَمة والمتبقية.