REST Resource: subscriptions

المرجع: الاشتراك

اشتراك لتلقّي أحداث عن أحد موارد Google Workspace للاطّلاع على مزيد من المعلومات عن الاشتراكات، اطّلِع على نظرة عامة على Google Workspace Events API.

تمثيل JSON 
{
  "name": string,
  "uid": string,
  "targetResource": string,
  "eventTypes": [
    string
  ],
  "payloadOptions": {
    object (PayloadOptions)
  },
  "notificationEndpoint": {
    object (NotificationEndpoint)
  },
  "state": enum (State),
  "suspensionReason": enum (ErrorType),
  "authority": string,
  "createTime": string,
  "updateTime": string,
  "reconciling": boolean,
  "etag": string,

  // Union field expiration can be only one of the following:
  "expireTime": string,
  "ttl": string
  // End of list of possible types for union field expiration.
}
الحقول
name

string

المُعرّف. اسم مورد الاشتراك

التنسيق: subscriptions/{subscription}
uid

string

النتائج فقط. معرّف فريد يحدّده النظام للاشتراك
targetResource

string

مطلوب. غير قابل للتغيير مورد Google Workspace الذي يتم تتبُّع الأحداث فيه، بتنسيق اسم المورد الكامل للتعرّف على الموارد المستهدَفة والأحداث التي تتيحها، اطّلِع على أحداث Google Workspace المتوافقة.

لا يمكن للمستخدم تفويض تطبيقك إلا بإنشاء اشتراك واحد لمورد مستهدَف معيّن. إذا حاول تطبيقك إنشاء اشتراك آخر باستخدام بيانات اعتماد المستخدم نفسها، يعرض الطلب خطأ ALREADY_EXISTS.
eventTypes[]

string

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

تعتمد أنواع الأحداث المتوافقة على المورد المستهدَف لاشتراكك. لمعرفة التفاصيل، يُرجى الاطّلاع على أحداث Google Workspace المتوافقة.

تتلقّى أيضًا تلقائيًا أحداثًا عن مراحل اشتراكك. لست بحاجة إلى تحديد أحداث مراحل النشاط لهذا الحقل.

إذا حدّدت نوع حدث غير متوفّر للمورد المستهدَف، يعرض الطلب رمز حالة HTTP 400 Bad Request.
payloadOptions

object (PayloadOptions)

اختياريّ. خيارات حول البيانات التي يجب تضمينها في الحمولة الخاصة بالحدث لا تتوفّر هذه الميزة إلا لأحداث Google Chat.
notificationEndpoint

object (NotificationEndpoint)

مطلوب. غير قابل للتغيير. نقطة النهاية التي يُرسِل إليها الاشتراك الأحداث، مثل موضوع Pub/Sub
state

enum (State)

النتائج فقط. حالة الاشتراك لتحديد ما إذا كان الاشتراك يمكنه تلقّي الأحداث وإرسالها إلى نقطة نهاية الإشعار.
suspensionReason

enum (ErrorType)

النتائج فقط. الخطأ الذي أدّى إلى تعليق الاشتراك

لإعادة تفعيل الاشتراك، عليك حلّ الخطأ والاتصال بطريقة subscriptions.reactivate.
authority

string

النتائج فقط. المستخدم الذي سمح بإنشاء الاشتراك

تنسيق الملف: users/{user}

بالنسبة إلى مستخدمي Google Workspace، تكون القيمة {user} هي الحقل user.id من واجهة برمجة تطبيقات الدليل.
createTime

string (Timestamp format)

النتائج فقط. الوقت الذي يتم فيه إنشاء الاشتراك
updateTime

string (Timestamp format)

النتائج فقط. آخر مرة تم فيها تعديل الاشتراك
reconciling

boolean

النتائج فقط. إذا كانت الإجابة true، يعني ذلك أنّه تتم معالجة الاشتراك.
etag

string

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

حقل الربط expiration الوقت الذي تنتهي فيه صلاحية الاشتراك

يعتمد الحد الأقصى لمدة انتهاء الصلاحية على ما إذا كان اشتراكك يتضمّن بيانات الموارد في حِزم بيانات الأحداث (المحدّدة في حقل PayloadOptions):

  • يمكنك تنفيذ ما يصل إلى 7 أيام في حال حذف الحمولات بيانات الموارد.
  • إذا كانت الحمولات تتضمّن بيانات الموارد، تصل إلى 4 ساعات. إذا منحت مؤسستك على Google Workspace إذن الوصول إلى المورد من خلال تفويض على مستوى النطاق، يمكنك تمديد وقت انتهاء صلاحية الاشتراك لمدة تصل إلى 24 ساعة.

بعد انتهاء صلاحية الاشتراك، يتم حذفه تلقائيًا. تتلقّى أحداث دورة الحياة قبل notification_endpoint 12 ساعة وقبل ساعة واحدة من انتهاء صلاحية الاشتراك. لمعرفة التفاصيل، يُرجى الاطّلاع على تلقي الأحداث في مراحل النشاط والردّ عليها.

لمنع انتهاء صلاحية اشتراك، يمكنك استخدام طريقة UpdateSubscription لإطالة تاريخ انتهاء صلاحيته. لمعرفة التفاصيل، يُرجى الاطّلاع على تعديل اشتراك أو تجديده. يمكن أن يكون expiration واحدًا فقط مما يلي:
expireTime

