Method: activities.watch

מתחילים לקבל התראות על פעילויות בחשבון. מידע נוסף זמין במאמר קבלת התראות בדחיפה.

בקשת HTTP

POST https://admin.googleapis.com/admin/reports/v1/activity/users/{userKey or all}/applications/{applicationName}/watch

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.

פרמטרים של נתיב

פרמטרים
userKey or all

string

מייצג את מזהה הפרופיל או את כתובת האימייל של המשתמש שעבורן צריך לסנן את הנתונים. הוא יכול להיות all לכל המידע, או userKey למזהה הפרופיל הייחודי של המשתמש ב-Google Workspace או לכתובת האימייל הראשית שלו. לא יכול להיות משתמש שנמחק. עבור משתמש שנמחק, קוראים ל-users.list ב-Directory API באמצעות showDeleted=true, ואז משתמשים ב-ID שהוחזר כ-userKey.
applicationName

enum (ApplicationName)

שם האפליקציה שעבורה יש לאחזר את האירועים.

פרמטרים של שאילתה

פרמטרים
actorIpAddress

string

כתובת פרוטוקול האינטרנט (IP) של המארח שבו בוצע האירוע. זוהי דרך נוספת לסנן תקציר של דוח לפי כתובת ה-IP של המשתמש שהפעילות שלו מדווחת. כתובת ה-IP הזו משקפת את המיקום הפיזי של המשתמש, אבל לא בהכרח. לדוגמה, כתובת ה-IP יכולה להיות כתובת שרת ה-proxy של המשתמש, או כתובת של רשת וירטואלית פרטית (VPN). הפרמטר הזה תומך גם בגרסה IPv4 וגם בגרסה IPv6 של כתובות.
customerId

string

המזהה הייחודי של הלקוח שלגביו רוצים לאחזר את הנתונים.
endTime

string

הגדרת תאריך הסיום של טווח הזמן שמוצג בדוח. התאריך הוא בפורמט RFC 3339, לדוגמה 2010-10-28T10:26:35.000Z. ערך ברירת המחדל הוא הזמן המשוער של בקשת ה-API. דוח API כולל שלושה מושגי זמן בסיסיים:

  • התאריך שבו נשלחה בקשת ה-API לדוח: התאריך שבו ה-API נוצר ואוחזר את הדוח.
  • מועד ההתחלה של הדוח: תחילת פרק הזמן שמוצג בדוח. הערך startTime חייב להיות לפני endTime (אם צוין) והזמן הנוכחי שבו הבקשה נשלחת, אחרת ה-API מחזיר שגיאה.
  • מועד הסיום של הדוח: סיום פרק הזמן שמוצג בדוח. לדוגמה: טווח הזמן של אירועים שמסוכמים בדוח יכול להתחיל באפריל ולהסתיים במאי. אפשר לבקש את הדוח עצמו באוגוסט.
אם לא מציינים את endTime, הדוח יחזיר את כל הפעילויות מהמועד הנוכחי ב-startTime עד השעה הנוכחית או עד 180 הימים האחרונים, אם הערך של startTime הוא יותר מ-180 ימים בעבר.
eventName

string

שם האירוע שה-API שולח שאילתה אליו. כל eventName קשור לתכונה או לשירות ספציפיים של Google Workspace שה-API מארגן לפי סוגי אירועים. דוגמה לכך היא האירועים ביומן Google בדוחות של האפליקציה במסוף Admin. המבנה של type של הגדרות היומן כולל את כל הפעילויות של eventName ביומן שמדווחות על ידי ה-API. כשאדמין משנה הגדרה של יומן Google, ה-API מדווח על הפעילות הזו בפרמטרים type ו-eventName בהגדרות היומן. למידע נוסף על מחרוזות ופרמטרים של שאילתה eventName, אפשר לעיין ברשימת שמות האירועים לאפליקציות שונות שלמעלה ב-applicationName.
filters

string

מחרוזת השאילתה filters היא רשימה מופרדת בפסיקים שמורכבת מפרמטרים של אירועים שעברו מניפולציה על ידי אופרטורים יחסיים. הפרמטרים של האירועים הם בצורה {parameter1 name}{relational operator}{parameter1 value},{parameter2 name}{relational operator}{parameter2 value},...

הפרמטרים האלה של האירועים משויכים ל-eventName ספציפי. אם הפרמטר של הבקשה לא שייך ל-eventName, מוחזר דוח ריק. לקבלת מידע נוסף על השדות הזמינים של eventName לכל אפליקציה והפרמטרים המשויכים אליה, עוברים לטבלה ApplicationName ולוחצים כדי לעבור לדף 'אירועי פעילות' בנספח של האפליקציה הרצויה.

