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 من 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)

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