التفويض

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

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

قبل أن يتمكّن المستخدمون من عرض معلومات حساباتهم على الموقع الإلكتروني لخدمة "إحصاءات 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 API Console. (يمكنك تخطّي هذه الخطوة إذا كانت واجهة برمجة التطبيقات غير مدرَجة في وحدة تحكم 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" من خلال متصفّح. وهي تلغي الحاجة إلى إمكانات من جهة الخادم، ولكنّها تجعل إعداد التقارير المبرمَجة أو غير المتصلة بالإنترنت أو المجدوَلة أمرًا غير عملي.

مثال:

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

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

أمثلة:

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

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

تكون حسابات الخدمة مفيدة للوصول المبرمَج أو غير المتصل بالإنترنت أو المجدوَل إلى بيانات "إحصاءات 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 التالي:

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

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

يبلغ الحدّ الأقصى لكل زوج فريد من عميل OAuth 2.0 وحساب على "إحصاءات Google" 25 رمزًا مميزًا لإعادة التحميل. إذا استمر التطبيق في طلب رموز مميزة لإعادة التحميل لزوج "العميل/الحساب" نفسه، بعد إصدار الرمز المميز رقم 26، سيصبح رمز إعادة التحميل الأول الذي تم إصداره سابقًا غير صالح. سيؤدي الرمز المميز الـ 27 المطلوب لإعادة التحميل إلى إبطال الرمز المميز الثاني الذي تم إصداره سابقًا، وهكذا.