广播消息 API

target_access_levels 引入于 14.8 版本，通过名为 role_targeted_broadcast_messages 的功能标志来控制。默认关闭。

广播消息 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",
        "color":"#E75E40",
        "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",
    "color":"#cecece",
    "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`）。
`color`	string	no	16 进制的背景颜色值。
`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&color=#cecece&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",
    "color":"#cecece",
    "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`）。
`color`	string	no	16 进制的背景颜色值。
`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&color=#000" \
     --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",
    "color":"#000",
    "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"