API организаций

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

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.

HTTP API организаций делится на два ресурса: /api/org (текущая организация) и /api/orgs (администрирование организаций). Одно большое различие между ними в том, что API администрирования всех организаций работает только с basic-аутентификацией; дополнительную информацию см. в разделе API администрирования организаций.

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

Конечные точки текущей организации

Метод	Описание	URI
GET	Получить текущую организацию	/api/org/
GET	Получить всех пользователей текущей организации	/api/org/users
GET	Получить всех пользователей текущей организации (поиск)	/api/org/users/lookup
PATCH	Обновляет указанного пользователя	/api/org/users/:userId
DELETE	Удалить пользователя в текущей организации	/api/org/users/:userId
PUT	Обновить текущую организацию	/api/org
POST	Добавить нового пользователя в текущую организацию	/api/org/users

Конечные точки администрирования организаций

Метод	Описание	URI
GET	Получить организацию по Id	/api/orgs/:orgId
GET	Получить организацию по имени	/api/orgs/name/:orgName
POST	Создать организацию	/api/orgs
GET	Поиск всех организаций	/api/orgs
PUT	Обновить организацию	/api/orgs/:orgId
DELETE	Удалить организацию	/api/orgs/:orgId
GET	Получить пользователей организации	/api/orgs/:orgId/users
POST	Добавить пользователя в организацию	/api/orgs/:orgId/users
PATCH	Обновить пользователей в организации	/api/orgs/:orgId/users/:userId
DELETE	Удалить пользователя в организации	/api/orgs/:orgId/users/:userId

API текущей организации

Получение текущей организации

GET /api/org/

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

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

Действие	Область
orgs:read	Н/Д

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

GET /api/org/ 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,
  "name":"Main Org."
}

Получение всех пользователей текущей организации

GET /api/org/users

Возвращает всех пользователей организации в текущей организации. Доступно пользователям с ролью администратора организации.

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

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

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

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

GET /api/org/users 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,
    "userId": 1,
    "email": "admin@localhost",
    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56",
    "login": "admin",
    "role": "Admin",
    "lastSeenAt": "2019-08-09T11:02:49+02:00",
    "lastSeenAtAge": "< 1m"
  }
]

Получение всех пользователей текущей организации (поиск)

GET /api/org/users/lookup

Возвращает всех пользователей организации в текущей организации, но с менее подробной информацией. Доступно пользователям с ролью администратора организации, администратора любой папки или администратора любой команды. В основном используется интерфейсом Grafana для предоставления списка пользователей при добавлении участников команды и при редактировании прав на папки и дашборды.

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

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

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

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

GET /api/org/users/lookup HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

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

HTTP/1.1 200
Content-Type: application/json

[
  {
    "userId": 1,
    "login": "admin",
    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
  }
]

Обновление указанного пользователя

PATCH /api/org/users/:userId

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

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

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

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

PATCH /api/org/users/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

{
  "role": "Viewer",
}

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

HTTP/1.1 200
Content-Type: application/json

{"message":"Organization user updated"}

Удаление пользователя в текущей организации

DELETE /api/org/users/:userId

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

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

Действие	Область
org.users:remove	users:*

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

DELETE /api/org/users/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

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

HTTP/1.1 200
Content-Type: application/json

{"message":"User removed from organization"}

Обновление текущей организации

PUT /api/org

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

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

Действие	Область
orgs:write	Н/Д

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

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

{
  "name":"Main Org."
}

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

HTTP/1.1 200
Content-Type: application/json

{"message":"Organization updated"}

Добавление нового пользователя в текущую организацию

POST /api/org/users

Добавляет глобального пользователя в текущую организацию.

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

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

Действие	Область
org.users:add	users:*

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

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

{
  "role": "Admin",
  "loginOrEmail": "admin"
}

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

HTTP/1.1 200
Content-Type: application/json

{"message":"User added to organization","userId":1}

API администрирования организаций

Caution
Вы не можете аутентифицироваться в HTTP API администрирования организаций с помощью токенов сервисных учётных записей. Сервисные учётные записи ограничены организацией и ролью в организации. Им нельзя предоставить права администратора сервера Grafana.

Чтобы использовать эти конечные точки API, необходимо применять basic-аутентификацию, и пользователь Grafana должен иметь право администратора сервера Grafana.

Пользователь admin, с которым Grafana создаётся по умолчанию, имеет права на использование этих конечных точек API.

Получение организации по Id

GET /api/orgs/:orgId

Работает только с basic-аутентификацией (имя пользователя и пароль), см. введение.

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

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

Действие	Область
orgs:read	Н/Д

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

