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 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 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 וב-Google Drive.
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

אופציונלי. סכום הבדיקה הזה מחושב על ידי השרת על סמך הערך של שדות אחרים, ויכול להיות שהוא יישלח בבקשות עדכון כדי לוודא שללקוח יש ערך עדכני לפני שהוא ממשיך.
שדה איחוד subscription_options. אפשרויות מינוי נוספות שזמינות למשאבי יעד ספציפיים במינויים ל-Google Workspace. הערך subscription_options יכול להיות רק אחד מהבאים:
driveOptions

object (DriveOptions)

אופציונלי. תכונות שנתמכות רק במינויים במשאבי Drive.

שדה איחוד expiration. המועד שבו תוקף המינוי יפוג.

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

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

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

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

string (Timestamp format)

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

string (Duration format)

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

DriveOptions

אפשרויות נוספות שנתמכות להצגת אירועים ב-Drive.

ייצוג ב-JSON 
{
  "includeDescendants": boolean
}
שדות
includeDescendants

boolean

אופציונלי. אי אפשר לשנות אותו. למינויים לאירועים ב-Google Drive, האם לקבל אירועים לגבי קבצים ב-Drive שהם צאצאים של תיקיית היעד או של האחסון השיתופי.

  • אם false, המינוי יקבל רק אירועים לגבי שינויים בתיקייה או באחסון השיתופי שצוינו כ-targetResource.
  • אם הערך הוא true, השדה mimeType של המשאב file צריך להיות מוגדר ל-application/vnd.google-apps.folder.

פרטים נוספים מופיעים במאמר בנושא סוגי אירועים ב-Google Drive.

PayloadOptions

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

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

boolean

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

string (FieldMask format)

אופציונלי. אם includeResource מוגדר ל-true, רשימת השדות שייכללו במטען הייעודי (payload) של האירוע. מפרידים בין השדות באמצעות פסיק. לדוגמה, כדי לכלול את השולח של הודעה ב-Google Chat ואת זמן היצירה שלה, מזינים message.sender,message.createTime. אם לא מציינים שדות, מטען הייעודי כולל את כל השדות של המשאב.

אם מציינים שדה שלא קיים במשאב, המערכת מתעלמת מהשדה.

NotificationEndpoint

נקודת הקצה (endpoint) שאליה המינוי מעביר אירועים.

ייצוג ב-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

אי אפשר לשנות אותו. נושא Pub/Sub שמקבל אירועים למינוי.

פורמט: projects/{project}/topics/{topic}

צריך ליצור את הנושא באותו פרויקט ב-Google Cloud שבו יוצרים את המינוי הזה.

הערה: Google Workspace Events API משתמש במפתחות סידור כדי לסדר את האירועים ברצף. אם בנושא Cloud Pub/Sub מוגדרת מדיניות אחסון הודעות שמוציאה מהכלל את האזור הקרוב ביותר ב-Google Cloud, פרסום אירועים עם מפתחות סידור ייכשל.

כשהנושא מקבל אירועים, האירועים מקודדים כהודעות Pub/Sub. פרטים נוספים זמינים במאמר Google Cloud Pub/Sub Protocol Binding for CloudEvents.

מדינה

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

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

ErrorType

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

טיפוסים בני מנייה (enum)
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 אירעה שגיאה לא מזוהה.

Methods

create

 יצירת מינוי ל-Google Workspace.

delete

 מחיקת מינוי ל-Google Workspace.

get

 קבלת פרטים על מינוי ל-Google Workspace.

list

 מציג את המינויים ל-Google Workspace.

patch

 עדכון או חידוש של מינוי Google Workspace.

reactivate

 הפעלה מחדש של מינוי ל-Google Workspace שהושעה.