التفويض

يوضّح هذا الدليل كيفية تفويض التطبيق للطلبات المرسَلة إلى واجهة برمجة التطبيقات User Deletion API.

السماح بالطلبات

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

عندما يرسل تطبيقك طلبًا إلى واجهة برمجة التطبيقات Analytics API، يجب أن يحتوي هذا الطلب على رمز موافقة مميز. ويساعد الرمز المميز محرك البحث Google في التعرّف على تطبيقك.

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

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

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

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

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

  1. عند إنشاء التطبيق، يجب تسجيله باستخدام وحدة التحكم في واجهة Google API. ويوفر محرك البحث Google المعلومات التي ستحتاجها في ما بعد، مثل معرّف العميل وسر العميل.
  2. فعِّل Analytics API في وحدة تحكّم واجهة برمجة تطبيقات Google. (يمكنك تخطّي هذه الخطوة إذا كانت واجهة برمجة التطبيقات غير مدرَجة في وحدة التحكم في واجهة 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.user.deletion حذف البيانات باستخدام User Deletion API

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

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

مسارات OAuth 2.0 الشائعة

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

خادم الويب

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

مثال:

  • تعديل لوحات بيانات المستخدِمين تلقائيًا باستخدام أحدث بيانات "إحصاءات Google"
جديد.

من جهة العميل

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

مثال:

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

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

أمثلة:

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

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

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

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