open-consul/website/pages/api-docs/event.mdx

159 lines
4.8 KiB
Plaintext
Raw Normal View History

2017-04-04 16:33:22 +00:00
---
layout: api
page_title: Events - HTTP API
sidebar_title: Events
2017-04-04 16:33:22 +00:00
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.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------------- | ------------------ |
| `PUT` | `/event/fire/:name` | `application/json` |
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------- |
| `NO` | `none` | `none` | `event:write` |
2017-04-04 16:33:22 +00:00
### Parameters
- `name` `(string: <required>)` - Specifies the name of the event to fire. This
is specified as part of the URL. This name must not start with an underscore,
since those are reserved for Consul internally.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `node` `(string: "")` - Specifies a regular expression to filter by node name.
This is specified as part of the URL as a query parameter.
- `service` `(string: "")` - Specifies a regular expression to filter by service
name. This is specified as part of the URL as a query parameter.
- `tag` `(string: "")` - Specifies a regular expression to filter by tag. This
is specified as part of the URL as a query parameter.
### 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
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
--request PUT \
--data @payload \
http://127.0.0.1:8500/v1/event/fire/my-event
2017-04-04 16:33:22 +00:00
```
### 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
2017-04-04 16:33:22 +00:00
agent may have a different view of the events. Events are broadcast using the
2020-04-09 23:46:54 +00:00
[gossip protocol](/docs/internals/gossip), so they have no global ordering
2017-04-04 16:33:22 +00:00
nor do they make a promise of delivery.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------- | ------------------ |
| `GET` | `/event/list` | `application/json` |
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
2017-04-04 16:33:22 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `none` | `none` | `event:read` |
2017-04-04 16:33:22 +00:00
### Parameters
- `name` `(string: <required>)` - Specifies the name of the event to filter.
This is specified as part of the URL as a query parameter.
- `node` `(string: "")` - Specifies a regular expression to filter by node name.
This is specified as part of the URL as a query parameter.
- `service` `(string: "")` - Specifies a regular expression to filter by service
name. This is specified as part of the URL as a query parameter.
- `tag` `(string: "")` - Specifies a regular expression to filter by tag. This
is specified as part of the URL as a query parameter.
### Sample Request
2020-05-19 18:32:38 +00:00
```shell-session
2017-04-04 16:33:22 +00:00
$ curl \
http://127.0.0.1:8500/v1/event/list
2017-04-04 16:33:22 +00:00
```
### 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
2020-04-09 23:46:54 +00:00
[consensus protocol](/docs/internals/consensus). With gossip, there is no
2017-04-04 16:33:22 +00:00
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.