REST Resource: subscriptions

المورد: الاشتراك

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

تمثيل 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)

الإدخال فقط تمثّل هذه السمة مدة الاشتراك أو مدة بقائه. في حال عدم تحديدها أو ضبطها على 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

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

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

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

ملاحظة: تستخدم "واجهة برمجة تطبيقات أحداث Google Workspace" مفاتيح ترتيب للاستفادة من الأحداث المتسلسلة. إذا كان موضوع Cloud Pub/Sub يتضمّن سياسة تخزين الرسائل تم ضبطها لاستبعاد أقرب منطقة على Google 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 المعلَّق.