Management API - التفويض

ويصف هذا الدليل كيفية تفويض أحد التطبيقات للطلبات إلى Management API.

تفويض الطلبات

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

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

نبذة عن بروتوكولات التفويض

يجب أن يستخدم تطبيقك OAuth 2.0 للسماح بالطلبات. ولا يُسمح باستخدام أي بروتوكولات أخرى للموافقة على الطلبات. إذا كان تطبيقك يستخدم ميزة تسجيل الدخول باستخدام حساب Google، ستتم معالجة بعض جوانب عملية الموافقة على الطلبات نيابةً عنك.

الموافقة على الطلبات باستخدام OAuth 2.0

يجب أن يصادق مستخدم مصادَق عليه على كلّ الطلبات الموجّهة إلى Analytics API.

تختلف تفاصيل عملية الموافقة على الطلبات لبروتوكول OAuth 2.0 نوعًا ما حسب نوع التطبيق الذي تكتبه. وتسري العملية العامة التالية على كل أنواع التطبيقات:

1. عند إنشاء التطبيق، يجب تسجيله باستخدام وحدة التحكم في واجهة Google API. ويوفر محرك البحث Google المعلومات التي ستحتاجها في ما بعد، مثل معرّف العميل وسر العميل.
2. فعِّل واجهة برمجة تطبيقات "إحصاءات Google" في وحدة التحكُّم في واجهة Google API. (يمكنك تخطّي هذه الخطوة إذا كانت واجهة برمجة التطبيقات غير مدرَجة في وحدة التحكم في واجهة Google API.)
3. إذا احتاج التطبيق الدخول إلى بيانات المستخدِم، يطلب التطبيق من Google نطاقًا معينًا للدخول.
4. يعرض Google شاشة الموافقة للمستخدم، ويطلب منه السماح لتطبيقك بطلب بعض بياناته.
5. عند موافقة المستخدِم، يمنح Google تطبيقك رمز دخول قصير الأجل.
6. يطلب تطبيقك بيانات المستخدِم، من خلال إرفاق رمز الدخول بالطلب.
7. يعرض Google البيانات المطلوبة بعد تحققه من صلاحية طلبك والرمز المميز.

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

في ما يلي معلومات عن نطاق OAuth 2.0 في Analytics API:

النطاق	المعنى
https://www.googleapis.com/auth/analytics.readonly	إذن بالقراءة فقط في Analytics API
https://www.googleapis.com/auth/analytics.edit	تعديل كيانات إدارة "إحصاءات Google".
https://www.googleapis.com/auth/analytics.manage.users	عرض وإدارة أذونات المستخدمين لحسابات "إحصاءات Google"
https://www.googleapis.com/auth/analytics.manage.users.readonly	عرض أذونات مستخدم "إحصاءات Google"

لطلب الدخول باستخدام بروتوكول OAuth 2.0، يحتاج التطبيق معلومات عن النطاق، بالإضافة إلى المعلومات التي يوفّرها Google عند تسجيل التطبيق (مثل معرِّف العميل وسر العميل).

نصيحة: يمكن لمكتبات عملاء Google APIs معالجة جزء من عملية السماح بالنيابة عنك. وتتوفّر هذه المكتبات للعديد من لغات البرمجة، ويمكنك الاطّلاع على صفحة المكتبات والنماذج للحصول على مزيد من التفاصيل.

التدفقات الشائعة لبروتوكول OAuth 2.0

في ما يلي حالات الاستخدام الشائعة لتدفقات OAuth 2.0 المحددة:

خادم الويب

تصلح هذه العملية للوصول التلقائي أو بلا اتصال بالإنترنت أو المجدول إلى بيانات "إحصاءات Google" الخاصة بالمستخدم.

مثال:

• يتم تعديل لوحات بيانات المستخدم تلقائيًا بآخر بيانات "إحصاءات Google".

من جانب العميل

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

مثال:

• أداة إعداد تقارير مستندة إلى المتصفّح مثل مستكشف طلبات البحث في "إحصاءات Google".

التطبيقات المثبّتة

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

أمثلة:

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

حسابات الخدمة

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

لبدء استخدام Analytics API، عليك أولاً استخدام أداة الإعداد، التي ترشدك خلال عملية إنشاء مشروع في وحدة التحكم في واجهة Google API، وتفعيل واجهة برمجة التطبيقات، وإنشاء بيانات الاعتماد.

لإعداد حساب خدمة جديد، اتّبِع الخطوات التالية:

1. انقر على إنشاء بيانات الاعتماد > مفتاح حساب الخدمة.
2. اختَر ما إذا كنت تريد تنزيل المفتاح العام/الخاص لحساب الخدمة كملف 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 المطلوب إلى إلغاء صلاحية الرمز المميز الثاني الذي تم إصداره سابقًا، وهكذا.