دليل مطوّري البرامج

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

المقدمة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

أمثلة على الرموز

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

قيود طلب البحث

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

  • إذا تم تضمين مقياس 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 طلب بحث في واجهة برمجة التطبيقات الأساسية لإعداد التقارير لملف شخصي واحد، ستكون لديك حصة تبلغ 4,000 طلب متبقٍ لذلك الملف الشخصي.

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