API Reports: relatório de uso de entidades

O relatório de uso de entidades retorna atividades do serviço do Google Workspace relacionadas às entidades usadas pelos usuários da conta. Esses relatórios podem ser personalizados e filtrados para fornecer informações de uso específicas. Os dados disponíveis são referentes aos últimos 30 dias.

O relatório de uso de entidades pode ser utilizado apenas para fins legais, de acordo com o Contrato do Cliente. Esses relatórios também são válidos para o Google Workspace e o Google Workspace for Education.

Recuperar todas as atividades de uso das entidades

Atualmente, o único tipo de entidade compatível com essa API são as comunidades do Google+. Para recuperar 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 isso. Para mais informações sobre os parâmetros da string de consulta e as propriedades de resposta, confira 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 de 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 separada por vírgulas de filtros para aplicar aos resultados. Cada 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 tenha 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 que esse, a resposta será truncada e um nextPageToken será incluído. Consulte o exemplo de resposta JSON abaixo.

Exemplos

O exemplo a seguir exibe um relatório que contém 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 exibe 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 exibe 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 de 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 recuperar 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 para o aplicativo em que a entidade reside. Consulte a Referência da API para detalhes sobre como conseguir o entityKey da entidade específica em que você tem 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 da string de consulta e as propriedades de resposta, confira a Referência da API. Para mais 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 acessa 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 do relatório de uso

Se a resposta for bem-sucedida, o código de status HTTP 200 será retornado. Com o 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 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 o relatório de entidades com avisos

Um ou mais avisos poderão ser retornados na resposta se a solicitação não puder ser atendida. Nesse exemplo, o relatório 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
  • data: lista de pares de chave-valor que fornecem informações detalhadas de aviso.