حلّ الأخطاء وإعادة تفعيل اشتراك Google Workspace

توضّح هذه الصفحة كيفية إعادة تفعيل اشتراك معلَّق في Google Workspace من خلال حلّ الأخطاء أو تحديد المشاكل وحلّها واستدعاء طريقة subscriptions.reactivate.

يتم تعليق اشتراكات Google Workspace عندما يمنع حدوث خطأ تلقّي الاشتراك للأحداث. على سبيل المثال، يتم تعليق الاشتراك عندما يتعذّر العثور على المورد المستهدف أو نقطة نهاية الإشعارات. بعد حلّ أي أخطاء في الاشتراك، يمكنك إعادة تفعيله لبدء تلقّي الأحداث مرة أخرى.

يمكنك التعرّف على الاشتراك المعلَّق بالطرق التالية:

  • يتلقّى تطبيقك حدثًا في مراحل النشاط بشأن التعليق. إذا تم تعليق اشتراكك بسبب خطأ في نقطة النهاية، قد لا تتلقّى حدثًا من أحداث دورة الحياة.
  • يمكنك استخدام الطريقتَين subscriptions.get أو subscriptions.list لمعرفة ما إذا كان الحقل state الخاص بالاشتراك مضبوطًا على SUSPENDED.
  • يتم إعلامك بتعذُّر التسليم إلى نقطة نهاية الإشعارات. للتعرّف على كيفية مراقبة حالات تعذُّر التسليم إلى مواضيع Google Cloud Pub/Sub، يُرجى الاطّلاع على مقالة التعامل مع حالات تعذُّر تسليم الرسائل.

تحتفظ الاشتراكات التي تمت إعادة تفعيلها بتاريخ انتهاء الصلاحية الأصلي. لتمديد وقت انتهاء صلاحية الاشتراك، يُرجى الاطّلاع على تعديل اشتراك Google Workspace أو تجديده.

برمجة التطبيقات

  • اشتراك في Google Workspace لإنشاء اشتراك، يُرجى الاطّلاع على إنشاء اشتراك.

  • مشروع "برمجة تطبيقات Google":
    • استخدِم مشروعك على Google Cloud بدلاً من المشروع التلقائي الذي يتم إنشاؤه تلقائيًا بواسطة Apps Script.
    • بالنسبة إلى جميع النطاقات التي أضفتها لإعداد شاشة موافقة OAuth، عليك أيضًا إضافة النطاقات إلى ملف appsscript.json في مشروع "برمجة تطبيقات Google". على سبيل المثال، إذا حدّدت النطاق chat.messages، أضِف ما يلي: 
      • "oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages"
]
    • فعِّل خدمة Google Workspace Events المتقدّمة.

Python

  • الإصدار 3.6 أو الإصدارات الأحدث من Python
  • أداة إدارة الحزم pip
  • أحدث مكتبات برامج Google للغة Python لتثبيتها أو تعديلها، نفِّذ الأمر التالي في واجهة سطر الأوامر: 
      pip3 install --upgrade google-api-python-client google-auth-oauthlib

تحديد الأخطاء وحلّها

لتحديد الخطأ في اشتراك، راجِع الحقل suspensionReason الخاص بالاشتراك. يمكنك العثور على هذا الحقل عند تلقّي حدث دورة الحياة بشأن التعليق، أو باستخدام طريقة subscriptions.get لمراجعة جميع حقول الاشتراك.

يعرض الجدول التالي الأخطاء المحتملة في الاشتراك، وكيفية حلّها عند الإمكان. إذا لم تتمكّن من حلّ المشكلة، يمكنك حذف الاشتراك أو الانتظار إلى أن تنتهي صلاحيته. تحذف Google Workspace Events API الاشتراكات المنتهية الصلاحية تلقائيًا.

خطأ الوصف طرق حلّ المشكلة

USER_SCOPE_REVOKED

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

RESOURCE_DELETED

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

USER_AUTHORIZATION_FAILURE

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

ENDPOINT_PERMISSION_DENIED

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

حسابات الخدمة:
  • أحداث Google Chat: chat-api-push@system.gserviceaccount.com
  • أحداث Google Drive: drive-api-event-push@system.gserviceaccount.com
  • أحداث Google Meet: meet-api-event-push@system.gserviceaccount.com

بالنسبة إلى مواضيع Pub/Sub، امنح حساب الخدمة دور ناشر Pub/Sub (roles/pubsub.publisher) .

ENDPOINT_NOT_FOUND

