广播消息 API
-
target_access_levels引入于 14.8 版本，通过名为role_targeted_broadcast_messages的功能标志 来控制。默认关闭。 -
color参数移除于 15.6 版本。
广播消息 API 工作在广播消息功能之上。
在 12.8 版本中，对于 GET 请求不再需要任何授权操作。所有的广播消息 API 都只能被管理员访问，对于其他类型的请求来说：
- 访客的请求会得到
401 Unauthorized。 - 普通的用户会得到
403 Forbidden。
获取所有的广播消息
列举出所有的广播消息。
GET /broadcast_messages
请求示例：
curl "https://gitlab.example.com/api/v4/broadcast_messages"
响应示例：
[
{
"message":"Example broadcast message",
"starts_at":"2016-08-24T23:21:16.078Z",
"ends_at":"2016-08-26T23:21:16.080Z",
"font":"#FFFFFF",
"id":1,
"active": false,
"target_access_levels": [10,30],
"target_path": "*/welcome",
"broadcast_type": "banner",
"dismissable": false
}
]
获取特定广播消息
获取特定广播消息。
GET /broadcast_messages/:id
参数：
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
id
| integer | yes | 需要获取的广播消息的 ID。 |
请求示例：
curl "https://gitlab.example.com/api/v4/broadcast_messages/1"
响应示例：
{
"message":"Deploy in progress",
"starts_at":"2016-08-24T23:21:16.078Z",
"ends_at":"2016-08-26T23:21:16.080Z",
"font":"#FFFFFF",
"id":1,
"active":false,
"target_access_levels": [10,30],
"target_path": "*/welcome",
"broadcast_type": "banner",
"dismissable": false
}
创建广播消息
创建新的广播消息。
POST /broadcast_messages
参数：
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
message
| string | yes | 要展示的消息。 |
starts_at
| datetime | no | 开始时间（默认为当前 UTC 时间）。日期格式应当为 ISO 8601（如：2019-03-15T08:00:00Z）。
|
ends_at
| datetime | no | 结束时间（默认为当前 UTC 时间）。日期格式应当为 ISO 8601（如：2019-03-15T08:00:00Z）。
|
font
| string | no | 16 进制的前景颜色值。 |
target_access_levels
| array of integers | no | 广播消息的目标的访问权限（角色）。 |
target_path
| string | no | 广播消息的目标路径。 |
broadcast_type
| string | no | 广播的外观类型（默认为横幅）。 |
dismissable
| boolean | no | 是否可以手动关闭广播消息。 |
target_access_levels 在 Gitlab::Access 模块中定义。可以有以下几种权限（角色）：
- Guest (
10) - Reporter (
20) - Developer (
30) - Maintainer (
40) - Owner (
50)
请求示例：
curl --data "message=Deploy in progress&target_access_levels[]=10&target_access_levels[]=30" \
--header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/broadcast_messages"
响应示例：
{
"message":"Deploy in progress",
"starts_at":"2016-08-26T00:41:35.060Z",
"ends_at":"2016-08-26T01:41:35.060Z",
"font":"#FFFFFF",
"id":1,
"active": true,
"target_access_levels": [10,30],
"target_path": "*/welcome",
"broadcast_type": "notification",
"dismissable": false
}
更新广播消息
更新现存的广播消息。
PUT /broadcast_messages/:id
参数：
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
id
| integer | yes | 需要修改的广播消息的 ID。 |
message
| string | no | 想要展示的消息内容。 |
starts_at
| datetime | no | 开始时间（UTC）。日期格式应当为 ISO 8601（如：2019-03-15T08:00:00Z）。
|
ends_at
| datetime | no | 结束时间（UTC）。日期格式应当为 ISO 8601（如：2019-03-15T08:00:00Z）。
|
font
| string | no | 16 进制的前景颜色值。 |
target_access_levels
| array of integers | no | 广播消息的目标的访问权限（角色）。 |
target_path
| string | no | 广播消息的目标路径。 |
broadcast_type
| string | no | 广播的外观类型（默认为横幅）。 |
dismissable
| boolean | no | 是否可以手动关闭广播消息。 |
target_access_levels 在 Gitlab::Access 模块中定义。可以有以下几种权限（角色）：
- Guest (
10) - Reporter (
20) - Developer (
30) - Maintainer (
40) - Owner (
50)
请求示例：
curl --request PUT --data "message=Update message" \
--header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/broadcast_messages/1"
响应示例：
{
"message":"Update message",
"starts_at":"2016-08-26T00:41:35.060Z",
"ends_at":"2016-08-26T01:41:35.060Z",
"font":"#FFFFFF",
"id":1,
"active": true,
"target_access_levels": [10,30],
"target_path": "*/welcome",
"broadcast_type": "notification",
"dismissable": false
}
删除一条广播消息
删除一条广播消息。
DELETE /broadcast_messages/:id
参数：
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
id
| integer | yes | 想要删除的广播消息的 ID。 |
请求示例：
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/broadcast_messages/1"