Method: activities.watch

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

בקשת HTTP

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

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

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

פרמטרים
userKey

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. כשאדמין משנה הגדרה ביומן, ה-API מדווח על הפעילות הזו בפרמטרים type ו-eventName של הגדרות היומן. למידע נוסף על מחרוזות ופרמטרים של שאילתה eventName, אפשר לעיין ברשימת שמות האירועים לאפליקציות שונות שלמעלה ב-applicationName.
filters

string

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

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

בדוגמאות הבאות לפעילות ב-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).
  • >= – 'גדול מ- או שווה ל-'. חייב להיות מקודד בכתובת האתר (%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

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

ערך בוליאני שמציין אם רצוי לשלוח את עומס העבודה. עומס שימושי הוא נתונים שנשלחים בגוף של הודעת 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

דוחות הפעילות של 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 Groups מספקים מידע על אירועי פעילות שונים בקבוצות.
groups_enterprise

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

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

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

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

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

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

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

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