دليل المطوّر

يوضّح هذا المستند كيفية استخدام واجهة برمجة التطبيقات Real Time Reporting API للحصول على بيانات "إحصاءات 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.