دليل المطوّر

يوضّح هذا المستند كيفية استخدام واجهة برمجة التطبيقات لإعداد التقارير في الوقت الفعلي للحصول على بيانات "إحصاءات Google".

مقدمة

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

إذا كنت مبتدئًا في استخدام واجهة برمجة التطبيقات، يُرجى الاطّلاع على نظرة عامة على واجهة برمجة التطبيقات في الوقت الفعلي لإعداد التقارير للاطّلاع على مقدمة عن واجهة برمجة التطبيقات في الوقت الفعلي والبيانات التي توفّرها.

المتطلبات الأساسية

قبل استخدام واجهة برمجة التطبيقات لإعداد التقارير في الوقت الفعلي للحصول على بيانات "إحصاءات Google":

  • اطّلِع على صفحة مكتبات العملاء للحصول على قائمة كاملة بمكتبات العملاء الخاصة بلغة البرمجة التي تعمل مع واجهة برمجة التطبيقات.
  • اقرأ الدليل المرجعي لمعرفة كيفية استخدام واجهة برمجة التطبيقات بمفردها (بدون استخدام مكتبة البرامج) للحصول على بيانات "إحصاءات Google".

توفِّر كل مكتبة عملاء عنصرًا واحدًا لخدمة الإحصاءات للوصول إلى جميع بيانات واجهة برمجة التطبيقات لإعداد التقارير في الوقت الفعلي. لإنشاء عنصر خدمة، اتّبِع الخطوات التالية:

  1. سجِّل تطبيقك في وحدة التحكم في واجهة Google API.
  2. السماح بالوصول إلى بيانات "إحصاءات Google"
  3. أنشئ عنصر خدمة على "إحصاءات Google".

إذا لم تكن قد أكملت هذه الخطوات، يُرجى التوقف وقراءة الدليل التعليمي لواجهة برمجة تطبيقات "إحصاءات Google" الذي يرشدك عبر الخطوات الأولية لإنشاء تطبيق واجهة برمجة تطبيقات "إحصاءات Google". بعد ذلك، ستعرف كيفية استخدام واجهة برمجة التطبيقات للحصول على بيانات "إحصاءات Google".

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

لاستخدام واجهة برمجة التطبيقات لإعداد التقارير في الوقت الفعلي، يجب أن يستوفي التطبيق ما يلي:

  1. طلبات البحث في واجهة برمجة التطبيقات لإعداد التقارير في الوقت الفعلي
  2. معالجة استجابة واجهة برمجة التطبيقات

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

يوفّر عنصر خدمة الإحصاءات طريقة لإنشاء طلب بحث في الوقت الفعلي من خلال واجهة برمجة التطبيقات لإعداد التقارير في الوقت الفعلي. للاطّلاع على تفاصيل حول معلَمات طلب البحث والبيانات المتاحة لواجهة برمجة التطبيقات، يُرجى الاطّلاع على ما يلي:

بعد تحديد طلب بحث، يمكنك استدعاء طريقة execute لإرسال الطلب إلى خوادم "إحصاءات Google".

معالجة استجابة واجهة برمجة التطبيقات

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

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

أمثلة على الرموز البرمجية

يوفّر قسم أمثلة في صفحة البيانات في الوقت الفعلي: get رمز نموذجي بلغات برمجة مختلفة لطلب البحث في واجهة برمجة التطبيقات لإعداد التقارير في الوقت الفعلي والتعامل مع ردّ واجهة برمجة التطبيقات.

القيود المفروضة على طلب البحث

في ما يلي القيود المفروضة على طلبات البحث في الوقت الفعلي من واجهة برمجة التطبيقات:

  • إذا تم تضمين مقياس rt:activeUsers في طلب بحث باستخدام فلاتر السمات التالية، حينئذٍ لا تتم إتاحة سوى عامل التشغيل AND ونوع مطابقة المساواة (==).
    • rt:goalId
    • rt:eventAction
    • rt:eventCategory
    • rt:eventLabel

    بما أنّ مقياس rt:activeUsers يسترد فقط عدد المستخدمين النشطين على الموقع الإلكتروني في الوقت الحالي، لا تستخدم rt:minutesAgo مع rt:activeUsers. وهذا يعني أنّ السمة rt:activeUsers تشير إلى أنّ قيمة rt:minutesAgo هي 0.

  • لا تتوفر فلاتر للمقاييس.
  • لا يمكن استخدام المَعلمة fields.

إدارة الحصص

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

في ما يلي بعض الأمثلة على عمليات التنفيذ التي قد تستهلك الحصة بسرعة كبيرة:

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

لتقليل استخدام الحصة وإدارتها بكفاءة:

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

مثال: احتساب الفاصل الزمني لإعادة التحميل

إذا كنت تتوقع إرسال طلبات منتظمة للحصول على بيانات في الوقت الفعلي، عليك اختيار فاصل إعادة تحميل معقول استنادًا إلى معدّل الاستخدام المتوقّع.

على سبيل المثال، يمكن للملف الشخصي الواحد في "إحصاءات Google" بلوغ 10,000 طلب في اليوم كحد أقصى للحصة اليومية. في يوم واحد، إذا كنت تتوقع إجراء 6,000 طلب بحث في Core Reporting API لملف شخصي واحد، ستكون لديك حصة قدرها 4,000 طلب للملف الشخصي.

لنفترض أنّك قرّرت استخدام واجهة برمجة التطبيقات لإعداد التقارير في الوقت الفعلي لتنفيذ 3 لوحات بيانات في الوقت الفعلي يتم تنفيذ طلبات بحث طوال اليوم عن البيانات في الوقت الفعلي من الملف الشخصي نفسه. يمكن أن تُجري كل لوحة بيانات حوالي 1,333 طلب بحث في اليوم (4,000 طلب بحث / 3 لوحات بيانات). عدد الثواني في اليوم هو 86400 ثانية. وبالتالي، يجب أن يكون الفاصل الزمني لإعادة التحميل لكل لوحة بيانات أكبر من 65 ثانية (86,400 / 1,333) ليكون إجمالي عدد الطلبات اليومية للملف الشخصي أقل من الحد اليومي البالغ 4,000.