בדוגמאות הבאות של פעילות ב-Drive, הרשימה שמוחזרת מורכבת מכל אירועי edit שבהם ערך הפרמטר doc_id תואם לתנאים שהוגדרו על ידי האופרטור הרלציוני. בדוגמה הראשונה, הבקשה מחזירה את כל המסמכים שנערכו עם הערך doc_id ששווה ל-12345. בדוגמה השנייה, הדוח מחזיר את כל המסמכים שנערכו שבהם הערך של doc_id לא שווה ל-98765. האופרטור <> מקודד בכתובת URL במחרוזת השאילתה של הבקשה (%3C%3E):

GET...&eventName=edit&filters=doc_id==12345
GET...&eventName=edit&filters=doc_id%3C%3E98765

שאילתת filters תומכת באופרטורים הקשורים הבאים:

  • == — 'שווה ל-'.
  • <> – 'לא שווה ל-'. חייב להיות מקודד בכתובת ה-URL (%3C%3E).
  • < — 'פחות מ-'. הקוד חייב להיות מקודד בכתובת ה-URL (%3C).
  • <= – 'פחות מ- או שווה ל-'. חייב להיות מקודד בכתובת ה-URL (%3C=).
  • > — 'גדול מ-'. הקוד חייב להיות מקודד בכתובת ה-URL (%3E).
  • >= – 'גדול מ- או שווה ל-'. חייב להיות מקודד בכתובת ה-URL (%3E=).

הערה: ה-API לא מקבל כמה ערכים של אותו פרמטר. אם פרמטר מסוים מסופק יותר מפעם אחת בבקשת ה-API, ה-API מקבל רק את הערך האחרון של אותו פרמטר. כמו כן, אם בבקשת ה-API סופק פרמטר לא חוקי, ה-API מתעלם מהפרמטר הזה ומחזיר את התשובה שתואמת לפרמטרים החוקיים הנותרים. אם לא התבקשו פרמטרים, מוחזרים כל הפרמטרים.
maxResults

integer

ההגדרה הזו קובעת כמה רשומות פעילות יוצגו בכל דף תגובה. לדוגמה, אם הבקשה מגדירה את הערך maxResults=1 והדוח כולל שתי פעילויות, הדוח כולל שני דפים. למאפיין nextPageToken של התשובה יש את האסימון לדף השני. מחרוזת השאילתה maxResults היא אופציונלית בבקשה. ערך ברירת המחדל הוא 1,000.
orgUnitID
(deprecated)

string

Deprecated השדה הזה הוצא משימוש ולא נתמך יותר.

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

pageToken

string

האסימון לציין את הדף הבא. דוח עם כמה דפים מכיל בתשובה נכס nextPageToken. בבקשת ההמשך לקבלת הדף הבא של הדוח, מזינים את הערך nextPageToken במחרוזת השאילתה pageToken.
startTime

string

ההגדרה הזו מגדירה את תחילת טווח הזמן שמוצג בדוח. התאריך הוא בפורמט RFC 3339, לדוגמה 2010-10-28T10:26:35.000Z. הדוח יחזיר את כל הפעילויות מ-startTime עד endTime. הערך startTime חייב להיות לפני endTime (אם צוין) והזמן הנוכחי שבו הבקשה נשלחת, אחרת ה-API מחזיר שגיאה.
groupIdFilter

string

מזהי קבוצות מופרדים בפסיקים (obfuscated) של פעילויות של משתמשים מסוננות. כלומר, התגובה תכיל פעילויות רק עבור המשתמשים ששייכים לפחות לאחד ממזהי הקבוצות המוזכרים כאן. פורמט: "id:abc123,id:xyz456"

גוף הבקשה

גוף הבקשה מכיל מופע של SubscriptionChannel.

גוף התשובה

ערוץ התראות שמשמש למעקב אחרי שינויים במשאבים.

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל נתונים במבנה הבא:

ייצוג JSON 
{
  "id": string,
  "token": string,
  "expiration": string,
  "type": string,
  "address": string,
  "payload": boolean,
  "params": {
    string: string,
    ...
  },
  "resourceId": string,
  "resourceUri": string,
  "kind": string
}
שדות
id

string

מזהה ייחודי אוניברסלי (UUID) או מחרוזת ייחודית דומה המזהה את הערוץ הזה.
token

string

מחרוזת שרירותית שתישלח לכתובת היעד בכל התראה שנמסרה בערוץ הזה. זה שינוי אופציונלי.
expiration

string (int64 format)

התאריך והשעה של התפוגה של ערוץ ההתראות, מבוטאים כחותמת זמן של Unix, באלפיות השנייה. זה שינוי אופציונלי.
type

