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áquinamessage: mensagem de aviso legível por humanosdata: lista de pares de chave-valor que fornece informações detalhadas de aviso.