يصف هذا الدليل كيف يسمح أحد التطبيقات بالطلبات إلى واجهة برمجة التطبيقات Real Time Reporting API.
الموافقة على الطلبات
قبل أن يتمكن المستخدمون من عرض معلومات حساباتهم على موقع Google Analytics على الويب، يجب عليهم تسجيل الدخول أولاً إلى حساباتهم في Google. وبالمثل، عند دخول المستخدمين إلى تطبيقك لأول مرة، يجب عليهم منح التطبيق الإذن بالوصول إلى بياناتهم.
عندما يرسل تطبيقك طلبًا إلى واجهة برمجة تطبيقات "إحصاءات Google"، يجب أن يتضمّن رمزًا مميّزًا للتفويض. ويساعد الرمز المميز محرك البحث Google في التعرّف على تطبيقك.
نبذة عن بروتوكولات التفويض
يجب أن يستخدم تطبيقك OAuth 2.0 للسماح بالطلبات. ولا يُسمح باستخدام أي بروتوكولات أخرى للموافقة على الطلبات. إذا كان تطبيقك يستخدم ميزة تسجيل الدخول باستخدام حساب Google، ستتم معالجة بعض جوانب عملية الموافقة على الطلبات نيابةً عنك.
الموافقة على الطلبات باستخدام OAuth 2.0
يجب أن يوافق مستخدم مصادَق عليه على كلّ الطلبات الموجّهة إلى Analytics API.
تختلف تفاصيل عملية الموافقة على الطلبات لبروتوكول OAuth 2.0 نوعًا ما حسب نوع التطبيق الذي تكتبه. وتسري العملية العامة التالية على كل أنواع التطبيقات:
- عند إنشاء التطبيق، يجب تسجيله باستخدام وحدة التحكم في واجهة Google API. ويوفر محرك البحث Google المعلومات التي ستحتاجها في ما بعد، مثل معرّف العميل وسر العميل.
- يجب تفعيل Analytics API في وحدة التحكم في واجهة Google API. (يمكنك تخطّي هذه الخطوة إذا كانت واجهة برمجة التطبيقات غير مدرَجة في وحدة التحكم في واجهة Google API.)
- إذا احتاج التطبيق الدخول إلى بيانات المستخدِم، يطلب التطبيق من Google نطاقًا معينًا للدخول.
- يعرض Google شاشة الموافقة للمستخدم، ويطلب منه السماح لتطبيقك بطلب بعض بياناته.
- عند موافقة المستخدِم، يمنح Google تطبيقك رمز دخول قصير الأجل.
- يطلب تطبيقك بيانات المستخدِم، من خلال إرفاق رمز الدخول بالطلب.
- يعرض Google البيانات المطلوبة بعد تحققه من صلاحية طلبك والرمز المميز.
تستلزم بعض التدفقات إجراء خطوات إضافية، مثل استخدام رموز مميزة للتحديث للحصول على رموز دخول جديدة. لمزيد من المعلومات التفصيلية حول العمليات المتعلقة بمختلف أنواع التطبيقات، راجِع مستندات بروتوكول OAuth 2.0 في Google.
في ما يلي معلومات عن نطاق OAuth 2.0 في واجهة برمجة تطبيقات "إحصاءات Google":
| النطاق | المعنى |
|---|---|
https://www.googleapis.com/auth/analytics.readonly |
إذن بالقراءة فقط في واجهة برمجة تطبيقات "إحصاءات Google" |
لطلب الدخول باستخدام بروتوكول OAuth 2.0، يحتاج التطبيق معلومات عن النطاق، بالإضافة إلى المعلومات التي يوفّرها Google عند تسجيل التطبيق (مثل معرِّف العميل وسر العميل).
نصيحة: يمكن لمكتبات عملاء Google APIs معالجة جزء من عملية السماح بالنيابة عنك. وتتوفّر هذه المكتبات للعديد من لغات البرمجة، ويمكنك الاطّلاع على صفحة المكتبات والنماذج للحصول على مزيد من التفاصيل.
مسارات OAuth 2.0 الشائعة
في ما يلي قائمة بحالات الاستخدام الشائعة لمسارات OAuth 2.0 محددة:
خادم الويب
ويصلح هذا التدفق إلى الوصول المبرمَج أو بلا اتصال بالإنترنت أو الوصول المُجدوَل إلى بيانات المستخدم على "إحصاءات Google".
مثال:
- تحديث لوحات بيانات المستخدمين تلقائيًا بأحدث بيانات في "إحصاءات Google".
من جهة العميل
وهذا التدفق مثالي للتطبيقات عندما يتفاعل المستخدمون مباشرةً مع التطبيق للوصول إلى بياناتهم في "إحصاءات Google" داخل أحد المتصفحات. يلغي ذلك الحاجة إلى إمكانات جانب الخادم، ولكنه يجعل إعداد التقارير الآلية أو بلا اتصال بالإنترنت أو المجدول غير عملي.
مثال:
- أداة إعداد تقارير مستندة إلى المتصفح مثل مستكشف طلبات البحث في "إحصاءات Google".
التطبيقات المثبّتة
هذا التدفق للتطبيقات التي يتم توزيعها كحزمة وتثبيتها من قبل المستخدم. يتطلّب هذا المسار أن يتمكّن التطبيق أو المستخدم من الوصول إلى المتصفّح لإكمال عملية المصادقة.
أمثلة:
- تطبيق مصغّر للكمبيوتر المكتبي على جهاز كمبيوتر شخصي أو جهاز Mac.
- مكوّن إضافي لنظام إدارة المحتوى: تكمن فائدة هذا التدفق مقارنةً بخادم الويب أو من جهة العميل في إمكانية استخدام مشروع واحد لوحدة تحكُّم واجهة برمجة التطبيقات مع تطبيقك. يتيح ذلك إعداد التقارير الموحّدة وتثبيت أسهل للمستخدمين.
حسابات الخدمة
حسابات الخدمة مفيدة في الوصول المبرمَج أو بلا اتصال بالإنترنت أو الوصول المجدول إلى بيانات "إحصاءات Google" لحسابك. على سبيل المثال، لإنشاء لوحة تحكم مباشرة لبيانات Google Analytics الخاصة بك ومشاركتها مع مستخدمين آخرين.
لبدء استخدام واجهة برمجة التطبيقات Analytics، يجب أولاً استخدام أداة الإعداد التي ترشدك خلال إنشاء مشروع في وحدة التحكم في واجهة Google API وتفعيل واجهة برمجة التطبيقات وإنشاء بيانات الاعتماد.
لإعداد حساب خدمة جديد، عليك اتّباع الخطوات التالية:
- انقر على إنشاء بيانات اعتماد > مفتاح حساب الخدمة.
- اختَر ما إذا كنت تريد تنزيل المفتاح العام/الخاص بحساب الخدمة كملف P12 عادي، أو كملف JSON يمكن تحميله من خلال مكتبة برامج Google API.
يتم إنشاء زوج المفتاح العام/الخاص وتنزيله على جهازك، ويعد هذا الزوج هو النسخة الوحيدة من هذا المفتاح. أنت مسئول عن تخزينها بأمان.
تحديد المشاكل وحلّها
يتعذّر منح الإذن في الحالات التالية:
ستتلقّى رمز الحالة
401إذا انتهت صلاحيةaccess_tokenأو إذا كنت تستخدم النطاق غير الصحيح لواجهة برمجة التطبيقات.ستحصل على رمز الحالة
403إذا لم يكن لدى المستخدم المُصرَّح له حق الوصول إلى الملف الشخصي (الملف الشخصي). تأكد من حصولك على تفويض من المستخدم الصحيح ومن أن لديه الملف الشخصي (الملف الشخصي) الذي حددته.
ملعب OAuth 2.0
تسمح لك هذه الأداة بإكمال مسار التفويض بالكامل من خلال واجهة ويب. تعرض الأداة أيضًا جميع رؤوس طلبات HTTP المطلوبة لإجراء طلب بحث معتمد. إذا لم تتمكن من الحصول على إذن للعمل في تطبيقك الخاص، يجب محاولة تشغيل هذا من خلال واجهة OAuth 2.0 التجريبية. بعد ذلك، يمكنك مقارنة عناوين HTTP والطلب من الملعب بما يرسله تطبيقك إلى "إحصاءات Google". وتعد عملية التحقق هذه طريقة بسيطة لضمان تنسيق طلباتك بشكل صحيح.
منحة غير صالحة
عند محاولة استخدام رمز مميّز لإعادة التحميل، يعرض ما يلي خطأ invalid_grant:
- ساعة الخادم غير متزامنة مع بروتوكول وقت الشبكة - NTP.
- تم تجاوز حد الرمز المميز للتحديث.
يمكن أن تطلب التطبيقات عدة رموز مميزة لإعادة التحميل للوصول إلى حساب واحد على "إحصاءات Google".
على سبيل المثال، إذا أراد أحد المستخدمين تثبيت تطبيق على أجهزة متعددة والوصول إلى حساب "إحصاءات Google" نفسه، سيتطلب الأمر رمزًا مميّزًا منفصلاً لكل جهاز. عندما يتجاوز عدد الرموز المميّزة لإعادة التحميل الحدّ المسموح به، تصبح الرموز المميّزة القديمة غير صالحة. إذا حاول التطبيق استخدام رمز مميّز لإعادة التحميل غير صالح، سيتم عرض استجابة خطأ invalid_grant.
الحد الأقصى لكل زوج فريد من عميل OAuth 2.0 وحساب "إحصاءات Google" هو 25 رمزًا مميزًا لإعادة التحميل. إذا استمر التطبيق في طلب الرموز المميّزة لإعادة التحميل لزوجَي العميل والحساب نفسه، فبعد إصدار الرمز المميّز السادس والعشرين، سيصبح الرمز المميّز الأول لإعادة التحميل الذي تم إصداره سابقًا غير صالح. سيؤدي الرمز المميّز رقم 27 لإعادة التحميل إلى إلغاء صلاحية الرمز المميّز الثاني الذي تم إصداره سابقًا وهكذا.