REST Resource: subscriptions

משאב: Subscription

מינוי לקבלת אירועים לגבי משאב ב-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 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. המועד שבו יפוג תוקף המינוי.

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

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

זה שינוי אופציונלי. האם המטען הייעודי (Payload) של האירוע כולל נתונים על המשאב שהשתנה. לדוגמה, באירוע שבו נוצרה הודעה ב-Google Chat, האם עומס העבודה מכיל נתונים על המשאב 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 שהושעה.