string (Timestamp format)

القيمة التلقائية غير فارغة. الطابع الزمني بالتوقيت العالمي المنسّق عند انتهاء صلاحية الاشتراك يتم عرضها دائمًا في الإخراج، بغض النظر عن ما تم استخدامه في الإدخال.
ttl

string (Duration format)

الإدخال فقط مدة البقاء (TTL) أو مدة الاشتراك في حال عدم تحديد هذه السمة أو ضبطها على 0، يتم استخدام أقصى مدة ممكنة.

PayloadOptions

خيارات حول البيانات التي يجب تضمينها في الحمولة الخاصة بالحدث لا تتوفّر هذه الميزة إلا لأحداث Google Chat.

تمثيل JSON 
{
  "includeResource": boolean,
  "fieldMask": string
}
الحقول
includeResource

boolean

اختياريّ. ما إذا كانت حِزمة بيانات الحدث تتضمّن بيانات عن المورد الذي تغيّر على سبيل المثال، بالنسبة إلى حدث تم فيه إنشاء رسالة على Google Chat، ما إذا كانت الحمولة تحتوي على بيانات عن المورد Message. إذا كان القيمة خطأ، لا تتضمّن الحمولة الأساسية للحدث سوى اسم المورد الذي تم تغييره.
fieldMask

string (FieldMask format)

اختياريّ. إذا تم ضبط includeResource على true، قائمة الحقول المطلوب تضمينها في الحمولة الخاصة بالحدث افصل بين الحقول بفاصلة. على سبيل المثال، لتضمين مُرسِل رسالة Google Chat وإنشاء الوقت، أدخِل message.sender,message.createTime. في حال حذفها، ستتضمّن الحمولة جميع حقول المورد.

إذا حدّدت حقلًا غير متوفّر للمورد، يتجاهل النظام الحقل.

NotificationEndpoint

نقطة النهاية التي يرسل إليها الاشتراك الأحداث.

تمثيل JSON 
{

  // Union field endpoint can be only one of the following:
  "pubsubTopic": string
  // End of list of possible types for union field endpoint.
}
الحقول

حقل الاتحاد endpoint.

يمكن أن يكون endpoint واحدًا فقط مما يلي:
pubsubTopic

string

غير قابل للتغيير موضوع Cloud Pub/Sub الذي يتلقّى أحداث الاشتراك

تنسيق الملف: projects/{project}/topics/{topic}

يجب إنشاء الموضوع في مشروع Google Cloud نفسه الذي أنشأت فيه هذا الاشتراك.

عندما يتلقّى الموضوع أحداثًا، يتم ترميز الأحداث كرسائل Cloud Pub/Sub. لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة ربط بروتوكول Google Cloud Pub/Sub بـ CloudEvents.

الحالة

الحالات المحتملة للاشتراك

عمليات التعداد
STATE_UNSPECIFIED القيمة التلقائية هذه القيمة غير مستخدَمة.
ACTIVE الاشتراك نشط ويمكنه تلقّي الأحداث وإرسالها إلى نقطة نهاية الإشعار.
SUSPENDED يتعذّر على الاشتراك تلقّي الأحداث بسبب خطأ. لتحديد الخطأ، راجِع الحقل suspensionReason.
DELETED تم حذف الاشتراك.

ErrorType

قد تحدث أخطاء في أحد الاشتراكات.

عمليات التعداد
ERROR_TYPE_UNSPECIFIED القيمة التلقائية هذه القيمة غير مستخدَمة.
USER_SCOPE_REVOKED ألغى المستخدم المفوَّض منح نطاق OAuth واحد أو أكثر. لمزيد من المعلومات عن التفويض في Google Workspace، راجِع مقالة ضبط شاشة موافقة بروتوكول OAuth.
RESOURCE_DELETED لم يعُد المورد المستهدَف للاشتراك متوفّرًا.
USER_AUTHORIZATION_FAILURE لم يعُد بإمكان المستخدم الذي فوّض بإنشاء الاشتراك الوصول إلى المورد المستهدَف للاشتراك.
ENDPOINT_PERMISSION_DENIED لا يمكن لتطبيق Google Workspace عرض الأحداث في نقطة نهاية الإشعارات الخاصة باشتراكك.
ENDPOINT_NOT_FOUND لا تتوفّر نقطة نهاية الإشعارات للاشتراك، أو لا يمكن العثور على نقطة النهاية في مشروع Google Cloud الذي أنشأت فيه الاشتراك.
ENDPOINT_RESOURCE_EXHAUSTED تعذّر على نقطة نهاية الإشعارات للاشتراك تلقّي الأحداث بسبب عدم كفاية الحصة أو الوصول إلى الحدّ الأقصى لمعدّل الإرسال.
OTHER حدث خطأ غير محدّد.

الطُرق

create

 لإنشاء اشتراك في Google Workspace

delete

 لحذف اشتراك في Google Workspace

get

 الحصول على تفاصيل عن اشتراك Google Workspace

list

 يعرض هذا الجدول اشتراكات Google Workspace.

patch

 تعديل اشتراك Google Workspace أو تجديده

reactivate

 إعادة تفعيل اشتراك Google Workspace معلَّق.