API команд | Grafana Labs

Документация

Grafana

Документация GlaberGraph

Ресурсы для разработчиков

API Grafana

Справочное руководство по HTTP API Grafana

Устаревший HTTP API Grafana

API команд

Note
Starting in Grafana 13, /api endpoints are being deprecated in favor of the /apis route. Note that while Grafana is working on migrating existing APIs, currently there may not be an exact match to the legacy API you’re using.

This change doesn’t disrupt or break your current setup. Legacy APIs are not being disabled and remain fully accessible and operative, but /api routes will no longer be updated.

To learn more refer to the new API structure in Grafana.

Этот API можно использовать для управления командами и членством в командах.

Доступ к этим конечным точкам API ограничен следующим образом:

Все аутентифицированные пользователи могут просматривать сведения о командах, в которых они состоят.
Администраторы организации могут управлять всеми командами и участниками команд.

Если вы используете Grafana Enterprise, для некоторых конечных точек потребуются определённые права. Дополнительные сведения см. в разделе Права управления доступом на основе ролей.

Поиск команд с постраничной выдачей

GET /api/teams/search?perpage=50&page=1&query=myteam&sort=memberCount-desc

или

GET /api/teams/search?name=myteam

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
teams:read	teams:*

Пример запроса:

GET /api/teams/search?perpage=10&page=1&query=mytestteam HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Пример ответа:

HTTP/1.1 200
Content-Type: application/json

{
  "totalCount": 1,
  "teams": [
    {
      "id": 1,
      "orgId": 1,
      "name": "MyTestTeam",
      "email": "",
      "avatarUrl": "\/avatar\/3f49c15916554246daa714b9bd0ee398",
      "memberCount": 1
    }
  ],
  "page": 1,
  "perPage": 1000
}

Использование параметра query

Значение по умолчанию для параметра perpage — 1000, а для параметра page — 1.

Поле totalCount в ответе можно использовать для постраничной выдачи списка команд. Например, если totalCount равен 100 командам, а параметр perpage установлен в 10, то имеется 10 страниц команд.

Параметр query необязателен, и он вернёт результаты, в которых значение запроса содержится в поле name. Значения запросов с пробелами нужно кодировать в URL, например query=my%20team.

Параметр sort — необязательный разделённый запятыми список опций для упорядочивания результатов поиска. Допустимые значения для фильтра sort: name-asc, name-desc, email-asc, email-desc, memberCount-asc, memberCount-desc. По умолчанию, если sort не указан, список команд упорядочивается по name в возрастающем порядке.

Использование параметра name

Параметр name возвращает одну команду, если параметр совпадает с полем name.

Коды состояния:

200 — Ok
400 — Некорректный запрос
401 — Не авторизован
403 — В доступе отказано
404 — Команда не найдена (при поиске по имени)

Получение команды по Id

GET /api/teams/:id

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
teams:read	teams:*

Пример запроса:

GET /api/teams/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Пример ответа:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "orgId": 1,
  "name": "MyTestTeam",
  "email": "",
  "created": "2017-12-15T10:40:45+01:00",
  "updated": "2017-12-15T10:40:45+01:00"
}

Коды состояния:

200 — Ok
401 — Не авторизован
403 — В доступе отказано
404 — Команда не найдена

Добавление команды

Имя команды name должно быть уникальным. name обязательно, email необязательно.

POST /api/teams

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
teams:create	Н/Д

Пример запроса:

POST /api/teams HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

{
  "name": "MyTestTeam",
  "email": "email@test.com",
}

Пример ответа:

HTTP/1.1 200
Content-Type: application/json

{"message":"Team created","teamId":2,"uid":"ceaulqadfoav4e"}

Коды состояния:

200 — Ok
401 — Не авторизован
403 — В доступе отказано
409 — Имя команды уже занято

Обновление команды

Для команды можно обновить два поля: name и email.

PUT /api/teams/:id

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
teams:write	teams:*

Пример запроса:

PUT /api/teams/2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

{
  "name": "MyTestTeam",
  "email": "email@test.com"
}

Пример ответа:

HTTP/1.1 200
Content-Type: application/json

{"message":"Team updated"}

Коды состояния:

