Reports 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 . Доступные параметры описаны в справочнике по параметрам использования объектов . Если параметры не указаны, возвращаются все.

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

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