مصادقة المستخدمين ومنحهم الإذن

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

بعد مصادقة واستدعاء واجهة برمجة تطبيقات باستخدام بيانات اعتماد المستخدم، يمكن لتطبيقات Chat إجراء ما يلي:

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

عندما ينفِّذ تطبيق إجراءً باستخدام مصادقة المستخدم (مثل إنشاء مساحة)، يعرض Google Chat رسالة إحالة تخبر المستخدمين باسم التطبيق الذي نفّذ الإجراء للمستخدم الذي فوّضه.

لمزيد من المعلومات عن الحالات التي تتطلب فيها تطبيقات Chat المصادقة ونوع المصادقة المطلوب استخدامها، يُرجى الاطّلاع على أنواع المصادقة المطلوبة في نظرة عامة على المصادقة والترخيص في واجهة برمجة تطبيقات Chat.

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

لاستخدام Google Chat API للوصول إلى موارد مؤسسة Google Workspace أو تعديلها، يجب أن يكون المستخدم عضوًا في تلك المؤسسة. المستخدمون الخارجيون أو المستخدمون الذين ليس لديهم حساب Google Workspace لديه إذن بالوصول إلى Google Chat غير متاحين.

المتطلبات الأساسية

الخطوة 1: تثبيت مكتبة برامج Google

إذا لم يسبق لك تثبيت مكتبات برامج Google للغة التي تختارها، شغِّل الأمر التالي في واجهة سطر الأوامر:

pip3 install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib oauth2client

يمكنك استخدام أي لغة تتوافق مع مكتبات العميل.

الخطوة 2: ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth، وتحديد النطاقات، وتسجيل تطبيقك

عند استخدام OAuth 2.0 للتفويض، تعرض Google شاشة موافقة للمستخدم بما في ذلك ملخّص لمشروعك وسياساته ونطاقات التفويض المطلوبة. إنّ ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth في تطبيقك يحدّد البيانات التي تعرضها Google للمستخدمين ومراجعي التطبيقات، ويسجّل تطبيقك لكي تتمكّن من نشره لاحقًا.

تتطلب جميع التطبيقات التي تستخدم OAuth 2.0 إعداد شاشة الموافقة، ولكن ما عليك سوى إدراج النطاقات للتطبيقات التي يستخدمها الأشخاص من خارج مؤسستك على Google Workspace.

1. في وحدة تحكّم Google Cloud، انتقِل إلى رمز القائمة menu > واجهات برمجة التطبيقات والخدمات > شاشة موافقة OAuth.

   الانتقال إلى شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

2. اختَر نوع المستخدم لتطبيقك، ثم انقر على إنشاء.

3. املأ نموذج تسجيل التطبيق، ثم انقر على حفظ ومتابعة.

4. انقر على إضافة نطاقات أو إزالتها. أضِف نطاقات التفويض التي يطلبها تطبيقك وتحقّق منها، ثم انقر على تعديل، ثم انقر على حفظ ومتابعة.

5. مراجعة ملخص تسجيل التطبيقات انقر على تعديل لإجراء تغييرات، أو انقر على الرجوع إلى لوحة البيانات.

الخطوة 3: إنشاء بيانات اعتماد معرِّف عميل OAuth في Google Cloud Console

للمصادقة كمستخدم مستخدم والوصول إلى بيانات المستخدم في تطبيقك، عليك إنشاء واحد أو أكثر من معرِّفات عميل OAuth 2.0. يتم استخدام معرِّف العميل لتحديد تطبيق واحد لخوادم OAuth من Google. إذا كان تطبيقك يعمل على أنظمة أساسية متعددة، مثل Android وiOS والويب، عليك إنشاء معرِّف عميل منفصل لكل نظام أساسي.

إنشاء بيانات اعتماد معرِّف عميل OAuth

اختَر نوع التطبيق للحصول على تعليمات محدّدة عن كيفية إنشاء معرِّف عميل بروتوكول OAuth:

