REST Resource: subscriptions

منبع: اشتراک

اشتراکی برای دریافت رویدادهای مربوط به یک منبع Google Workspace. برای کسب اطلاعات بیشتر درباره اشتراک‌ها، به نمای کلی API رویدادهای 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 ساعت افزایش دهید.

پس از انقضای اشتراک، به طور خودکار حذف می شود. رویدادهای چرخه حیات را 12 ساعت و یک ساعت قبل از انقضای اشتراک در notification_endpoint دریافت می‌کنید. برای جزئیات، به رویدادهای چرخه حیات دریافت و پاسخ دهید .

برای جلوگیری از انقضای یک اشتراک، می توانید از روش 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 وارد کنید. در صورت حذف، payload شامل تمام فیلدهای منبع می شود.

اگر فیلدی را مشخص کنید که برای منبع وجود ندارد، سیستم آن فیلد را نادیده می گیرد.

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 Binding for CloudEvents مراجعه کنید.

ایالت

حالت های احتمالی برای اشتراک

Enums
STATE_UNSPECIFIED مقدار پیش فرض این مقدار استفاده نشده است.
ACTIVE اشتراک فعال است و می تواند رویدادها را به نقطه پایانی اعلان خود دریافت و تحویل دهد.
SUSPENDED اشتراک به دلیل یک خطا قادر به دریافت رویدادها نیست. برای شناسایی خطا، قسمت suspensionReason را ببینید.
DELETED اشتراک حذف شده است.

نوع خطا

خطاهای احتمالی برای اشتراک

Enums
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 را دوباره فعال می کند.
،

منبع: اشتراک

اشتراکی برای دریافت رویدادهای مربوط به یک منبع Google Workspace. برای کسب اطلاعات بیشتر درباره اشتراک‌ها، به نمای کلی API رویدادهای 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 ساعت افزایش دهید.

پس از انقضای اشتراک، به طور خودکار حذف می شود. رویدادهای چرخه حیات را 12 ساعت و یک ساعت قبل از انقضای اشتراک در notification_endpoint دریافت می‌کنید. برای جزئیات، به رویدادهای چرخه حیات دریافت و پاسخ دهید .

برای جلوگیری از انقضای یک اشتراک، می توانید از روش 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 وارد کنید. در صورت حذف، payload شامل تمام فیلدهای منبع می شود.

اگر فیلدی را مشخص کنید که برای منبع وجود ندارد، سیستم آن فیلد را نادیده می گیرد.

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 Binding for CloudEvents مراجعه کنید.

ایالت

حالت های احتمالی برای اشتراک

Enums
STATE_UNSPECIFIED مقدار پیش فرض این مقدار استفاده نشده است.
ACTIVE اشتراک فعال است و می تواند رویدادها را به نقطه پایانی اعلان خود دریافت و تحویل دهد.
SUSPENDED اشتراک به دلیل یک خطا قادر به دریافت رویدادها نیست. برای شناسایی خطا، قسمت suspensionReason را ببینید.
DELETED اشتراک حذف شده است.

نوع خطا

خطاهای احتمالی برای اشتراک

Enums
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 را دوباره فعال می کند.