List Alarms¶
Overview¶
- Lists alarms, based on a query.
- This API performs the same function as "OpenStack Telemetry API: GET /v2/alarms".
Classification¶
- List
API Operation Object¶
- Alarm
Synchronous / Asynchronous¶
- Synchronous
Request¶
HTTP Request Method¶
- GET
HTTP Request Path¶
{api_endpoint}/v2/alarms
HTTP Request Header¶
Content-Type: application/json
Accept: application/json
X-Auth-Token: <token_id>
HTTP Request Body¶
- none
Request Parameter¶
| name | style | format | description | required/optional | default value | action for invalid parameter | response code for invalid parameter |
|---|---|---|---|---|---|---|---|
| q | Query | string | Filter rules for listing alarms | optional | - | Terminate | 400 |
| page | Query | Integer | A page number when alarms are paginated | optional | 100 | Terminate | 400 |
| per_page | Query | Integer | A page number when alarms are paginated | optional | 100 | Terminate | 400 |
| token_id | Header | authentication token string | authentication token | required | - | Terminate | 401 |
A query key can be designated by describing after a dot(.) . (ex. q.field, q.op)
| key name | format | description | required/optional | default value |
|---|---|---|---|---|
| field | string | a retrieving target | required | - |
| op | string | a comparison operator | optional | eq |
| value | string | a field value for retrieving meter statistics | required | - |
| type | string | format used to convert the value for comparison | optional | - |
A query field can be designated by describing after "q.field=". (ex. q.field=timestamp)
| key name | format | description | required/optional | default value | valid operator |
|---|---|---|---|---|---|
| alarm_id | string | the uuid of an alarm | optional | - | eq |
| project_id | string | the uuid of a tenant | optional | - | eq |
| project | string | an alias of 'project_id' | optional | - | eq |
| user_id | string | the uuid of a user | optional | - | eq |
| user | string | an alias of 'user_id' | optional | - | eq |
| name | string | the name of an alarm | optional | - | eq |
| enabled | boolean | whether an alarm is enabled or disabled | optional | - | eq |
| state | string | the state of an alarm | optional | - | eq |
| meter | string | the meter name to which an alarm belongs | optional | - | eq |
| type | string | the type of an alarm | optional | - | eq |
| alarm_type | string | an alias of 'type' | optional | - | eq |
| severity | string | the severity of an alarm | optional | - | eq |
A query operator can be designated by describing after "q.op=". (ex. q.op=eq)
| operator | description |
|---|---|
| eq | equal to |
A query type can be designated by describing after "q.type=". (ex. q.type=integer)
| type | ex. (q.value) |
|---|---|
| integer | 1234 |
| float | 1234.1234 |
| boolean | 0 or 1 |
| string | abcd |
| datetime | 2015-12-01T12:34:00+09:00 |
Response¶
Response Header¶
Format¶
HTTP/1.1 <response_code> <status> (ex. 200 OK)
- <response_code>: see "Response Code" section
- <status>: message based on the response code
注釈
skip auto-insert fields such as "Content-Length" and "Date"
Response Code¶
| response code | status | condition | message |
|---|---|---|---|
| 200 | ok | normal end | |
| 400 | bad request | specified non query field | Field can't be blank. |
| invalid query field | Unrecognized field in query. valid keys: ["alarm_id", "enabled", "meter", "name", "project_id", "state", "type", "severity", "user_id"] | ||
| invalid query op | Unimplemented operator 'xxxx' for specified field. | ||
| specified non query value | Value can't be blank. | ||
| invalid query data type | The data type 'xxxx' is not supported. The supported data type list is: ['integer', 'float', 'boolean', 'string', 'datetime'] | ||
| invalid value (1) | Unable to convert the value 'xxxx' to the expected data type 'integer'. | ||
| invalid value (2) | Unexpected exception converting 'xxxx' to the expected data type 'datetime'. | ||
| 401 | unauthorized | authentication failure | The request you have made requires authentication. |
| invalid project id | Not authorized to access project. | ||
| 500 | internal server error | internal server error | The request processing has failed due to some unknown error, exception or failure |
Response Body¶
Format¶
[
{
"alarm_id": "<alarm_id>",
"project_id": "<tenant_id>",
"user_id": "<user_id>",
"name": "<alarm_name>",
"description": "<alarm_description>",
"enabled": <enabled>,
"state": "<state>",
"repeat_actions": <repeat_actions>,
"severity": "<severity>",
"time_constraints": [],
"alarm_actions": ["<alarm_actions>",<<repeat>>],
"ok_actions": ["<ok_actions>",<<repeat>>],
"insufficient_data_actions": [],
"type": "threshold",
"threshold_rule": {
"meter_name": "<meter_name>",
"period": <period>,
"query": [{
"field": "resource_id",
"op": "eq",
"type": "string",
"value": "<resource_id>"
}],
"exclude_outliers": false,
"evaluation_periods": <evaluation_periods>,
"evaluation_type": "<evaluation_type>",
"comparison_operator": "<comparison_operator>",
"statistic": "<statistics>",
"threshold": <threshold>
},
"timestamp": "<timestamp>",
"state_timestamp": "<state_timestamp>",
"resource_name": "<resource_name>",
"deleted": <deleted>
},
<<repeat>>
]
Response Parameter¶
| item | format | description |
|---|---|---|
| (data) | List(Alarm) | alarms listed by the request |
Sample Request and Response¶
Sample API Request¶
Request URL¶
GET /v2/alarms/?q.field=alarm_id&q.op=eq&q.type=string&q.value=638c3bfe-9435-45f5-9fbb-9d6d380c17ba&page=1&per_page=10
Request Header¶
Content-Type: application/json
Accept: application/json
X-Auth-Token: e8c788fbaeb14964ae19759eb1df4ff1
Request Body¶
- none
Sample API Response¶
Response Header¶
HTTP/1.1 200 OK
Response Body¶
[
{
"alarm_id": "638c3bfe-9435-45f5-9fbb-9d6d380c17ba",
"project_id": "26574d10673044dbb03ffc8facc7ab7a",
"user_id": "a9de93f5a7604707a2870d8b95f74eda",
"name": "alarm-test",
"description": "alarm-test-description",
"enabled": true,
"state": "ok",
"repeat_actions": false,
"severity": "moderate",
"time_constraints": [],
"alarm_actions": ["http://example.com"],
"ok_actions": ["http://example.com"],
"insufficient_data_actions": [],
"type": "threshold",
"threshold_rule": {
"meter_name": "nova.hv.status.bool",
"period": 300,
"query": [{
"field": "resource_id",
"op": "eq",
"type": "string",
"value": "nova_5dd5bfe5-aee8-4663-86e4-e76d032d318e"
}],
"exclude_outliers": false,
"evaluation_periods": 1,
"evaluation_type": "0",
"comparison_operator": "gt",
"statistic": "max",
"threshold": 1
},
"timestamp": "2015-11-23T04:35:08+00:00",
"state_timestamp": "2015-11-20T07:05:10+00:00",
"resource_name": "test-vm",
"deleted": false
}
]
Sample Error Response¶
HTTP Request¶
GET /v2/alarms?q.field=hoge&q.value=hoge
User-Agent: curl/7.35.0
Content-Type: application/json
Accept: application/json
X-Auth-Token: 61389973e52b49c394ba3b89179b290b
HTTP Response¶
HTTP/1.1 400 Bad Request
Date: Mon, 09 Nov 2015 04:36:02 GMT
Server: Apache
Cache-Control: no-cache
X-XSS-Protection: 1; mode=block
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
Status: 400 Bad Request
Connection: close
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{"error":{"code":400,"message":"Unrecognized field in query. valid keys: [\"alarm_id\", \"enabled\", \"meter\", \"name\", \"project_id\", \"state\", \"type\", \"severity\", \"user_id\"]","title":"Bad Request"}}