string

סוג מנגנון הצגת המודעות שבו נעשה שימוש בערוץ הזה. הערך צריך להיות "web_hook".
address

string

הכתובת שאליה נשלחות התראות מהערוץ הזה.
payload

boolean

ערך בוליאני שמציין אם רוצים להשתמש במטען ייעודי (payload). מטען ייעודי (payload) הוא נתונים שנשלחים בגוף הודעת HTTP POST, PUT או PATCH ומכיל מידע חשוב על הבקשה. זה שינוי אופציונלי.
params

map (key: string, value: string)

פרמטרים נוספים ששולטים בהתנהגות של ערוץ הצגת המודעות. זה שינוי אופציונלי.

אובייקט שמכיל רשימה של "key": value זוגות. לדוגמה: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
resourceId

string

מזהה אטום שמזהה את המשאב שצופים בו בערוץ הזה. יציב בגרסאות שונות של API.
resourceUri

string

מזהה ספציפי לגרסה של המשאב שנצפה.
kind

string

מזהה את הערוץ כערוץ התראות שמשמש למעקב אחרי שינויים במשאב – 'api#channel'.

היקפי ההרשאות

נדרש היקף ההרשאות הבא של OAuth:

  • https://www.googleapis.com/auth/admin.reports.audit.readonly

מידע נוסף זמין במדריך להרשאות.

ApplicationName

שם האפליקציה שעבורה יש לאחזר את האירועים.

טיפוסים בני מנייה (enum)
access_transparency

בדוחות הפעילות של Google Workspace Access Transparency מוחזר מידע על סוגים שונים של אירועי פעילות של שקיפות גישה.
admin

דוחות הפעילות של האפליקציה של מסוף Admin מחזירים פרטי חשבון לגבי סוגים שונים של אירועי פעילות של אדמין.
calendar

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

בדוחות הפעילות של אפליקציית Google Drive מוצגים מידע לגבי אירועי פעילות שונים ב-Google Drive. דוח הפעילות ב-Drive זמין רק ללקוחות Google Workspace Business ו-Google Workspace Enterprise.
gcp דוחות הפעילות של אפליקציית Google Cloud Platform מחזירים מידע על אירועי פעילות שונים של GCP.
gplus דוחות הפעילות של אפליקציית Google+ מחזירים מידע לגבי אירועי פעילות שונים ב-Google+.
groups

בדוחות הפעילות של האפליקציה 'קבוצות Google' מוצגים מידע על אירועי פעילות שונים בקבוצות Google.
groups_enterprise

דוחות הפעילות של קבוצות Enterprise מחזירים מידע לגבי אירועי פעילות שונים של קבוצות Enterprise.
jamboard בדוחות הפעילות ב-Jamboard מוחזר מידע על אירועי פעילות שונים ב-Jamboard.
login

דוחות הפעילות של אפליקציית ההתחברות מחזירים פרטי חשבון לגבי סוגים שונים של אירועי פעילות התחברות.
meet בדוח 'פעילות ביקורת' של Meet מחזיר מידע על סוגים שונים של אירועי פעילות ביקורת של Meet.
mobile בדוח 'פעילות ביקורת על מכשירים' מחזיר מידע על סוגים שונים של אירועים של פעילות ביקורת על מכשירים.
rules

בדוח 'פעילות של כללים' מוצג מידע על סוגים שונים של אירועי פעילות של כללים.
saml

בדוח הפעילות ב-SAML מוחזר מידע על סוגים שונים של אירועי פעילות ב-SAML.
token

דוחות הפעילות של אפליקציית האסימון מחזירים פרטי חשבון לגבי סוגים שונים של אירועי פעילות של אסימון.
user_accounts

בדוחות הפעילות של האפליקציה 'חשבונות משתמשים' מוצגים פרטי חשבון לגבי סוגים שונים של אירועי פעילות של חשבונות משתמשים.
context_aware_access

דוחות פעילות בקרת גישה מבוססת-הקשר מחזירים מידע על אירועי גישה שנדחו עקב כללים לבקרת גישה מבוססת-הקשר.
chrome

בדוחות הפעילות ב-Chrome מוצגים מידע על אירועים בדפדפן Chrome וב-ChromeOS.
data_studio בדוחות הפעילות ב-Data Studio מוחזר מידע על סוגים שונים של אירועי פעילות ב-Data Studio.
keep בדוחות הפעילות של אפליקציית Keep מוחזרות מידע על אירועי פעילות שונים ב-Google Keep. דוח הפעילות ב-Keep זמין רק ללקוחות Google Workspace Business ו-Enterprise.