REST Resource: subscriptions

משאב: Subscription

מינוי לקבלת אירועים לגבי משאב ב-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)

זה שינוי אופציונלי. אפשרויות לגבי הנתונים שרוצים לכלול בתוכן של האירוע. הפעולה הזו נתמכת רק באירועים ב-Google Chat.
notificationEndpoint

object (NotificationEndpoint)

חובה. קבוע. נקודת הקצה שבה המינויים מעבירים אירועים, כמו נושא Pub/Sub.
state

enum (State)

פלט בלבד. המצב של המינוי. המדיניות הזו קובעת אם המינוי יכול לקבל אירועים ולשלוח אותם לנקודת הקצה של ההתראה.
suspensionReason

enum (ErrorType)

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

כדי להפעיל מחדש את המינוי, צריך לפתור את השגיאה ולקרוא ל-method‏ 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

אפשרויות לגבי הנתונים שרוצים לכלול בתוכן של האירוע. הפעולה הזו נתמכת רק באירועים ב-Google Chat.

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

boolean

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

string (FieldMask format)

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

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

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

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

כשהנושא מקבל אירועים, האירועים מקודדים כהודעות של Cloud Pub/Sub. פרטים נוספים זמינים במאמר קישור פרוטוקול של Google Cloud Pub/Sub ל-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 אירעה שגיאה לא מזוהה.

שיטות

create

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

delete

 מחיקה של מינוי ל-Google Workspace.

get

 הצגת פרטים על מינוי ל-Google Workspace.

list

 רשימת המינויים ל-Google Workspace.

patch

 מעדכנים או מחדשים את המינוי ל-Google Workspace.

reactivate

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