O relatório de uso de entidades retorna as atividades do serviço do Google Workspace relacionadas às entidades usadas pelos usuários da sua conta. Esses relatórios podem ser personalizados e filtrados por informações de uso específico. Os dados estão disponíveis para os últimos 30 dias.
O relatório de uso de entidades só pode ser usado para fins legais de acordo com o Contrato de Cliente. Esses relatórios também se aplicam ao Google Workspace e ao Education.
Recuperar todas as atividades de uso de entidades
O único tipo de entidade compatível com essa API são as comunidades do Google+. Para extrair um relatório de todas as atividades relacionadas a entidades de apps na sua conta, use a seguinte solicitação HTTP GET e inclua o token de autorização descrito na documentação de autorização. Para facilitar a leitura, 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 mais informações sobre os parâmetros de string de consulta e 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 Referência de parâmetros de uso de entidades.
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
referência de parâmetros de uso de entidades. Se nenhum parâmetro for especificado, todos serão retornados.
parameterFilters é uma lista de filtros separados por vírgulas a serem aplicados aos resultados. Cada
filtro é formatado como
application:parameter_name[relational_operator]parameter_value. Por exemplo, o filtro gplus:num_total_members>100 restringe os resultados para incluir apenas aqueles 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 número total de resultados for maior, a resposta será truncada e um nextPageToken será incluído. Consulte o exemplo de resposta JSON abaixo.
Exemplos
O exemplo a seguir recebe um relatório com todos os parâmetros de 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 recebe um relatório com 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 recebe um relatório de community_name e num_total_members para cada entidade gplus_communities, filtrado por comunidades com mais de 100 membros. Para ver um exemplo de resposta da API, consulte o
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 extrair um relatório de uma entidade específica, use a seguinte solicitação HTTP GET e inclua o token de autorização descrito na documentação de autorização. Para facilitar a leitura, 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 a entidade está. Consulte a referência da API para saber como conseguir o entityKey da entidade específica em que você tem interesse. Os outros parâmetros estão documentados anteriormente na seção 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 referência de parâmetros de uso de entidades.
Exemplos
O exemplo a seguir recebe o relatório de entidade para 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 do relatório de uso
Uma resposta bem-sucedida retorna um código de status HTTP 200. Além do código de status, a resposta retorna um relatório. Alguns dos parâmetros na resposta foram omitidos para facilitar a leitura.
Exemplo de resposta JSON para um 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 um 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, o relatório não está disponível no momento da solicitação.{
"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 tem os seguintes parâmetros:
code: código de aviso legível por máquinamessage: mensagem de aviso legíveldata: lista de pares de chave-valor que fornecem informações detalhadas sobre o aviso.