تنزيل ملف JSON السرّي للعميل

الملف السري في العميل هو تمثيل JSON لبيانات اعتماد معرّف عميل OAuth التي يمكن لتطبيقك Chat الرجوع إليها عند تقديم بيانات الاعتماد.

1. في Google Cloud Console، انتقِل إلى رمز القائمة menu > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.

   الانتقال إلى "بيانات الاعتماد"

2. ضمن معرِّفات عملاء OAuth 2.0، انقر على معرِّف العميل الذي أنشأته.

3. انقر على تنزيل JSON.

4. احفظ الملف باسم client_secrets.json.

الخطوة 4: كتابة نص برمجي يستدعي واجهة برمجة تطبيقات Chat

يستخدِم الرمز التالي مكتبة برامج لاستدعاء Chat API. تتم المصادقة باستخدام واجهة برمجة تطبيقات Chat باستخدام بيانات اعتماد معرّف عميل OAuth، ثم إنشاء مساحة.

احفظ الرمز التالي في ملف باسم chat_space_create_named.py في الدليل نفسه الذي يتضمن client_secrets.json:

from __future__ import print_function

import os.path

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

# Define your app's authorization scopes.
# When modifying these scopes, delete the file token.json, if it exists.
SCOPES = ["https://www.googleapis.com/auth/chat.spaces.create"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then creates a Chat space.
    '''

    flow = InstalledAppFlow.from_client_secrets_file(
                      'client_secrets.json', SCOPES)
    creds = flow.run_local_server()

    # Build a service endpoint for Chat API.
    service = build('chat', 'v1', credentials=creds)

    # Use the service endpoint to call Chat API.
    result = service.spaces().create(

      # Details about the space to create.
      body = {

        # To create a named space, set spaceType to SPACE.
        'spaceType': 'SPACE',

        # The user-visible name of the space.
        'displayName': 'API-made'
      }

      ).execute()

    # Prints details about the created membership.
    print(result)

if __name__ == '__main__':
    main()

الخطوة 5: تشغيل نموذج النص البرمجي

لتشغيل المثال، انتقِل من سطر الأوامر إلى الدليل الذي يحتوي على chat_space_create_named.py وclient_secrets.json، ثم نفِّذ الأمر التالي:

python3 chat_space_create_named.py

سيظهر متصفح يطلب منك تسجيل الدخول إلى حسابك على Google.

بعد تسجيل الدخول، تظهر شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth وتطلب منك منح الإذن للتطبيق.

وبعد منح الإذن، يستدعي النص البرمجي Chat API، التي تستجيب عن طريق إضافة تطبيق Chat إلى مساحة Chat. تطبع وحدة التحكم تفاصيل طلب البيانات من واجهة برمجة التطبيقات.

تحديد مشاكل المثال وحلّها

عند تشغيل chat_space_create_named.py، قد تتلقى رسالة خطأ تفيد بما يلي:

Expected a JSON object with a single property for a "web" or "installed" application

تعني رسالة الخطأ هذه أنّ ملف client_secrets.json الذي تم تنزيله من وحدة تحكُّم Google Cloud لا يبدأ بالسمة "web" أو "installed". بعد المصادقة باستخدام الملف الذي تم تنزيله، إذا لم يحفظ الرمز رمز الدخول في ملف جديد مثل token.json، ستتم كتابة رمز الدخول على client_secrets.json، ما قد يؤدي إلى حدوث هذا الخطأ أثناء محاولات التفويض اللاحقة.

لإصلاح هذا الخطأ، نزِّل الملف السري للعميل من Google Cloud Console مرة أخرى واحفظ الملف الجديد في مكان الملف الحالي.

مواضيع ذات صلة

يمكنك التعرّف على الإجراءات الأخرى التي يمكن أن تتخذها واجهة برمجة التطبيقات في Chat من خلال مراجعة المستندات المرجعية في Chat API.