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

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

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

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

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

object (PayloadOptions)

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

object (NotificationEndpoint)

مطلوبة. غير قابل للتغيير. نقطة النهاية التي يعرض فيها الاشتراك أحداثًا، مثل موضوع النشر/الاشتراك.
state

enum (State)

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

enum (ErrorType)

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

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

string

النتائج فقط. المستخدِم الذي فوَّض لإنشاء الاشتراك.

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

بالنسبة إلى مستخدمي Google Workspace، تكون القيمة {user} هي الحقل user.id من Directory API.
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)

القيمة التلقائية غير فارغة. الطابع الزمني بالتوقيت العالمي المنسق (UTC) عند انتهاء صلاحية الاشتراك. يتم عرضه دائمًا عند الإدخال، بغض النظر عمّا تم استخدامه عند الإدخال.
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 لـ CloudEvent.

الحالة

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

عمليات التعداد
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