Help us learn about your current experience with the documentation. Take the survey.

广播消息 API

  • 层级：免费、高级、旗舰
  • 提供方式：GitLab 自托管、GitLab 专属

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

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

  • 访客会收到 401 Unauthorized。
  • 普通用户会收到 403 Forbidden。

获取所有广播消息

  • 层级：免费、高级、旗舰
  • 提供方式：GitLab.com、GitLab 自托管、GitLab 专属

列出所有广播消息。

GET /broadcast_messages

示例请求：

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

示例响应：

[
    {
        "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,
        "theme": "indigo"
    }
]

获取特定广播消息

  • 层级：免费、高级、旗舰
  • 提供方式：GitLab.com、GitLab 自托管、GitLab 专属

获取特定广播消息。

GET /broadcast_messages/:id

参数：

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

示例请求：

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

示例响应：

{
    "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,
    "theme": "indigo"
}

创建广播消息

无论目标设置如何，广播消息都通过 API 公开可访问。不要包含敏感或机密信息，也不要使用广播消息向特定组或项目传达私人信息。

创建新的广播消息。

POST /broadcast_messages

参数：

属性 类型 必需 描述
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 模块中定义。以下级别有效：

  • Guest (10) - 访客
  • Planner (15) - 计划者
  • Reporter (20) - 报告者
  • Developer (30) - 开发者
  • Maintainer (40) - 维护者
  • Owner (50) - 所有者

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

  • indigo (默认) - 靛蓝色
  • light-indigo - 浅靛蓝色
  • blue - 蓝色
  • light-blue - 浅蓝色
  • green - 绿色
  • light-green - 浅绿色
  • red - 红色
  • light-red - 浅红色
  • dark - 深色
  • light - 浅色

示例请求：

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

示例响应：

{
    "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,
    "theme": "red"
}

更新广播消息

无论目标设置如何，广播消息都通过 API 公开可访问。不要包含敏感或机密信息，也不要使用广播消息向特定组或项目传达私人信息。

更新现有的广播消息。

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 模块中定义。以下级别有效：

  • Guest (10) - 访客
  • Planner (15) - 计划者
  • Reporter (20) - 报告者
  • Developer (30) - 开发者
  • Maintainer (40) - 维护者
  • Owner (50) - 所有者

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

  • indigo (默认) - 靛蓝色
  • light-indigo - 浅靛蓝色
  • blue - 蓝色
  • light-blue - 浅蓝色
  • green - 绿色
  • light-green - 浅绿色
  • red - 红色
  • light-red - 浅红色
  • dark - 深色
  • light - 浅色

示例请求：

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

示例响应：

{
    "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,
    "theme": "indigo"
}

删除广播消息

删除广播消息。

DELETE /broadcast_messages/:id

参数：

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

示例请求：

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