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

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

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

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

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

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

فئات الحصص

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

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

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

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

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

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

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

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

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

يتم تحديد تكلفة الرموز المميّزة الدقيقة للطلب في وقت التنفيذ، ما يجعل الحساب المسبق الدقيق أمرًا صعبًا. تتأثر التكلفة بمجموعة من العوامل المرتبطة بالطلب نفسه والبيانات الأساسية في موقع على "إحصاءات 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 chat، تمثّل الرموز المميّزة تكاليف الحوسبة والاستدلال واسترداد البيانات الأساسية في النموذج. يتأثر استهلاك الرموز المميّزة في Chat بما يلي:

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

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