Reports API: Entities Usage Report

گزارش استفاده از نهادها، فعالیت‌های خدمات Google Workspace مربوط به نهادهای مورد استفاده توسط کاربران حساب شما را برمی‌گرداند. این گزارش ها را می توان برای اطلاعات استفاده خاص سفارشی و فیلتر کرد. داده های 30 روز گذشته در دسترس است.

گزارش استفاده از نهادها ممکن است فقط برای اهداف قانونی مطابق با توافق نامه مشتری شما استفاده شود. این گزارش‌ها برای Google Workspace و Education نیز اعمال می‌شود.

همه فعالیت‌های استفاده از موجودیت‌ها را بازیابی کنید

در حال حاضر، تنها نوع موجودی که توسط این API پشتیبانی می‌شود، انجمن‌های +Google هستند. برای بازیابی گزارشی از تمام فعالیت‌های مربوط به نهادهای برنامه در حساب خود، از درخواست GET HTTP زیر استفاده کنید و کد مجوز شرح داده شده در اسناد مجوز را اضافه کنید. برای خوانایی، مثال زیر با بازگشت خط فرمت شده است:

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 قالب‌بندی می‌شود. پارامترهای موجود در مرجع Entities Usage Parameters مستند شده اند. اگر هیچ پارامتری مشخص نشده باشد، همه برگردانده می شوند.

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

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

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

{
 "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
    },
   ]
  }
 ]
}

{
 "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": [],
}