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 مقداری بزرگتر از ۱۰۰ دارد.

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 دریافت می‌کند که بر اساس جوامعی با بیش از ۱۰۰ عضو فیلتر شده است. برای نمونه‌ای از پاسخ 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": [],
}

• code : کد هشدار قابل خواندن توسط ماشین
• message : پیام هشدار قابل خواندن توسط انسان
• data : فهرستی از جفت‌های کلید-مقدار که اطلاعات هشدار دقیقی ارائه می‌دهند.