المصادقة كتطبيق Chat

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

يمكن لتطبيقات Chat استخدام حسابات الخدمة للمصادقة عند طلب واجهة برمجة تطبيقات Google Chat REST بشكل غير متزامن:

  • أرسل رسائل إلى Google Chat باستخدام spaces.messages.create إلى:
    • أبلغ المستخدمين عند انتهاء تشغيل مهمة طويلة المدى في الخلفية.
    • تنبيه المستخدمين بأن الخادم قد انقطع اتصاله بالإنترنت.
    • اطلب من أحد موظّفي دعم العملاء الاعتناء بحالته التي تم فتحها حديثًا.
  • تعديل الرسائل المُرسَلة سابقًا باستخدام spaces.messages.update إلى:
    • تغيير حالة التشغيل المستمر
    • تعديل المستخدم الذي تم إسناد المهمة إليه أو تاريخ تسليمها
  • إدراج المستخدمين في مساحة باستخدام spaces.members.list لإجراء ما يلي:
    • عرض الأشخاص المتاحين في المساحة.
    • تحقّق من توفُّر عضوية في المساحة لجميع أعضاء الفريق.

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

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

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

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

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

لتشغيل المثال الوارد في هذا الدليل، يجب استيفاء المتطلبات الأساسية التالية:

لغة Python

الخطوة 1: إنشاء حساب خدمة في Google Cloud Console

أنشِئ حساب خدمة سيستخدمه تطبيق Chat للوصول إلى واجهات Google API.

إنشاء حساب خدمة:

لإنشاء حساب خدمة، اتّبِع الخطوات التالية:

  1. في Google Cloud Console، انتقِل إلى رمز القائمة > إدارة الهوية وإمكانية الوصول والمشرف > حسابات الخدمة.

    الانتقال إلى حسابات الخدمة

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

يظهر حساب الخدمة في صفحة حساب الخدمة. بعد ذلك، أنشئ مفتاحًا خاصًا لحساب الخدمة.

إنشاء مفتاح خاص

ولإنشاء مفتاح خاص لحساب الخدمة، اتّبِع الخطوات التالية:

  1. في Google Cloud Console، انتقِل إلى رمز القائمة > إدارة الهوية وإمكانية الوصول والمشرف > حسابات الخدمة.

    الانتقال إلى حسابات الخدمة

  2. اختَر حساب الخدمة.
  3. انقر على المفاتيح > إضافة مفتاح > إنشاء مفتاح جديد.
  4. اختَر JSON، ثم انقر على إنشاء.

    يتم إنشاء زوج مفاتيح عام/خاص جديد وتنزيله على جهازك كملف جديد. هذا الملف هو النسخة الوحيدة من هذا المفتاح. للحصول على معلومات حول كيفية تخزين مفتاحك بشكل آمن، يُرجى الاطّلاع على إدارة مفاتيح حساب الخدمة.

  5. انقر على إغلاق.

لمزيد من المعلومات حول حسابات الخدمة، يُرجى الاطّلاع على حسابات الخدمة في مستندات Google Cloud IAM.

الخطوة 2: كتابة نص برمجي يستخدم حساب الخدمة للمصادقة باستخدام Chat REST API

تتم المصادقة على الرمز التالي باستخدام Chat REST API باستخدام حساب خدمة، ثم نشر رسالة إلى مساحة Chat:

لغة Python

  1. في دليل العمل، أنشِئ ملفًا باسم chat_app_auth.py.

  2. يُرجى تضمين الرمز التالي في chat_app_auth.py:

    from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'service_account.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# Create a Chat message.
result = chat.spaces().messages().create(

    # The space to create the message in.
    #
    # Replace SPACE_NAME with a space name.
    # Obtain the space name from the spaces resource of Chat API,
    # or from a space's URL.
    parent='spaces/SPACE_NAME',

    # The message to create.
    body={'text': 'Hello, world!'}

).execute()

print(result)

  3. في الرمز، استبدِل SPACE_NAME باسم مساحة يمكنك الحصول عليها من طريقة spaces.list في Chat API أو من عنوان URL لمساحة.

الخطوة 3: تنفيذ المثال الكامل

في دليل العمل، أنشِئ النموذج وشغِّله:

لغة Python

python3 chat_app_auth.py

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

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

يصف هذا القسم المشاكل الشائعة التي قد تواجهها أثناء محاولة تشغيل هذا النموذج.

لا يُسمح لك باستخدام هذا التطبيق.

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

<HttpError 403 when requesting https://chat.googleapis.com/v1/spaces/{space}/messages?alt=json returned "You are not permitted to use this app". Details: "You are not permitted to use this app">

تعني رسالة الخطأ هذه أنّ تطبيق Chat لا يملك الإذن بنشر رسائل Chat في مساحة Chat التي يحاول النشر فيها.

لإصلاح الخطأ، يمكنك إضافة تطبيق Chat إلى مساحة Chat المحدَّدة في chat_app_auth.py.

الخطوة التالية

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