The transaction endpoint supports the use of ACL tokens using the "?token=" query
parameter.
#### PUT Method
The `PUT` method lets you submit a list of operations to apply to the key/value store
inside a transaction. If any operation fails, the transaction will be rolled back and
none of the changes will be applied.
The body of the request should be a list of operations to perform inside the atomic
transaction, which looks like this:
```javascript
[
{
"KV": {
"Verb": "<verb>",
"Key": "<key>",
"Value": "<Base64-encodedblobofdata>",
"Flags": <flags>,
"Index": <index>,
"Session": "<sessionid>"
}
},
...
]
```
`KV` is the only available operation type, though other types of operations may be added
in future versions of Consul to be mixed with key/value operations. The following fields
are available:
* `Verb` is the type of operation to perform. Please see the table below for
available verbs.
* `Key` is simply the full path of the entry.
* `Value` is a Base64-encoded blob of data. Note that values cannot be larger than
512kB.
* `Flags` is an opaque unsigned integer that can be attached to each entry. Clients
can choose to use this however makes sense for their application.
* `Index` and `Session` are used for locking, unlocking, and check-and-set operations.
Please see the table below for details on how they are used.
The following table summarizes the available verbs and the fields that apply to that
operation ("X" means a field is required and "O" means it is optional):
<tableclass="table table-bordered table-striped">
<tr>
<th>Verb</th>
<th>Operation</th>
<th>Key</th>
<th>Value</th>
<th>Flags</th>
<th>Index</th>
<th>Session</th>
</tr>
<tr>
<td>set</td>
<td>Sets the `Key` to the given `Value`.</td>
<tdalign="center">X</td>
<tdalign="center">X</td>
<tdalign="center">O</td>
<tdalign="center"></td>
<tdalign="center"></td>
</tr>
<tr>
<td>cas</td>
<td>Sets the `Key` to the given `Value` with check-and-set semantics. The `Key` will only be set if its current modify index matches the supplied `Index`.</td>
<tdalign="center">X</td>
<tdalign="center">X</td>
<tdalign="center">O</td>
<tdalign="center">X</td>
<tdalign="center"></td>
</tr>
<tr>
<td>lock</td>
<td>Locks the `Key` with the given `Session`. The `Key` will only obtain the lock if the `Session` is valid, and no other session has it locked.</td>
<tdalign="center">X</td>
<tdalign="center">X</td>
<tdalign="center">O</td>
<tdalign="center"></td>
<tdalign="center">X</td>
</tr>
<tr>
<td>unlock</td>
<td>Unlocks the `Key` with the given `Session`. The `Key` will only release the lock if the `Session` is valid and currently has it locked..</td>
<tdalign="center">X</td>
<tdalign="center">X</td>
<tdalign="center">O</td>
<tdalign="center"></td>
<tdalign="center">X</td>
</tr>
<tr>
<td>get</td>
<td>Gets the `Key` during the transaction. This fails the transaction if the `Key` doesn't exist.</td>
<tdalign="center">X</td>
<tdalign="center"></td>
<tdalign="center"></td>
<tdalign="center"></td>
<tdalign="center"></td>
</tr>
<tr>
<td>check-index</td>
<td>Fails the transaction if `Key` does not have a modify index equal to `Index`.</td>
<tdalign="center">X</td>
<tdalign="center"></td>
<tdalign="center"></td>
<tdalign="center">X</td>
<tdalign="center"></td>
</tr>
<tr>
<td>check-session</td>
<td>Fails the transaction if `Key` is not currently locked by `Session`.</td>
<tdalign="center">X</td>
<tdalign="center"></td>
<tdalign="center"></td>
<tdalign="center"></td>
<tdalign="center">X</td>
</tr>
<tr>
<td>delete</td>
<td>Deletes the `Key`.</td>
<tdalign="center">X</td>
<tdalign="center"></td>
<tdalign="center"></td>
<tdalign="center"></td>
<tdalign="center"></td>
</tr>
<tr>
<td>delete-tree</td>
<td>Deletes all keys with a prefix of`Key`.</td>
<tdalign="center">X</td>
<tdalign="center"></td>
<tdalign="center"></td>
<tdalign="center"></td>
<tdalign="center"></td>
</tr>
<tr>
<td>delete-cas</td>
<td>Deletes the `Key` with check-and-set semantics. The `Key` will only be deleted if its current modify index matches the supplied `Index`.</td>
<tdalign="center">X</td>
<tdalign="center"></td>
<tdalign="center"></td>
<tdalign="center">X</td>
<tdalign="center"></td>
</tr>
</table>
If the transaction can be processed, a status code of 200 will be returned if it
was successfully applied, or a status code of 409 will be returned if it was rolled
back. If either of these status codes are returned, the response will look like this:
```javascript
{
"Results": [
{
"KV": {
"LockIndex": <lockindex>,
"Key": "<key>",
"Flags": <flags>,
"Value": "<Base64-encodedblobofdata,ornull>",
"CreateIndex": <index>,
"ModifyIndex": <index>
}
},
...
],
"Errors": [
{
"OpIndex": <indexoffailedoperation>,
"What": "<errormessageforfailedoperation>"
},
...
]
}
```
`Results` has an entry for each operation if the transaction was successful. To save
space, the `Value` will be `null` for any `Verb` other than "get". Like the `/v1/kv/<key>`
endpoint, `Value` will be Base64-encoded if it is present. For verbs that delete
keys, a `null` result entry will be present, keeping the list of `Results` 1:1 with the
list of operations given in the transaction.
`Errors` has entries describing which operations failed if the transaction was rolled
back. The `OpIndex` gives the index of the failed operation in the transaction, and
`What` is a string with an error message about why that operation failed.
If any other status code is returned, such as 400 or 500, then the body of the response
will simply be an unstructured error message about what happened.
James Phillips
9 years ago