Reports API：實體使用情形報表
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
實體使用情形報告會傳回與實體相關的 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。可用的參數會記錄在
實體使用參數
參考資料。如未指定參數，系統會傳回所有參數。
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 和
各 gplus_communities 實體的 num_total_members，篩選條件為
會員人數超過 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 是應用程式專屬的實體 ID，
實體的生命體。請參閱 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：提供詳細警告資訊的鍵/值組合清單
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 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"]]