نقطة نهاية الإشعارات غير متوفّرة أو يتعذّر العثور عليها. تأكَّد من أنّ نقطة النهاية لا تزال نشطة وتعمل. لتحديد المشاكل وحلّها في مواضيع Pub/Sub، راجِع مستندات تحديد المشاكل وحلّها.

ENDPOINT_RESOURCE_EXHAUSTED

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

APP_SCOPE_REVOKED

ألغى مشرف النطاق منح إذن الوصول إلى نطاق واحد أو أكثر من نطاقات OAuth لتطبيق Chat. الحصول على موافقة المشرف

APP_AUTHORIZATION_FAILURE

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

إعادة تفعيل اشتراك

بعد حلّ الخطأ الذي أدّى إلى تعليق اشتراكك، يمكنك استخدام طريقة reactivate للسماح للاشتراك بتلقّي الأحداث مرة أخرى. تتحقّق الطريقة من حلّ جميع الأخطاء وتغيّر قيمة الحقل state في اشتراكك من SUSPENDED إلى ACTIVE.

لإعادة تفعيل اشتراك Google Workspace، اتّبِع الخطوات التالية:

برمجة التطبيقات

  1. في مشروع "برمجة تطبيقات Google"، أنشئ ملف نص برمجي جديدًا باسم reactivateSubscription وأضِف الرمز التالي:

    function reactivateSubscription() {
  // The name of the subscription to reactivate.
  const name = 'subscriptions/SUBSCRIPTION_ID';

  // Call the Workspace Events API using the advanced service.
  const response = WorkspaceEvents.Subscriptions.reactivate({}, name);
  console.log(response);
}

    غيِّر القيم في السلسلة على الشكل التالي:

    • ‫SUBSCRIPTION_ID: رقم تعريف الاشتراك. للحصول على المعرّف، يمكنك استخدام أيّ مما يلي:
      • قيمة الحقل uid
      • معرّف اسم المرجع الممثّل في الحقل name على سبيل المثال، إذا كان اسم المورد هو subscriptions/subscription-123، استخدِم subscription-123.

  2. لإعادة تفعيل اشتراك Google Workspace، شغِّل الدالة reactivateSubscription في مشروع "برمجة تطبيقات Google".

Python

  1. في دليل العمل، أنشئ ملفًا باسم reactivate_subscription.py وأضِف الرمز التالي:

    """Reactivate subscription."""

from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [SCOPES]

# Authenticate with Google Workspace and get user authentication.
flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
CREDENTIALS = flow.run_local_server()

# Call the Workspace Events API using the service endpoint.
service = build(
    'workspaceevents',
    'v1',
    credentials=CREDENTIALS,
)

NAME = 'subscriptions/SUBSCRIPTION_ID'
response = service.subscriptions().reactivate(name=NAME).execute()
print(response)

    غيِّر القيم في السلسلة على الشكل التالي:

    • SCOPES: نطاق واحد أو أكثر من نطاقات OAuth التي تتوافق مع كل نوع من أنواع الأحداث للاشتراك. يتم تنسيقه كصفيف من السلاسل. لإدراج نطاقات متعددة، افصل بينها بفواصل. على سبيل المثال، 'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'.
    • ‫SUBSCRIPTION_ID: رقم تعريف الاشتراك. للحصول على المعرّف، يمكنك استخدام أيّ مما يلي:
      • قيمة الحقل uid
      • معرّف اسم المرجع الممثّل في الحقل name على سبيل المثال، إذا كان اسم المورد هو subscriptions/subscription-123، استخدِم subscription-123.

  2. في دليل العمل، تأكَّد من تخزين بيانات اعتماد معرّف عميل OAuth وتسمية الملف credentials.json. يستخدم نموذج الرمز ملف JSON هذا للمصادقة مع Google Workspace والحصول على بيانات اعتماد المستخدم. للاطّلاع على التعليمات، راجِع مقالة إنشاء بيانات اعتماد معرّف عميل OAuth.

  3. لإعادة تفعيل اشتراك Google Workspace، نفِّذ ما يلي في نافذة الأوامر:

    python3 reactivate_subscription.py
تعرض Google Workspace Events API عملية طويلة الأمد تحتوي على مثيل المورد Subscription.

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