200 — Ok
401 — Не авторизован
403 — В доступе отказано
404 — Команда не найдена
409 — Имя команды уже занято

Удаление команды по Id

DELETE /api/teams/:id

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
teams:delete	teams:*

Пример запроса:

DELETE /api/teams/2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Пример ответа:

HTTP/1.1 200
Content-Type: application/json

{"message":"Team deleted"}

Коды состояния:

200 — Ok
401 — Не авторизован
403 — В доступе отказано
404 — Не удалось удалить команду. ID не найден

Получение участников команды

GET /api/teams/:teamId/members

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
teams.permissions:read	teams:*

Пример запроса:

GET /api/teams/1/members HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Пример ответа:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "orgId": 1,
    "teamId": 1,
    "userId": 3,
    "email": "user1@example.com",
    "login": "user1",
    "avatarUrl": "\/avatar\/1b3c32f6386b0185c40d359cdc733a79"
  },
  {
    "orgId": 1,
    "teamId": 1,
    "userId": 2,
    "email": "user2@example.com",
    "login": "user2",
    "avatarUrl": "\/avatar\/cad3c68da76e45d10269e8ef02f8e73e"
  }
]

Коды состояния:

200 — Ok
401 — Не авторизован
403 — В доступе отказано

Добавление участника команды

POST /api/teams/:teamId/members

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
teams.permissions:write	teams:*

Пример запроса:

POST /api/teams/1/members HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

{
  "userId": 2
}

Пример ответа:

HTTP/1.1 200
Content-Type: application/json

{"message":"Member added to Team"}

Коды состояния:

200 — Ok
400 — Пользователь уже добавлен в эту команду
401 — Не авторизован
403 — В доступе отказано
404 — Команда не найдена

Удаление участника из команды

DELETE /api/teams/:teamId/members/:userId

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
teams.permissions:write	teams:*

Пример запроса:

DELETE /api/teams/2/members/3 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Пример ответа:

HTTP/1.1 200
Content-Type: application/json

{"message":"Team Member removed"}

Коды состояния:

200 — Ok
401 — Не авторизован
403 — В доступе отказано
404 — Команда не найдена / участник команды не найден

Массовое обновление участников команды

Позволяет массово обновлять участников команды и администраторов, используя электронные адреса пользователей. Перезапишет всех текущих участников и администраторов указанной команды.

`PUT /api/teams/:teamId/members

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
teams.permissions:write	teams:*

Пример запроса:

PUT /api/teams/1/members HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

{
  "members": ["user1@example.com", "user2@example.com"]
  "admins": ["user3@example.com"]
}

Пример ответа:

HTTP/1.1 200
Content-Type: application/json

{"message":"Team memberships have been updated"}

Коды состояния:

200 — Ok
401 — Не авторизован
403 — В доступе отказано
404 — Команда не найдена / участник команды не найден
500 — Внутренняя ошибка

Получение настроек команды

GET /api/teams/:teamId/preferences

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
teams:read	teams:*

Пример запроса:

GET /api/teams/2/preferences HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Пример ответа:

HTTP/1.1 200
Content-Type: application/json

{
  "theme": "",
  "homeDashboardId": 0,
  "homeDashboardUID": "",
  "timezone": ""
}

Обновление настроек команды

PUT /api/teams/:teamId/preferences

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
teams:write	teams:*

Пример запроса:

PUT /api/teams/2/preferences HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

{
  "theme": "dark",
  "homeDashboardId": 39,
  "homeDashboardUID": "jcIIG-07z",
  "timezone": "utc"
}

Схема тела JSON:

theme — одно из: light, dark или пустая строка для темы по умолчанию
homeDashboardId — устарел. Используйте вместо него homeDashboardUID.
homeDashboardUID — :uid дашборда
timezone — одно из: utc, browser или пустая строка для значения по умолчанию

Пропуск ключа приведёт к замене текущего значения на системное значение по умолчанию.

Пример ответа:

HTTP/1.1 200
Content-Type: text/plain; charset=utf-8

{
  "message":"Preferences updated"
}

Была ли эта страница полезна?

Написать на docs@glaber.ru

Справка и поддержка

Сообщество