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 הוא מזהה ישות שהוא ספציפי לאפליקציה שבה נמצאת הישות. בחומר העזר בנושא API מוסבר איך לקבל את ה-entityKey של הישות המסוימת שמעניינת אותך. הפרמטרים האחרים מתועדים למעלה, בקטע אחזור כל פעילויות השימוש בישויות.

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