API de informes: Informe de uso de entidades
Organiza tus páginas con colecciones
Guarda y categoriza el contenido según tus preferencias.
El informe de uso de entidades muestra las actividades de servicio de Google Workspace relacionadas con las entidades
que usan los usuarios de tu cuenta. Estos informes se pueden personalizar y filtrar para usos específicos
información. Hay datos disponibles de los últimos 30 días.
El informe de uso de entidades solo se puede utilizar con fines legales en
conforme a su Acuerdo del Cliente. Estos informes también se aplican
Google Workspace y Education.
Recuperar todas las actividades de uso de las entidades
Actualmente, el único tipo de entidad compatible con esta API son las comunidades de Google+. Para recuperar un
informe de todas las actividades relacionadas con las entidades de aplicaciones de tu cuenta, utiliza el siguiente
solicitud HTTP GET e incluye el token de autorización descrito en el
documentación de autorización. Para
para mayor legibilidad, el siguiente ejemplo tiene un formato con retornos de línea:
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults
El valor date es la fecha en que ocurrió el uso y la marca de tiempo se encuentra en el
Formato ISO 8601, aaaa-mm-dd. Te recomendamos
utilice la zona horaria de su cuenta para este fin. Para obtener más información sobre los parámetros de la cadena de consulta y
propiedades de respuesta, consulta la API
Referencia. Para obtener información acerca de los parámetros del informe de uso de entidades, consulta la
Parámetros de uso de entidades
referencia.
applicationParameters es una lista de parámetros separados por comas que deseas recuperar.
Cada parámetro tiene el formato de application:parameter_name, por ejemplo:
gplus:community_name Los parámetros disponibles se documentan en el
Parámetros de uso de entidades
referencia. Si no se especifican parámetros, se mostrarán todos.
parameterFilters es una lista de filtros separados por comas que se aplicarán a los resultados. Cada
el filtro tiene el formato
application:parameter_name[relational_operator]parameter_value Por ejemplo, el
filtrar gplus:num_total_members>100 filtra los resultados para que solo contengan resultados
en el que el parámetro gplus:num_total_members tiene un valor superior a 100.
maxResults es la cantidad máxima de resultados que se muestran en una sola recuperación. Si el total
de resultados es mayor que este, la respuesta se truncará y se
Se incluirán nextPageToken (consulta la
ejemplo de respuesta JSON a continuación).
Ejemplos
En el siguiente ejemplo, se obtiene un informe que contiene todos los parámetros
para todas las entidades gplus_communities.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11
En el siguiente ejemplo, se obtiene un informe que contiene el parámetro community_name
para todas las entidades gplus_communities.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11?parameters=gplus:community_name
En el siguiente ejemplo, se obtiene un informe de community_name y
num_total_members para cada entidad gplus_communities, filtrado por
comunidades con más de 100 miembros. Para ver un ejemplo de respuesta de la API, consulta la
Ejemplo de respuesta 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
Recuperar un informe de una entidad específica
Para recuperar un informe de una entidad específica, usa la siguiente solicitud HTTP GET y
incluir el token de autorización descrito en el
documentación de autorización. Para
para mayor legibilidad, el siguiente ejemplo tiene un formato con retornos de línea.
GET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults
El entityKey es un identificador de entidad específico de la aplicación en la que
la entidad. Consulta la página
Consulta este artículo de referencia para saber cómo obtener el entityKey de la entidad en particular que
les interesan. Los otros parámetros están documentados anteriormente en
Recupera todas las actividades de uso de las entidades.
Para obtener más información sobre los parámetros de la cadena de consulta y las propiedades de la respuesta, consulta la Referencia de la API. Información
acerca de los parámetros del informe de uso de entidades, consulta el
Parámetros de uso de entidades
referencia.
Ejemplos
En el siguiente ejemplo, se obtiene el informe de entidad de una entidad gplus_community con el
entityKey “1234”:
https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11
Ejemplo de respuesta JSON de informe de uso
Si la respuesta es correcta, se mostrará un código de estado HTTP 200. Junto con
el código de estado, la respuesta devuelve un informe. Algunos de los parámetros de la respuesta se han
omitida para facilitar la lectura.
Ejemplo de respuesta JSON para el informe de entidades
{
"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
},
]
}
]
}
Ejemplo de respuesta JSON para el informe de entidades con advertencias
Se pueden mostrar una o más advertencias en la respuesta si la solicitud no se puede llevar a cabo. En este
Por ejemplo, la denuncia no está disponible en el momento en que se realiza la solicitud.
{
"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": [],
}
Cada entrada del array warnings tiene los siguientes parámetros:
.
code: Código de advertencia legible por máquina
message: mensaje de advertencia legible por humanos
data: Es la lista de pares clave-valor que proporcionan información de advertencia detallada.
Salvo que se indique lo contrario, el contenido de esta página está sujeto a la licencia Atribución 4.0 de Creative Commons, y los ejemplos de código están sujetos a la licencia Apache 2.0. Para obtener más información, consulta las políticas del sitio de Google Developers. Java es una marca registrada de Oracle o sus afiliados.
Última actualización: 2025-08-29 (UTC)
[null,null,["Última actualización: 2025-08-29 (UTC)"],[],[],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"]]
