API Reports: relatório de uso de entidades

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

O Relatório de uso de entidades pode ser usado apenas para fins legais de acordo com seu Contrato do Cliente. Esses relatórios também se aplicam ao Google Workspace e ao 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 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 legibilidade, o exemplo a seguir é formatado com devoluções 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, 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 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 que contenham 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 número total de resultados for maior que isso, a resposta será truncada e um nextPageToken será incluído. Veja o exemplo de resposta JSON abaixo.

Exemplos

O exemplo a seguir recebe 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 recebe 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 recebe 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 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

GET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults

https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11

{
 "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
    },
   ]
  }
 ]
}

{
 "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": [],
}