GET /api/orgs/1 HTTP/1.1
Accept: application/json
Content-Type: application/json

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

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "name":"Main Org.",
  "address":{
    "address1":"",
    "address2":"",
    "city":"",
    "zipCode":"",
    "state":"",
    "country":""
  }
}

Получение организации по имени

GET /api/orgs/name/:orgName

Работает только с basic-аутентификацией (имя пользователя и пароль), см. введение.

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

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

Действие	Область	Примечание
orgs:read	Н/Д	Должно быть назначено глобально.

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

GET /api/orgs/name/Main%20Org%2E HTTP/1.1
Accept: application/json
Content-Type: application/json

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

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "name":"Main Org.",
  "address":{
    "address1":"",
    "address2":"",
    "city":"",
    "zipCode":"",
    "state":"",
    "country":""
  }
}

Создание организации

POST /api/orgs

Работает только с basic-аутентификацией (имя пользователя и пароль), см. введение.

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

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

Действие	Область	Примечание
orgs:create	Н/Д	Должно быть назначено глобально.

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

POST /api/orgs HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "name":"New Org."
}

Примечание: API будет работать двумя следующими способами

Нужно установить GF_USERS_ALLOW_ORG_CREATE=true
Установить значение конфигурации users.allow_org_create в true в ini-файле

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

HTTP/1.1 200
Content-Type: application/json

{
  "orgId":"1",
  "message":"Organization created"
}

Поиск всех организаций

GET /api/orgs?perpage=10&page=1

Работает только с basic-аутентификацией (имя пользователя и пароль), см. введение.

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

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

Действие	Область	Примечание
orgs:read	Н/Д	Должно быть назначено глобально.

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

GET /api/orgs HTTP/1.1
Accept: application/json
Content-Type: application/json

Примечание: API будет работать только если вы передадите имя и пароль администратора в URL HTTP-запроса, например http://admin:admin@localhost:3000/api/orgs

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

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

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id":1,
    "name":"Main Org."
  }
]

Обновление организации

PUT /api/orgs/:orgId

Обновляет организацию; поля Address 1, Address 2, City пока не реализованы. Работает только с basic-аутентификацией (имя пользователя и пароль), см. введение.

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

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

Действие	Область
orgs:write	Н/Д

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

PUT /api/orgs/1 HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "name":"Main Org 2."
}

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

HTTP/1.1 200
Content-Type: application/json

{"message":"Organization updated"}

Удаление организации

DELETE /api/orgs/:orgId

Работает только с basic-аутентификацией (имя пользователя и пароль), см. введение.

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

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

Действие	Область
orgs:delete	Н/Д

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

DELETE /api/orgs/1 HTTP/1.1
Accept: application/json

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

HTTP/1.1 200
Content-Type: application/json

{"message":"Organization deleted"}

Получение пользователей организации

GET /api/orgs/:orgId/users

Работает только с basic-аутентификацией (имя пользователя и пароль), см. введение.

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

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

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

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

GET /api/orgs/1/users HTTP/1.1
Accept: application/json
Content-Type: application/json

Примечание: API будет работать только если вы передадите имя и пароль администратора в URL HTTP-запроса, например http://admin:admin@localhost:3000/api/orgs/1/users

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

HTTP/1.1 200
Content-Type: application/json
[
  {
    "orgId":1,
    "userId":1,
    "email":"admin@mygraf.com",
    "login":"admin",
    "role":"Admin"
  }
]

Добавление пользователя в организацию

POST /api/orgs/:orgId/users

Работает только с basic-аутентификацией (имя пользователя и пароль), см. введение.

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

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

Действие	Область
org.users:add	users:*

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

POST /api/orgs/1/users HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "loginOrEmail":"user",
  "role":"Viewer"
}

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

HTTP/1.1 200
Content-Type: application/json

{"message":"User added to organization", "userId": 1}

Обновление пользователей в организации

PATCH /api/orgs/:orgId/users/:userId

Работает только с basic-аутентификацией (имя пользователя и пароль), см. введение.

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

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

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

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

PATCH /api/orgs/1/users/2 HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "role":"Admin"
}

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

HTTP/1.1 200
Content-Type: application/json

{"message":"Organization user updated"}

Удаление пользователя в организации

DELETE /api/orgs/:orgId/users/:userId

Работает только с basic-аутентификацией (имя пользователя и пароль), см. введение.

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

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

Действие	Область
org.users:remove	users:*

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

DELETE /api/orgs/1/users/2 HTTP/1.1
Accept: application/json
Content-Type: application/json

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

HTTP/1.1 200
Content-Type: application/json

{"message":"User removed from organization"}

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

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

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

Сообщество