consul/website/content/api-docs/event.mdx

156 lines
4.4 KiB
Markdown

---
layout: api
page_title: Events - HTTP API
description: |-
The /event endpoints fire new events and to query the available events in
Consul.
---
# Event HTTP Endpoint
The `/event` endpoints fire new events and to query the available events in
Consul.
## Fire Event
This endpoint triggers a new user event.
| Method | Path | Produces |
| ------ | ------------------- | ------------------ |
| `PUT` | `/event/fire/:name` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------- |
| `NO` | `none` | `none` | `event:write` |
The corresponding CLI command is [`consul event`](/commands/event).
### Path Parameters
- `name` `(string: <required>)` - Specifies the name of the event to fire.
This name must not start with an underscore,
since those are reserved for Consul internally.
### Query Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried.
- `node` `(string: "")` - Specifies a regular expression to filter by node name.
- `service` `(string: "")` - Specifies a regular expression to filter by service name.
- `tag` `(string: "")` - Specifies a regular expression to filter by tag.
### Sample Payload
The body contents are opaque to Consul and become the "payload" that is passed
onto the receiver of the event.
```text
Lorem ipsum dolor sit amet, consectetur adipisicing elit...
```
### Sample Request
```shell-session
$ curl \
--request PUT \
--data @payload \
http://127.0.0.1:8500/v1/event/fire/my-event
```
### Sample Response
```json
{
"ID": "b54fe110-7af5-cafc-d1fb-afc8ba432b1c",
"Name": "deploy",
"Payload": null,
"NodeFilter": "",
"ServiceFilter": "",
"TagFilter": "",
"Version": 1,
"LTime": 0
}
```
- `ID` is a unique identifier the newly fired event
## List Events
This endpoint returns the most recent events (up to 256) known by the agent. As a
consequence of how the [event command](/commands/event) works, each
agent may have a different view of the events. Events are broadcast using the
[gossip protocol](/docs/architecture/gossip), so they have no global ordering
nor do they make a promise of delivery.
@include 'http_api_results_filtered_by_acls.mdx'
| Method | Path | Produces |
| ------ | ------------- | ------------------ |
| `GET` | `/event/list` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `none` | `none` | `event:read` |
### Query Parameters
- `name` `(string: "")` - Specifies the name of the event to filter.
- `node` `(string: "")` - Specifies a regular expression to filter by node name.
- `service` `(string: "")` - Specifies a regular expression to filter by service name.
- `tag` `(string: "")` - Specifies a regular expression to filter by tag.
### Sample Request
```shell-session
$ curl \
http://127.0.0.1:8500/v1/event/list
```
### Sample Response
```json
[
{
"ID": "b54fe110-7af5-cafc-d1fb-afc8ba432b1c",
"Name": "deploy",
"Payload": "MTYwOTAzMA==",
"NodeFilter": "",
"ServiceFilter": "",
"TagFilter": "",
"Version": 1,
"LTime": 19
}
]
```
### Caveat
The semantics of this endpoint's blocking queries are slightly different. Most
blocking queries provide a monotonic index and block until a newer index is
available. This can be supported as a consequence of the total ordering of the
[consensus protocol](/docs/architecture/consensus). With gossip, there is no
ordering, and instead `X-Consul-Index` maps to the newest event that matches the
query.
In practice, this means the index is only useful when used against a single
agent and has no meaning globally. Because Consul defines the index as being
opaque, clients should not be expecting a natural ordering either.