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 subscription_options can be only one of the following:
  "driveOptions": {
    object (DriveOptions)
  }
  // End of list of possible types for union field subscription_options.

  // Union field authority_info can be only one of the following:
  "userAuthority": string,
  "serviceAccountAuthority": string
  // End of list of possible types for union field authority_info.

  // 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 وGoogle Drive.
notificationEndpoint

object (NotificationEndpoint)

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

enum (State)

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

enum (ErrorType)

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

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

string

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

عندما يمنح المستخدم الإذن بالاشتراك، يكون لهذا الحقل والحقل userAuthority القيمة نفسها ويكون التنسيق كما يلي:

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

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

عندما يمنح تطبيق Chat الإذن بالاشتراك، يتم ملء الحقل serviceAccountAuthority فقط ويكون هذا الحقل فارغًا.
createTime

string (Timestamp format)

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

string (Timestamp format)

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

boolean

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

string

اختياريّ. يتم احتساب مجموع التحقّق هذا من قِبل الخادم استنادًا إلى قيمة الحقول الأخرى، وقد يتم إرساله في طلبات التعديل للتأكّد من أنّ العميل لديه قيمة حديثة قبل المتابعة.
حقل الدمج subscription_options خيارات اشتراك إضافية متاحة لمراجع مستهدَفة معيّنة لاشتراكات Google Workspace يمكن أن تكون subscription_options إحدى القيم التالية فقط:
driveOptions

object (DriveOptions)

اختياريّ. الميزات التي تتوفّر فقط للاشتراكات في موارد Drive
حقل الدمج authority_info الهوية التي سمحت بإنشاء الاشتراك. يمكن أن تكون authority_info إحدى القيم التالية فقط:
userAuthority

string

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

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

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

serviceAccountAuthority

string

النتائج فقط. حساب الخدمة الذي تم استخدامه لتفويض إنشاء الاشتراك يجب أن يكون حساب الخدمة هذا مملوكًا لمشروع Google Cloud نفسه الذي تنشئ فيه هذا الاشتراك.

التنسيق: projects/{projectId}/serviceAccounts/{service_account_id}

حقل الدمج expiration الوقت الذي تنتهي فيه صلاحية الاشتراك

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

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

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

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

string (Timestamp format)

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

string (Duration format)

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

DriveOptions

خيارات إضافية متاحة لعرض أحداث Drive.

تمثيل JSON 
{
  "includeDescendants": boolean
}
الحقول
includeDescendants

boolean

اختياريّ. غير قابل للتغيير بالنسبة إلى الاشتراكات في أحداث Google Drive، يمكنك تحديد ما إذا كنت تريد تلقّي أحداث حول ملفات Drive التي تكون تابعة للمجلد أو مساحة التخزين السحابي المشتركة المستهدَفة.

  • إذا كانت القيمة false، لن يتلقّى الاشتراك سوى أحداث حول التغييرات التي تطرأ على المجلد أو مساحة التخزين السحابي المشتركة المحدّدة كـ targetResource.
  • إذا كانت القيمة true، يجب ضبط حقل mimeType الخاص بالمورد file على application/vnd.google-apps.folder.

لمعرفة التفاصيل، يُرجى الاطّلاع على أنواع أحداث Google Drive.

PayloadOptions

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

تمثيل 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.
APP_SCOPE_REVOKED ألغى مشرف النطاق منح واحد أو أكثر من نطاقات OAuth للتطبيق.
RESOURCE_DELETED لم يعُد المرجع المستهدف للاشتراك متوفّرًا.
USER_AUTHORIZATION_FAILURE لم يعُد بإمكان المستخدم الذي سمح بإنشاء الاشتراك الوصول إلى المورد المستهدف للاشتراك.
APP_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 المعلَّق.