واجهة برمجة التطبيقات للإدارة - التفويض

يصف هذا الدليل كيفية تفويض أحد التطبيقات للطلبات لواجهة برمجة تطبيقات الإدارة.

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

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

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

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

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

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

يجب تفويض جميع الطلبات إلى "إحصاءات Google" من خلال مستخدم تمت مصادقته.

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

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

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

في ما يلي معلومات على نطاق OAuth 2.0 لواجهة برمجة التطبيقات في "إحصاءات Google":

النطاق المعنى
https://www.googleapis.com/auth/analytics.readonly حق الوصول إلى واجهة برمجة تطبيقات "إحصاءات Google" للقراءة فقط.
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" داخل المتصفّح. يُلغي ذلك الحاجة إلى الإمكانات من جهة الخادم، ولكنه يجعل التقارير التلقائية أو غير المتصلة بالإنترنت أو المجدوَلة غير عملية.

مثال:

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

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

أمثلة:

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

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

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

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

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

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