菜单
企业版 开源

团队 API

此 API 可用于管理团队和团队成员资格。

这些 API 端点的访问权限限制如下

  • 所有已认证用户都可以查看其所属团队的详细信息。
  • 组织管理员能够管理所有团队和团队成员。

如果您正在运行 Grafana Enterprise,对于某些端点,您需要具有特定的权限。请参阅基于角色的访问控制权限了解更多信息。

带分页的团队搜索

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

GET /api/teams/search?name=myteam

所需权限

请参阅引言中的说明。

操作Scope
teams:readteams:*

请求示例:

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

响应示例:

http
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` 字段中包含 query 值的结果。包含空格的 query 值需要进行 URL 编码,例如 `query=my%20team`。

`sort` 参数是一个可选的逗号分隔列表,用于对搜索结果进行排序。sort 过滤器的接受值有:`name-asc`、`name-desc`、`email-asc`、`email-desc`、`memberCount-asc`、`memberCount-desc`。默认情况下,如果未指定 `sort`,则团队列表将按 `name` 升序排列。

使用 name 参数

`name` 参数在匹配 `name` 字段时返回单个团队。

状态码

  • 200 - 正常
  • 400 - 错误请求
  • 401 - 未授权
  • 403 - 权限拒绝
  • 404 - 未找到团队(如果按名称搜索)

按 ID 获取团队

GET /api/teams/:id

所需权限

请参阅引言中的说明。

操作Scope
teams:readteams:*

请求示例:

http
GET /api/teams/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt

响应示例:

http
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 - 正常
  • 401 - 未授权
  • 403 - 权限拒绝
  • 404 - 未找到团队

添加团队

团队的 `name` 需要是唯一的。`name` 是必需的,而 `email` 是可选的。

POST /api/teams

所需权限

请参阅引言中的说明。

操作Scope
teams:create不适用

请求示例:

http
POST /api/teams HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt

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

响应示例:

http
HTTP/1.1 200
Content-Type: application/json

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

状态码

  • 200 - 正常
  • 401 - 未授权
  • 403 - 权限拒绝
  • 409 - 团队名称已被占用

更新团队

团队有两个可更新的字段:`name` 和 `email`。

PUT /api/teams/:id

所需权限

请参阅引言中的说明。

操作Scope
teams:writeteams:*

请求示例:

http
PUT /api/teams/2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt

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

响应示例:

http
HTTP/1.1 200
Content-Type: application/json

{"message":"Team updated"}

状态码

  • 200 - 正常
  • 401 - 未授权
  • 403 - 权限拒绝
  • 404 - 未找到团队
  • 409 - 团队名称已被占用

按 ID 删除团队

DELETE /api/teams/:id

所需权限

请参阅引言中的说明。

操作Scope
teams:deleteteams:*

请求示例:

http
DELETE /api/teams/2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt

响应示例:

http
HTTP/1.1 200
Content-Type: application/json

{"message":"Team deleted"}

状态码

  • 200 - 正常
  • 401 - 未授权
  • 403 - 权限拒绝
  • 404 - 删除团队失败。未找到 ID

获取团队成员

GET /api/teams/:teamId/members

所需权限

请参阅引言中的说明。

操作Scope
teams.permissions:readteams:*

请求示例:

http
GET /api/teams/1/members HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt

响应示例:

http
HTTP/1.1 200
Content-Type: application/json

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

状态码

  • 200 - 正常
  • 401 - 未授权
  • 403 - 权限拒绝

添加团队成员

POST /api/teams/:teamId/members

所需权限

请参阅引言中的说明。

操作Scope
teams.permissions:writeteams:*

请求示例:

http
POST /api/teams/1/members HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt

{
  "userId": 2
}

响应示例:

http
HTTP/1.1 200
Content-Type: application/json

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

状态码

  • 200 - 正常
  • 400 - 用户已添加到此团队
  • 401 - 未授权
  • 403 - 权限拒绝
  • 404 - 未找到团队

从团队中移除成员

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

所需权限

请参阅引言中的说明。

操作Scope
teams.permissions:writeteams:*

请求示例:

http
DELETE /api/teams/2/members/3 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt

响应示例:

http
HTTP/1.1 200
Content-Type: application/json

{"message":"Team Member removed"}

状态码

  • 200 - 正常
  • 401 - 未授权
  • 403 - 权限拒绝
  • 404 - 未找到团队/未找到团队成员

批量更新团队成员

允许使用用户电子邮件批量更新团队成员和管理员。将覆盖指定团队的所有当前成员和管理员。

`PUT /api/teams/:teamId/members

所需权限

请参阅引言中的说明。

操作Scope
teams.permissions:writeteams:*

请求示例:

http
PUT /api/teams/1/members HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt

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

响应示例:

http
HTTP/1.1 200
Content-Type: application/json

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

状态码

  • 200 - 正常
  • 401 - 未授权
  • 403 - 权限拒绝
  • 404 - 未找到团队/未找到团队成员
  • 500 - 内部错误

获取团队偏好设置

GET /api/teams/:teamId/preferences

所需权限

请参阅引言中的说明。

操作Scope
teams:readteams:*

请求示例:

http
GET /api/teams/2/preferences HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

http
HTTP/1.1 200
Content-Type: application/json

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

更新团队偏好设置

PUT /api/teams/:teamId/preferences

所需权限

请参阅引言中的说明。

操作Scope
teams:writeteams:*

请求示例:

http
PUT /api/teams/2/preferences HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "theme": "dark",
  "homeDashboardId": 39,
  "timezone": "utc"
}

JSON 请求体 Schema

  • theme - 以下之一:`light`、`dark`,或空字符串表示默认主题
  • homeDashboardId - 仪表盘的数字 `:id`,默认值:`0`
  • timezone - 以下之一:`utc`、`browser`,或空字符串表示默认值

省略某个键将导致当前值被系统默认值替换。

响应示例:

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

{
  "message":"Preferences updated"
}