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 HTTP زیر استفاده کنید و کد مجوز شرح داده شده در اسناد مجوز را اضافه کنید. برای خوانایی، مثال زیر با بازگشت خط فرمت شده است.
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 : فهرست جفت‌های کلید-مقدار که اطلاعات هشدار دقیقی را ارائه می‌دهد
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Reports API: Entities Usage Report\n\nThe entities usage report returns Google Workspace service activities related to entities\nused by your account's users. These reports can be customized and filtered for specific usage\ninformation. Data is available for the past 30 days.\n\nThe entities usage report may be used only for lawful purposes in\naccordance with your Customer Agreement. These reports also apply to\nGoogle Workspace and Education.\n\nRetrieve all entities usage activities\n--------------------------------------\n\nCurrently, the only entity type supported by this API is Google+ communities. To retrieve a\nreport of all activities related to app entities in your account, use the following\n`GET` HTTP request and include the authorization token described in the\n[authorization documentation](/workspace/admin/reports/v1/guides/authorizing). For\nreadability, the following example is formatted with line returns: \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date\n?parameters=applicationParameters\n&filters=parameterFilters\n&maxResults=maxResults\n```\n\nThe \u003cvar translate=\"no\"\u003edate\u003c/var\u003e value is the date the usage occurred and the timestamp is in the\n[ISO 8601 format](http://en.wikipedia.org/wiki/ISO_8601), yyyy-mm-dd. We recommend you\nuse your account's time zone for this. For more information about the query string parameters and\nresponse properties, see the [API\nReference](/workspace/admin/reports/v1/reference/entityUsageReports/get). For information about the entities usage report parameters, see the\n[Entities Usage Parameters\nreference](/workspace/admin/reports/v1/reference/usage-ref-appendix-a/entities).\n\n\u003cvar translate=\"no\"\u003eapplicationParameters\u003c/var\u003e is a comma-separated list of parameters you wish to retrieve.\nEach parameter is formatted as `application:parameter_name`, for example,\n`gplus:community_name`. The available parameters are documented in the\n[Entities Usage Parameters\nreference](/workspace/admin/reports/v1/reference/usage-ref-appendix-a/entities). If no parameters are specified, all are returned.\n\n\u003cvar translate=\"no\"\u003eparameterFilters\u003c/var\u003e is a comma-separated list of filters to apply to the results. Each\nfilter is formatted as\n`application:parameter_name[relational_operator]parameter_value`. For example, the\nfilter `gplus:num_total_members\u003e100` filters the results to contain only results\nwhere the `gplus:num_total_members` parameter has a value greater than 100.\n\n\u003cvar translate=\"no\"\u003emaxResults\u003c/var\u003e is the maximum number of results to return in a single fetch. If the total\nnumber of results is greater than this, the response will be truncated and a\n`nextPageToken` will be included (see the\n[JSON response example](#example_response) below).\n\n### Examples\n\nThe following example gets a report containing all parameters\nfor all `gplus_communities` entities. \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all\n/dates/2017-12-11\n```\n\nThe following example gets a report containing the `community_name` parameter\nfor all `gplus_communities` entities. \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all\n/dates/2017-12-11?parameters=gplus:community_name\n```\n\nThe following example gets a report of `community_name` and\n`num_total_members` for each `gplus_communities` entity, filtered by\ncommunities with more than 100 members. For an example of an API response, see the\n[JSON response example](#example_response). \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/2017-12-11\n?parameters=gplus:community_name,gplus:num_total_members&filters=gplus:num_total_members\u003e100\n```\n\nRetrieve a report for a specific entity\n---------------------------------------\n\nTo retrieve a report for a specific entity, use the following `GET` HTTP request and\ninclude the authorization token described in the\n[authorization documentation](/workspace/admin/reports/v1/guides/authorizing). For\nreadability, the following example is formatted with line returns. \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date\n?parameters=applicationParameters\n&filters=parameterFilters\n&maxResults=maxResults\n```\n\nThe \u003cvar translate=\"no\"\u003eentityKey\u003c/var\u003e is an entity identifier which is specific to the application where the\nentity lives. See the [API\nReference](/workspace/admin/reports/v1/reference/userUsageReport/get) for details on how to obtain the \u003cvar translate=\"no\"\u003eentityKey\u003c/var\u003e for the particular entity you\nare interested in. The other parameters are documented above under\n[Retrieve all entities usage activities](#get_all_entities_usage).\n\nFor more information about the query string parameters and response properties, see the [API Reference](/workspace/admin/reports/v1/reference/userUsageReport/get). For information\nabout the entities usage report parameters, see the\n[Entities Usage Parameters\nreference](/workspace/admin/reports/v1/reference/usage-ref-appendix-a/users).\n\n### Examples\n\nThe following example gets the entity report for a `gplus_community` entity with the\n\u003cvar translate=\"no\"\u003eentityKey\u003c/var\u003e \"1234\". \n\n```\nhttps://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11\n```\n\nUsage report example JSON response\n----------------------------------\n\nA successful response returns an [HTTP 200 status code](http://wikipedia.org/wiki/List_of_HTTP_status_codes). Along with\nthe status code, the response returns a report. Some of the parameters in the response have been\nomitted for readability.\n\n#### Example JSON response for entities report\n\n```carbon\n{\n \"kind\": \"reports#usageReports\",\n \"nextPageToken\": \"NjQ1OTgwODk0MzkxNDAwNjQ0OA\",\n \"usageReports\": [\n {\n \"kind\": \"admin#reports#usageReport\",\n \"date\": \"2017-12-11\",\n \"entity\": {\n \"type\": \"OBJECT\",\n \"customerId\": \"C03az79cb\",\n \"objectType\": \"GPLUS_COMMUNITY\",\n \"objectId\": \"1234\",\n },\n \"parameters\": [\n {\n \"name\": \"gplus:community_name\",\n \"stringValue\": \"My Community\"\n },\n {\n \"name\": \"gplus:num_total_members\",\n \"intValue\": 37\n },\n {\n \"name\": \"gplus:num_7day_active_members\",\n \"intValue\": 12\n },\n {\n \"name\": \"gplus:num_30day_active_members\",\n \"intValue\": 17\n },\n ]\n }\n ]\n}\n```\n\n#### Example JSON response for entities report with warnings\n\nOne or more warnings may be returned in the response if the request cannot be fulfilled. In this example, the report is not available at the time the request is made. \n\n```scdoc\n{\n \"kind\": \"reports#usageReports\",\n \"warnings\": [\n {\n \"code\": \"PARTIAL_DATA_AVAILABLE\"\n \"message\": \"Data for date 2017-12-11 for application gplus is not available right now, please try again after a few hours.\"\n \"data\": [\n {\n \"key\": \"date\"\n \"value\": \"2017-12-11\"\n }\n ]\n }\n ],\n \"usageReports\": [],\n}\n```\nEach entry in the `warnings` array has the following parameters:\n\n- `code`: machine-readable warning code\n- `message`: human-readable warning message\n- `data`: list of key-value pairs which give detailed warning information"]]
