Reports API: דוח שימוש בישויות

בדוח השימוש בישויות מופיעות פעילויות בשירות Google Workspace שקשורות לישויות שבהן משתמשים המשתמשים בחשבון. אפשר להתאים אישית את הדוחות האלה ולסנן אותם כדי לקבל מידע ספציפי על השימוש. הנתונים זמינים מ-30 הימים האחרונים.

השימוש בדוח השימוש בישויות מותר רק למטרות חוקיות בהתאם להסכם הלקוח. הדוחות האלה חלים גם על Google Workspace ו-Education.

שליפת כל פעילויות השימוש בישויות

סוג הישות היחיד שנתמך על ידי ה-API הזה הוא קהילות Google+‎. כדי לאחזר דוח של כל הפעילויות שקשורות לישויות של אפליקציות בחשבון, משתמשים בבקשת ה-HTTP GET הבאה וכוללים את אסימון ההרשאה שמתואר במסמכי ההרשאה. כדי שיהיה קל יותר לקרוא, הדוגמה הבאה מפורמטת עם מעברי שורה:

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults

הערך date הוא התאריך שבו התרחשה השימוש, וחותמת הזמן היא בפורמט ISO 8601,‏ yyyy-mm-dd. מומלץ להשתמש באזור הזמן של החשבון. מידע נוסף על פרמטרים של מחרוזת שאילתה ומאפייני תגובה זמין בהפניית ה-API. מידע על הפרמטרים של דוח השימוש בישויות מופיע במאמר בנושא פרמטרים של שימוש בישויות.

‫applicationParameters: רשימה מופרדת בפסיקים של הפרמטרים שרוצים לאחזר. הפורמט של כל פרמטר הוא application:parameter_name, לדוגמה, gplus:community_name. הפרמטרים הזמינים מתועדים במאמר בנושא פרמטרים של שימוש בישויות. אם לא מציינים פרמטרים, כל הפרמטרים מוחזרים.

‫parameterFilters היא רשימה מופרדת בפסיקים של מסננים שיוחלו על התוצאות. כל מסנן צריך להיות בפורמט application:parameter_name[relational_operator]parameter_value. לדוגמה, המסנן gplus:num_total_members>100 מסנן את התוצאות כך שיכללו רק תוצאות שבהן הערך של הפרמטר gplus:num_total_members גדול מ-100.

‫maxResults הוא המספר המקסימלי של תוצאות שיוחזרו באחזור יחיד. אם המספר הכולל של התוצאות גדול יותר, התגובה תיחתך ויופיע בה nextPageToken (ראו את הדוגמה לתגובת JSON בהמשך).

דוגמאות

בדוגמה הבאה מוצג דוח שמכיל את כל הפרמטרים של כל ישויות gplus_communities.

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11

בדוגמה הבאה מוצג דוח שמכיל את הפרמטר community_name לכל הישויות gplus_communities.

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11?parameters=gplus:community_name

בדוגמה הבאה מתקבל דוח של community_name ושל num_total_members לכל ישות gplus_communities, מסונן לפי קהילות עם יותר מ-100 חברים. דוגמה לתגובת API מופיעה בדוגמה לתגובת JSON.

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/2017-12-11
?parameters=gplus:community_name,gplus:num_total_members&filters=gplus:num_total_members>100

אחזור דוח לגבי ישות ספציפית

כדי לאחזר דוח עבור ישות ספציפית, משתמשים בבקשת ה-HTTP GET הבאה וכוללים את אסימון ההרשאה שמתואר במסמכי ההרשאה. כדי שיהיה קל יותר לקרוא את הדוגמה הבאה, הוספנו בה מעברי שורה.

GET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults

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

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

דוגמאות

בדוגמה הבאה מוצג דוח הישות של ישות gplus_community עם entityKey '1234'.

https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11

דוגמה לתגובת JSON של דוח שימוש

תגובה מוצלחת מחזירה קוד סטטוס HTTP 200. בנוסף לקוד הסטטוס, התשובה מחזירה דוח. חלק מהפרמטרים בתגובה הושמטו כדי שהתגובה תהיה קלה יותר לקריאה.

דוגמה לתגובת JSON לדוח ישויות

{
 "kind": "reports#usageReports",
 "nextPageToken": "NjQ1OTgwODk0MzkxNDAwNjQ0OA",
 "usageReports": [
 {
   "kind": "admin#reports#usageReport",
   "date": "2017-12-11",
   "entity": {
    "type": "OBJECT",
    "customerId": "C03az79cb",
    "objectType": "GPLUS_COMMUNITY",
    "objectId": "1234",
   },
   "parameters": [
    {
      "name": "gplus:community_name",
      "stringValue": "My Community"
    },
    {
     "name": "gplus:num_total_members",
     "intValue": 37
    },
    {
     "name": "gplus:num_7day_active_members",
     "intValue": 12
    },
    {
     "name": "gplus:num_30day_active_members",
     "intValue": 17
    },
   ]
  }
 ]
}

דוגמה לתגובת JSON לדוח ישויות עם אזהרות

אם אי אפשר למלא את הבקשה, יכול להיות שיוחזרו אחת או יותר אזהרות בתגובה. בדוגמה הזו, הדוח לא זמין בזמן שליחת הבקשה.

‫

{
 "kind": "reports#usageReports",
 "warnings": [
    {
      "code": "PARTIAL_DATA_AVAILABLE"
      "message": "Data for date 2017-12-11 for application gplus is not available right now, please try again after a few hours."
      "data": [
        {
          "key": "date"
          "value": "2017-12-11"
        }
      ]
    }
  ],
 "usageReports": [],
}

כל רשומה במערך warnings מכילה את הפרמטרים הבאים:

• code: קוד אזהרה שניתן לקריאה על ידי מכונה
• message: הודעת אזהרה שקריאה לאנשים
• ‫data: רשימה של צמדי מפתח/ערך שמספקים מידע מפורט על האזהרה