Core Reporting API - الإذن

يوضِّح هذا الدليل الطريقة التي يسمح بها التطبيق بإرسال الطلبات إلى Core Reporting API.

الموافقة على الطلبات

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

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

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

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

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

يجب أن يتم تفويض جميع الطلبات إلى Analytics API من قِبل مستخدم تمت مصادقته.

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

  1. عند إنشاء التطبيق، يجب تسجيله باستخدام وحدة التحكم في واجهة Google API. ويوفر محرك البحث Google المعلومات التي ستحتاجها في ما بعد، مثل معرّف العميل وسر العميل.
  2. تفعيل واجهة برمجة تطبيقات "إحصاءات Google" في وحدة تحكّم واجهة برمجة تطبيقات 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.readonly إذن بالاطّلاع على واجهة برمجة تطبيقات "إحصاءات Google"

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

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

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

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

خادم الويب

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

مثال:

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

من جهة العميل

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

مثال:

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

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

أمثلة:

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

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

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

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