实体使用情况报告会返回与您的帐号用户使用的实体相关的 Google Workspace 服务活动。您可以针对特定使用情况信息自定义和过滤这些报告。您可以查看过去 30 天的数据。
根据《客户协议》,实体使用情况报告只能用于合法目的。这些报告也适用于 Google Workspace 和 Google Workspace 教育版。
检索所有实体使用活动
目前,此 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
以下示例获取一个包含所有 gplus_communities
实体的 community_name
参数的报告。
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all /dates/2017-12-11?parameters=gplus:community_name
以下示例会获取每个 gplus_communities
实体的 community_name
和 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 是实体所在应用特有的实体标识符。如需详细了解如何获取您感兴趣的特定实体的 entityKey,请参阅 API 参考。其他参数记录在上文的 检索所有实体使用活动下。
如需详细了解查询字符串参数和响应属性,请参阅 API 参考。如需了解实体使用情况报告参数,请参阅实体使用情况参数参考文档。
示例
以下示例获取 entityKey 为“1234”的 gplus_community
实体的实体报告。
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
:提供详细警告信息的键值对列表