REST Resource: subscriptions

משאב: מינוי

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

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

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

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

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

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

boolean

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

string (FieldMask format)

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

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

NotificationEndpoint

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

ייצוג 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 שהושעה.