广播消息 API

Tier: 基础版, 专业版, 旗舰版
Offering: 私有化部署

History

target_access_levels 引入于极狐GitLab 14.8，使用名为 role_targeted_broadcast_messages 的功能标志。默认禁用。
color 参数在极狐GitLab 15.6 中被移除。
theme 引入于极狐GitLab 17.6。

使用此 API 与 UI 中显示的横幅和通知进行交互。有关更多信息，请参阅广播消息。

GET 请求不需要身份验证。所有其他广播消息 API 端点仅对 管理员 可访问。非 GET 请求由：

访客导致 401 Unauthorized。
普通用户 导致 403 Forbidden。

获取所有广播消息#

Tier: 基础版, 专业版, 旗舰版
Offering: JihuLab.com, 私有化部署

列出所有广播消息。

plaintext
GET /broadcast_messages

示例请求：

shell
curl "https://gitlab.example.com/api/v4/broadcast_messages"

示例响应：

json
1[
2    {
3        "message":"Example broadcast message",
4        "starts_at":"2016-08-24T23:21:16.078Z",
5        "ends_at":"2016-08-26T23:21:16.080Z",
6        "font":"#FFFFFF",
7        "id":1,
8        "active": false,
9        "target_access_levels": [10,30],
10        "target_path": "*/welcome",
11        "broadcast_type": "banner",
12        "dismissable": false,
13        "theme": "indigo"
14    }
15]

获取特定的广播消息#

Tier: 基础版, 专业版, 旗舰版
Offering: JihuLab.com, 私有化部署

获取特定的广播消息。

plaintext
GET /broadcast_messages/:id

参数：

属性	类型	必需	描述
id	integer	是	要检索的广播消息的 ID。

示例请求：

shell
curl "https://gitlab.example.com/api/v4/broadcast_messages/1"

示例响应：

json
1{
2    "message":"Deploy in progress",
3    "starts_at":"2016-08-24T23:21:16.078Z",
4    "ends_at":"2016-08-26T23:21:16.080Z",
5    "font":"#FFFFFF",
6    "id":1,
7    "active":false,
8    "target_access_levels": [10,30],
9    "target_path": "*/welcome",
10    "broadcast_type": "banner",
11    "dismissable": false,
12    "theme": "indigo"
13}

创建广播消息#

创建新的广播消息。

plaintext
POST /broadcast_messages

参数：

属性	类型	必需	描述
message	string	是	要显示的消息。
starts_at	datetime	否	开始时间（默认为当前 UTC 时间）。需要 ISO 8601 格式 (2019-03-15T08:00:00Z)
ends_at	datetime	否	结束时间（默认为当前时间起一小时）。需要 ISO 8601 格式 (2019-03-15T08:00:00Z)
font	string	否	前景颜色的十六进制代码。
target_access_levels	array of integers	否	广播消息的目标访问级别（角色）。
target_path	string	否	广播消息的目标路径。
broadcast_type	string	否	显示类型（默认为横幅）。
dismissable	boolean	否	用户是否可以关闭消息？
theme	string	否	广播消息的颜色主题（仅横幅）。

target_access_levels 在 Gitlab::Access 模块中定义。有效的级别有：

访客 (10)
策划者 (15)
报告者 (20)
开发者 (30)
维护者 (40)
所有者 (50)

theme 选项在 System::BroadcastMessage 类中定义。有效的主题有：

indigo (默认)
light-indigo
blue
light-blue
green
light-green
red
light-red
dark
light

示例请求：

shell
curl --data "message=Deploy in progress&target_access_levels[]=10&target_access_levels[]=30&theme=red" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/broadcast_messages"

示例响应：

json
1{
2    "message":"Deploy in progress",
3    "starts_at":"2016-08-26T00:41:35.060Z",
4    "ends_at":"2016-08-26T01:41:35.060Z",
5    "font":"#FFFFFF",
6    "id":1,
7    "active": true,
8    "target_access_levels": [10,30],
9    "target_path": "*/welcome",
10    "broadcast_type": "notification",
11    "dismissable": false,
12    "theme": "red"
13}

更新广播消息#

更新现有的广播消息。

plaintext
PUT /broadcast_messages/:id

参数：

属性	类型	必需	描述
id	integer	是	要更新的广播消息的 ID。
message	string	否	要显示的消息。
starts_at	datetime	否	开始时间（UTC）。需要 ISO 8601 格式 (2019-03-15T08:00:00Z)
ends_at	datetime	否	结束时间（UTC）。需要 ISO 8601 格式 (2019-03-15T08:00:00Z)
font	string	否	前景颜色的十六进制代码。
target_access_levels	array of integers	否	广播消息的目标访问级别（角色）。
target_path	string	否	广播消息的目标路径。
broadcast_type	string	否	显示类型（默认为横幅）。
dismissable	boolean	否	用户是否可以关闭消息？
theme	string	否	广播消息的颜色主题（仅横幅）。

target_access_levels 在 Gitlab::Access 模块中定义。有效的级别有：

访客 (10)
策划者 (15)
报告者 (20)
开发者 (30)
维护者 (40)
所有者 (50)

theme 选项在 System::BroadcastMessage 类中定义。有效的主题有：

indigo (默认)
light-indigo
blue
light-blue
green
light-green
red
light-red
dark
light

示例请求：

shell
curl --request PUT --data "message=Update message" \
     --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/broadcast_messages/1"

示例响应：

json
1{
2    "message":"Update message",
3    "starts_at":"2016-08-26T00:41:35.060Z",
4    "ends_at":"2016-08-26T01:41:35.060Z",
5    "font":"#FFFFFF",
6    "id":1,
7    "active": true,
8    "target_access_levels": [10,30],
9    "target_path": "*/welcome",
10    "broadcast_type": "notification",
11    "dismissable": false,
12    "theme": "indigo"
13}

删除广播消息#

删除广播消息。

plaintext
DELETE /broadcast_messages/:id

参数：

属性	类型	必需	描述
id	integer	是	要删除的广播消息的 ID。

示例请求：

shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/broadcast_messages/1"