Reports API：实体使用情况报告

实体用量报告会返回与账号用户使用的实体相关的 Google Workspace 服务活动。您可以自定义和过滤这些报告，以获取特定的使用情况信息。系统会提供过去 30 天的数据。

实体用量报告只能根据您的客户协议用于合法用途。这些报告也适用于 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 实体的实体报告。entityKey

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：键值对列表，其中包含详细的警告信息

Reports API：实体使用情况报告 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。