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,

  "driveOptions": {
    object (DriveOptions)
  }
  "userAuthority": string,
  "serviceAccountAuthority": string
  "expireTime": string,
  "ttl": string
}
שדות
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 שבו אתם יוצרים את המינוי הזה.

פורמט: projects/{projectId}/serviceAccounts/{service_account_id}

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

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

  • אם במטען הייעודי (payload) לא נכללים נתוני משאבים, עד 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

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

ייצוג ב-JSON 
{

  "pubsubTopic": string
}
שדות

שדה איחוד 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.

מדינה (State)

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

טיפוסים בני מנייה (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 שבו יצרתם את המינוי.
ENDPOINT_RESOURCE_EXHAUSTED נקודת הקצה של ההתראה של המינוי לא קיבלה אירועים בגלל מכסה לא מספיקה או הגעה להגבלת קצב של יצירת בקשות.
OTHER אירעה שגיאה לא מזוהה.

Methods

create

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

delete

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

get

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

list

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

patch

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

reactivate

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