API Reports: relatório de uso de entidades
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
O relatório de uso de entidades retorna as atividades do serviço do Google Workspace relacionadas às entidades.
pelos usuários da sua conta. Esses relatórios podem ser personalizados e filtrados para uso específico
informações imprecisas ou inadequadas. Os dados disponíveis são referentes aos últimos 30 dias.
O relatório de uso de entidades só pode ser utilizado para fins legais em:
de acordo com o Contrato do Cliente. Esses relatórios também se aplicam a
Google Workspace e Google Workspace for Education.
Recuperar todas as atividades de uso de entidades
Atualmente, o único tipo de entidade compatível com essa API são as comunidades do Google+. Para recuperar um
de todas as atividades relacionadas a entidades de apps em sua conta, use o seguinte
GET e inclua o token de autorização descrito no
documentação de autorização. Para
legibilidade, o exemplo a seguir é formatado com retornos de linha:
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults
O valor date é a data em que o uso ocorreu, e o carimbo de data/hora está no
Formato ISO 8601, aaaa-mm-dd. Recomendamos que você
use o fuso horário da sua conta para isso. Para mais informações sobre os parâmetros de string de consulta e
de resposta, consulte a API
Referência. Para informações sobre os parâmetros do relatório de uso de entidades, consulte a
Parâmetros de uso das entidades
como referência.
applicationParameters é uma lista separada por vírgulas dos parâmetros que você quer recuperar.
Cada parâmetro é formatado como application:parameter_name, por exemplo:
gplus:community_name. Os parâmetros disponíveis estão documentados na
Parâmetros de uso das entidades
como referência. Se nenhum parâmetro for especificado, todos serão retornados.
parameterFilters é uma lista separada por vírgulas de filtros para aplicar aos resultados. Cada
o filtro é formatado como
application:parameter_name[relational_operator]parameter_value: Por exemplo, o
filtro gplus:num_total_members>100 filtra os resultados para conter apenas resultados
em que o parâmetro gplus:num_total_members tem um valor maior que 100.
maxResults é o número máximo de resultados a serem retornados em uma única busca. Se o total
número de resultados for maior do que esse, a resposta será truncada e uma
nextPageToken serão incluídos. Consulte
exemplo de resposta JSON abaixo).
Exemplos
O exemplo a seguir mostra um relatório com todos os parâmetros
para todas as entidades gplus_communities.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11
O exemplo a seguir mostra um relatório que contém o parâmetro community_name.
para todas as entidades gplus_communities.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11?parameters=gplus:community_name
O exemplo a seguir gera um relatório de community_name e
num_total_members para cada entidade gplus_communities, filtrada por
comunidades com mais de cem membros. Para ver um exemplo de resposta da API, consulte a
Exemplo de resposta 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 um relatório de uma entidade específica
Para recuperar o relatório de uma entidade específica, use a seguinte solicitação HTTP GET e
incluir o token de autorização descrito no
documentação de autorização. Para
legibilidade, o exemplo a seguir é formatado com retornos de linha.
GET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults
O entityKey é um identificador de entidade específico do aplicativo em que o
a entidade viva. Consulte a API
Referência para detalhes sobre como conseguir o entityKey para a entidade específica que você
têm interesse. Os outros parâmetros estão documentados acima em
Recuperar todas as atividades de uso de entidades.
Para mais informações sobre os parâmetros de string de consulta e as propriedades de resposta, consulte a Referência da API. Para informações
sobre os parâmetros do relatório de uso de entidades, consulte a
Parâmetros de uso das entidades
como referência.
Exemplos
O exemplo a seguir recebe o relatório de uma entidade gplus_community com o
entityKey, "1234".
https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11
Exemplo de resposta JSON de relatório de uso
Uma resposta bem-sucedida retorna um código de status HTTP 200. Junto com
o código de status, a resposta retorna um relatório. Alguns dos parâmetros na resposta foram
omitido para facilitar a leitura.
Exemplo de resposta JSON para o relatório 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
},
]
}
]
}
Exemplo de resposta JSON para relatório de entidades com avisos
Um ou mais avisos podem ser retornados na resposta se a solicitação não puder ser atendida. Neste
exemplo, ele não está disponível no momento em que a solicitação é feita.
{
"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 na matriz warnings tem os seguintes parâmetros:
code: código de aviso legível por máquina
message: mensagem de aviso legível por humanos
data: lista de pares de chave-valor que fornece informações detalhadas de aviso.
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2025-08-29 UTC.
[null,null,["Última atualização 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"]]
