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

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

تعتمد أنواع الأحداث المتوافقة على المورد المستهدف لاشتراكك. لمعرفة التفاصيل، يُرجى الاطّلاع على أحداث 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 من واجهة برمجة تطبيقات الدليل.
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. إذا كانت القيمة "false"، لن تتضمّن حمولة الحدث سوى اسم المورد الذي تم تغييره.
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 Protocol for Cloudالأحداث.

الحالة

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

عمليات التعداد
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 معلَّق.