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 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.

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

אם תציינו סוג אירוע שלא קיים במשאב היעד, הבקשה תחזיר קוד סטטוס 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

פלט בלבד. המשתמש שאישר את יצירת המינוי.

כשהמשתמש מאשר את המינוי, הערך של השדה הזה זהה לערך של השדה 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 ימים.
  • אם המטענים הייעודיים (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.
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 אירעה שגיאה לא מזוהה.

Methods

create

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

delete

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

get

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

list

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

patch

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

reactivate

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