REST Resource: subscriptions

משאב: מנוי

מינוי לקבלת אירועים לגבי משאב ב-Google Workspace. מידע נוסף על מינויים זמין בסקירה הכללית על Google Workspace Event 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.

כברירת מחדל, תקבלו גם אירועים שקשורים למחזור החיים של המינוי שלכם. אין צורך לציין אירועים במחזור החיים בשדה הזה.

אם מציינים סוג אירוע שאינו קיים למשאב היעד, הבקשה תחזיר את קוד הסטטוס 400 Bad Request של HTTP.
payloadOptions

object (PayloadOptions)

אפשרות. אפשרויות לגבי הנתונים שיש לכלול במטען הייעודי (payload) של האירוע. התכונה נתמכת רק עבור אירועים ב-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. המועד שבו המינוי יפוג.

זמן התפוגה המקסימלי תלוי בשאלה אם המינוי כולל נתוני משאבים במטענים ייעודיים (payloads) של אירועים (מצוין בשדה PayloadOptions):

  • אם מטענים ייעודיים לא משמיטים נתוני משאבים, עד 7 ימים.
  • אם מטענים ייעודיים (payloads) כוללים נתוני משאבים, עד 4 שעות. אם הארגון שלכם ב-Google Workspace העניק גישה למשאב באמצעות הענקת גישה ברמת הדומיין, תוכלו להאריך את זמן התפוגה של המינוי עד ל-24 שעות.

כשתוקף המינוי פג, הוא נמחק באופן אוטומטי. יתקבלו אירועים במחזור החיים של notification_endpoint 12 שעות ושעה לפני שתוקף המינוי יפוג. מידע נוסף מופיע במאמר קבלת אירועים במחזור חיים ותגובה אליהם.

כדי שתוקף של מינוי לא יפוג, אפשר להשתמש בשיטה UpdateSubscription כדי להאריך את תאריך התפוגה שלו. מידע נוסף מופיע במאמר בנושא עדכון או חידוש של מינוי. expiration יכול להיות רק אחד מהבאים:
expireTime

string (Timestamp format)

שדה ברירת המחדל לא ריק. חותמת הזמן לפי שעון UTC (זמן אוניברסלי מתואם) של המינוי. תמיד מוצג בפלט, ללא קשר למה שנעשה בו שימוש בקלט.
ttl

string (Duration format)

קלט בלבד. משך החיים (TTL) או משך המינוי. אם לא צוין או מוגדר הערך 0, המערכת משתמשת במשך הזמן המקסימלי האפשרי.

PayloadOptions

אפשרויות לגבי הנתונים שיש לכלול במטען הייעודי (payload) של האירוע. התכונה נתמכת רק עבור אירועים ב-Google Chat.

ייצוג JSON 
{
  "includeResource": boolean,
  "fieldMask": string
}
שדות
includeResource

boolean

אפשרות. האם המטען הייעודי של האירוע כולל נתונים על המשאב שהשתנה. לדוגמה, באירוע שבו נוצרה הודעה ב-Google Chat, האם המטען הייעודי מכיל נתונים על המשאב Message. אם False, המטען הייעודי של האירוע כולל רק את שם המשאב שהשתנה.
fieldMask

string (FieldMask format)

אפשרות. אם המדיניות includeResource מוגדרת לערך true, זו רשימת השדות שצריך לכלול במטען הייעודי (payload) של האירוע. יש להפריד בין השדות באמצעות פסיק. לדוגמה, כדי לכלול את פרטי השולח של ההודעה ב-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 for CloudEvents.

ארץ

מצבים אפשריים למינוי.

טיפוסים בני מנייה (enums)
STATE_UNSPECIFIED ערך ברירת המחדל. הערך הזה לא בשימוש.
ACTIVE המינוי פעיל ויכול לקבל אירועים ולשלוח אותם לנקודת הקצה של ההתראות.
SUSPENDED אי אפשר לשלוח אירועים במינוי עקב שגיאה. כדי לזהות את השגיאה, אפשר לבדוק את השדה suspensionReason.
DELETED המינוי נמחק.

ErrorType

שגיאות אפשריות במינוי.

טיפוסים בני מנייה (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 שהושעה.