إعادة تفعيل اشتراك كتطبيق Google Chat

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

  1. بدلاً من مصادقة المستخدم، يمكنك المصادقة كتطبيق Chat من خلال موافقة المشرف لمرة واحدة.

  2. حدِّد نطاقات التفويض التي تسمح لتطبيق Chat بالاشتراك في أحداث Chat. تبدأ نطاقات الأذونات هذه دائمًا بـ chat.app، وتشمل ما يلي:

    • https://www.googleapis.com/auth/chat.app.memberships: للاشتراك في أحداث أعضاء مساحة Chat
    • ‫https://www.googleapis.com/auth/chat.app.messages.readonly: للاشتراك في أحداث الرسائل والتفاعلات في "مساحة Chat"
    • https://www.googleapis.com/auth/chat.app.spaces: للاشتراك في أحداث مساحة Chat.

إنشاء مفتاح واجهة برمجة تطبيقات

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

لإنشاء مفتاح واجهة برمجة التطبيقات، افتح مشروع Google Cloud الخاص بتطبيقك واتّبِع الخطوات التالية:

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

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

  2. انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات.
  3. يظهر مفتاح واجهة برمجة التطبيقات الجديد.
    • انقر على "نسخ" لنسخ مفتاح واجهة برمجة التطبيقات واستخدامه في رمز تطبيقك. يمكنك أيضًا العثور على مفتاح واجهة برمجة التطبيقات في قسم "مفاتيح واجهة برمجة التطبيقات" ضمن بيانات اعتماد مشروعك.
    • لمنع الاستخدام غير المصرّح به، ننصحك بفرض قيود على الأماكن التي يمكن فيها استخدام مفتاح واجهة برمجة التطبيقات وعلى واجهات برمجة التطبيقات التي يمكن استخدام المفتاح معها. لمزيد من التفاصيل، يُرجى الاطّلاع على إضافة قيود على واجهة برمجة التطبيقات.

كتابة نص برمجي يستدعي Google Workspace Events API

تعيد عيّنة الرمز البرمجي التالية تفعيل اشتراك تطبيق Chat في Google Workspace:

Python 

  """Reactivate subscription."""

  from google.oauth2 import service_account
  from apiclient.discovery import build

  # Specify required scopes.
  SCOPES = [SCOPES]

  # Specify service account details.
  CREDENTIALS = (
      service_account.Credentials.from_service_account_file('credentials.json')
      .with_scopes(SCOPES)
  )

  # Call the Workspace Events API using the service endpoint.
  service = build(
      'workspaceevents',
      'v1beta',
      credentials=CREDENTIALS,
      discoveryServiceUrl='https://workspaceevents.googleapis.com/$discovery/rest?version=v1beta&labels=DEVELOPER_PREVIEW&key=API_KEY',
  )

  NAME = 'subscriptions/SUBSCRIPTION_ID'
  response = service.subscriptions().reactivate(name=NAME).execute()
  print(response)

غيِّر القيم في السلسلة على الشكل التالي:

  • استبدِل SCOPES بنطاقات التفويض التي تسمح لتطبيق Chat بالاشتراك في أحداث Chat. تبدأ نطاقات الأذونات هذه دائمًا بـ chat.app، وتشمل ما يلي:

    • https://www.googleapis.com/auth/chat.app.memberships: للاشتراك في أحداث أعضاء مساحة Chat
    • ‫https://www.googleapis.com/auth/chat.app.messages.readonly: للاشتراك في أحداث الرسائل والتفاعلات في "مساحة Chat"
    • https://www.googleapis.com/auth/chat.app.spaces: للاشتراك في أحداث مساحة Chat

  • استبدِل API_KEY بمفتاح واجهة برمجة التطبيقات الذي أنشأته لإنشاء نقطة نهاية الخدمة لواجهة برمجة التطبيقات Google Workspace Events API.

  • ‫SUBSCRIPTION_ID: رقم تعريف الاشتراك. للحصول على المعرّف، يمكنك استخدام أيّ مما يلي:

    • قيمة الحقل uid
    • معرّف اسم المرجع الممثّل في الحقل name على سبيل المثال، إذا كان اسم المورد هو subscriptions/subscription-123، استخدِم subscription-123.

تحديد المشاكل في الأخطاء المتعددة وحلّها

إذا تم حلّ الخطأ الذي أدّى إلى تعليق الاشتراك وتعذّر استخدام طريقة الدفع reactivate، قد يكون حدث خطأ آخر بعد تعليق اشتراكك.

لتحديد أخطاء إضافية، راجِع الناتج من الطلب الذي تعذّر تنفيذه. يحتوي الناتج على أي أخطاء لا تزال موجودة.

عندما يتضمّن اشتراكك أخطاء متعدّدة، تستخدم قيمة الحقل suspensionReason دائمًا الخطأ الأصلي الذي أدّى إلى تعليق اشتراكك.