团队 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:read | teams:* |
请求示例:
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/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:read | teams:* |
请求示例:
GET /api/teams/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
响应示例:
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 | 不适用 |
请求示例:
POST /api/teams HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
{
"name": "MyTestTeam",
"email": "email@test.com",
}
响应示例:
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:write | teams:* |
请求示例:
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/1.1 200
Content-Type: application/json
{"message":"Team updated"}
状态码
- 200 - 正常
- 401 - 未授权
- 403 - 权限拒绝
- 404 - 未找到团队
- 409 - 团队名称已被占用
按 ID 删除团队
DELETE /api/teams/:id
所需权限
请参阅引言中的说明。
操作 | Scope |
---|---|
teams:delete | teams:* |
请求示例:
DELETE /api/teams/2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
响应示例:
HTTP/1.1 200
Content-Type: application/json
{"message":"Team deleted"}
状态码
- 200 - 正常
- 401 - 未授权
- 403 - 权限拒绝
- 404 - 删除团队失败。未找到 ID
获取团队成员
GET /api/teams/:teamId/members
所需权限
请参阅引言中的说明。
操作 | Scope |
---|---|
teams.permissions:read | teams:* |
请求示例:
GET /api/teams/1/members HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
响应示例:
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:write | teams:* |
请求示例:
POST /api/teams/1/members HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
{
"userId": 2
}
响应示例:
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:write | teams:* |
请求示例:
DELETE /api/teams/2/members/3 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
响应示例:
HTTP/1.1 200
Content-Type: application/json
{"message":"Team Member removed"}
状态码
- 200 - 正常
- 401 - 未授权
- 403 - 权限拒绝
- 404 - 未找到团队/未找到团队成员
批量更新团队成员
允许使用用户电子邮件批量更新团队成员和管理员。将覆盖指定团队的所有当前成员和管理员。
`PUT /api/teams/:teamId/members
所需权限
请参阅引言中的说明。
操作 | Scope |
---|---|
teams.permissions:write | teams:* |
请求示例:
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/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:read | teams:* |
请求示例:
GET /api/teams/2/preferences HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
响应示例:
HTTP/1.1 200
Content-Type: application/json
{
"theme": "",
"homeDashboardId": 0,
"timezone": ""
}
更新团队偏好设置
PUT /api/teams/:teamId/preferences
所需权限
请参阅引言中的说明。
操作 | Scope |
---|---|
teams:write | teams:* |
请求示例:
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/1.1 200
Content-Type: text/plain; charset=utf-8
{
"message":"Preferences updated"
}