API отчетов: отчет об использовании объектов

В отчете об использовании объектов отображаются действия службы Google Workspace, связанные с объектами, используемыми пользователями вашего аккаунта. Эти отчеты можно настраивать и фильтровать по конкретной информации об использовании. Данные доступны за последние 30 дней.

Отчет об использовании объектов может использоваться только в законных целях в соответствии с вашим Клиентским соглашением. Эти отчеты также применимы к Google Workspace и Google Education.

Получить все действия по использованию сущностей

В настоящее время единственным типом объектов, поддерживаемым этим API, являются сообщества Google+. Чтобы получить отчет обо всех действиях, связанных с сущностями приложения в вашей учетной записи, используйте следующий HTTP-запрос GET и включите токен авторизации, описанный в документации по авторизации . Для удобства чтения следующий пример отформатирован с возвратом строк:

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

Значением date является дата, когда произошло использование, а отметка времени имеет формат ISO 8601 , гггг-мм-дд. Мы рекомендуем вам использовать для этого часовой пояс вашей учетной записи. Дополнительные сведения о параметрах строки запроса и свойствах ответа см. в справочнике по API . Информацию о параметрах отчета об использовании сущностей см. в справочнике Параметры использования сущностей .

applicationParameters — это список параметров, разделенных запятыми, которые вы хотите получить. Каждый параметр имеет формат application:parameter_name , например gplus:community_name . Доступные параметры описаны в справочнике по параметрам использования Entities . Если параметры не указаны, возвращаются все.

parameterFilters — это список фильтров, разделенных запятыми, которые можно применить к результатам. Каждый фильтр имеет формат application:parameter_name[relational_operator]parameter_value . Например, фильтр gplus:num_total_members>100 фильтрует результаты, чтобы они содержали только результаты, в которых параметр gplus:num_total_members имеет значение больше 100.

maxResults — максимальное количество результатов, возвращаемых за одну выборку. Если общее количество результатов превышает это значение, ответ будет усечен и будет включен nextPageToken (см. пример ответа JSON ниже).

Примеры

В следующем примере создается отчет, содержащий все параметры для всех объектов gplus_communities .

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

В следующем примере возвращается отчет, содержащий параметр community_name для всех объектов gplus_communities .

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11?parameters=gplus:community_name

В следующем примере возвращается отчет community_name и num_total_members для каждого объекта gplus_communities , отфильтрованный по сообществам с более чем 100 участниками. Пример ответа API см. в примере ответа 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

Получить отчет для конкретной сущности

Чтобы получить отчет для определенной сущности, используйте следующий HTTP-запрос GET и включите токен авторизации, описанный в документации по авторизации . Для удобства чтения следующий пример отформатирован с возвратом строк.

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

entityKey — это идентификатор сущности, специфичный для приложения, в котором находится сущность. Подробную информацию о том, как получить entityKey для конкретной интересующей вас сущности, см. в справочнике по API. Остальные параметры описаны выше в разделе «Получение всех действий по использованию сущностей» .

Дополнительные сведения о параметрах строки запроса и свойствах ответа см. в справочнике по API . Информацию о параметрах отчета об использовании сущностей см. в справочнике Параметры использования сущностей .

Примеры

В следующем примере возвращается отчет о сущности для сущности gplus_community с entityKey «1234».

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

Пример отчета об использовании, ответ JSON

Успешный ответ возвращает код состояния HTTP 200 . Вместе с кодом состояния ответ возвращает отчет. Некоторые параметры в ответе опущены для удобства чтения.

Пример ответа JSON для отчета об объектах

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

Пример ответа JSON для отчета об объектах с предупреждениями

В ответе может быть возвращено одно или несколько предупреждений, если запрос не может быть выполнен. В этом примере отчет недоступен на момент выполнения запроса.
{
 "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 имеет следующие параметры:
  • code : машиночитаемый код предупреждения.
  • message : удобочитаемое предупреждающее сообщение.
  • data : список пар ключ-значение, которые предоставляют подробную предупреждающую информацию.