debian-mirror-gitlab/doc/api/broadcast_messages.md

190 lines
5.3 KiB
Markdown
Raw Normal View History

2017-09-10 17:25:29 +05:30
# Broadcast Messages API
2016-09-29 09:46:39 +05:30
2019-07-07 11:18:12 +05:30
> Introduced in GitLab 8.12.
2016-09-29 09:46:39 +05:30
2019-07-07 11:18:12 +05:30
Broadcast messages API operates on [broadcast messages](../user/admin_area/broadcast_messages.md).
2020-03-13 15:44:24 +05:30
As of GitLab 12.8, GET requests do not require authentication. All other broadcast message API endpoints are accessible only to administrators. Non-GET requests by:
2019-07-07 11:18:12 +05:30
- Guests will result in `401 Unauthorized`.
- Regular users will result in `403 Forbidden`.
2016-09-29 09:46:39 +05:30
## Get all broadcast messages
2019-07-07 11:18:12 +05:30
List all broadcast messages.
2020-05-24 23:13:21 +05:30
```plaintext
2016-09-29 09:46:39 +05:30
GET /broadcast_messages
```
2019-07-07 11:18:12 +05:30
Example request:
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl "https://gitlab.example.com/api/v4/broadcast_messages"
2016-09-29 09:46:39 +05:30
```
Example response:
```json
[
{
"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,
2020-01-01 13:55:28 +05:30
"active": false,
2020-03-13 15:44:24 +05:30
"target_path": "*/welcome",
2020-04-08 14:13:33 +05:30
"broadcast_type": "banner",
"dismissable": false
2016-09-29 09:46:39 +05:30
}
]
```
## Get a specific broadcast message
2019-07-07 11:18:12 +05:30
Get a specific broadcast message.
2020-05-24 23:13:21 +05:30
```plaintext
2016-09-29 09:46:39 +05:30
GET /broadcast_messages/:id
```
2019-07-07 11:18:12 +05:30
Parameters:
| Attribute | Type | Required | Description |
|:----------|:--------|:---------|:-------------------------------------|
| `id` | integer | yes | ID of broadcast message to retrieve. |
Example request:
2016-09-29 09:46:39 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl "https://gitlab.example.com/api/v4/broadcast_messages/1"
2016-09-29 09:46:39 +05:30
```
Example response:
```json
{
"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,
2020-01-01 13:55:28 +05:30
"active":false,
2020-03-13 15:44:24 +05:30
"target_path": "*/welcome",
2020-04-08 14:13:33 +05:30
"broadcast_type": "banner",
"dismissable": false
2016-09-29 09:46:39 +05:30
}
```
## Create a broadcast message
2019-07-07 11:18:12 +05:30
Create a new broadcast message.
2020-05-24 23:13:21 +05:30
```plaintext
2016-09-29 09:46:39 +05:30
POST /broadcast_messages
```
2019-07-07 11:18:12 +05:30
Parameters:
2016-09-29 09:46:39 +05:30
2020-04-08 14:13:33 +05:30
| Attribute | Type | Required | Description |
|:----------------|:---------|:---------|:------------------------------------------------------|
| `message` | string | yes | Message to display. |
| `starts_at` | datetime | no | Starting time (defaults to current time). |
| `ends_at` | datetime | no | Ending time (defaults to one hour from current time). |
| `color` | string | no | Background color hex code. |
| `font` | string | no | Foreground color hex code. |
| `target_path` | string | no | Target path of the broadcast message. |
| `broadcast_type`| string | no | Appearance type (defaults to banner) |
| `dismissable` | boolean | no | Can the user dismiss the message? |
2019-07-07 11:18:12 +05:30
Example request:
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --data "message=Deploy in progress&color=#cecece" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/broadcast_messages"
2016-09-29 09:46:39 +05:30
```
Example response:
```json
{
"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,
2020-01-01 13:55:28 +05:30
"active": true,
2020-03-13 15:44:24 +05:30
"target_path": "*/welcome",
"broadcast_type": "notification",
2020-04-08 14:13:33 +05:30
"dismissable": false
2016-09-29 09:46:39 +05:30
}
```
## Update a broadcast message
2019-07-07 11:18:12 +05:30
Update an existing broadcast message.
2020-05-24 23:13:21 +05:30
```plaintext
2016-09-29 09:46:39 +05:30
PUT /broadcast_messages/:id
```
2019-07-07 11:18:12 +05:30
Parameters:
2020-04-08 14:13:33 +05:30
| Attribute | Type | Required | Description |
|:----------------|:---------|:---------|:--------------------------------------|
| `id` | integer | yes | ID of broadcast message to update. |
| `message` | string | no | Message to display. |
| `starts_at` | datetime | no | Starting time. |
| `ends_at` | datetime | no | Ending time. |
| `color` | string | no | Background color hex code. |
| `font` | string | no | Foreground color hex code. |
| `target_path` | string | no | Target path of the broadcast message. |
| `broadcast_type`| string | no | Appearance type (defaults to banner) |
| `dismissable` | boolean | no | Can the user dismiss the message? |
2016-09-29 09:46:39 +05:30
2019-07-07 11:18:12 +05:30
Example request:
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request PUT --data "message=Update message&color=#000" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/broadcast_messages/1"
2016-09-29 09:46:39 +05:30
```
Example response:
```json
{
"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,
2020-01-01 13:55:28 +05:30
"active": true,
2020-03-13 15:44:24 +05:30
"target_path": "*/welcome",
"broadcast_type": "notification",
2020-04-08 14:13:33 +05:30
"dismissable": false
2016-09-29 09:46:39 +05:30
}
```
## Delete a broadcast message
2019-07-07 11:18:12 +05:30
Delete a broadcast message.
2020-03-13 15:44:24 +05:30
```shell
2016-09-29 09:46:39 +05:30
DELETE /broadcast_messages/:id
```
2019-07-07 11:18:12 +05:30
Parameters:
| Attribute | Type | Required | Description |
|:----------|:--------|:---------|:-----------------------------------|
| `id` | integer | yes | ID of broadcast message to delete. |
Example request:
2016-09-29 09:46:39 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/broadcast_messages/1"
2016-09-29 09:46:39 +05:30
```