Skip to content

Commit c1073c1

Browse files
inkedsquidinkedsquid
authored
feat(measure): allow measures to be pushed on Assets via API (no devices) (#344)
1 parent be8cfc4 commit c1073c1

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

49 files changed

+2397
-138
lines changed

‎doc/2/controllers/assets/ingest-measure/index.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
code: true
3+
type: page
4+
title: ingestMeasure
5+
description: Kuzzle IoT Platform - Device Manager - Assets Controller
6+
---
7+
8+
# ingestMeasure
9+
10+
Ingest a single measure into an asset.
11+
12+
---
13+
14+
## Query Syntax
15+
16+
### HTTP
17+
18+
```http
19+
URL: http://kuzzle:7512/_/device-manager/:engineId/assets/:assetId/measures/:slotName
20+
Method: POST
21+
```
22+
23+
### Other protocols
24+
25+
```js
26+
{
27+
"controller": "device-manager/assets",
28+
"action": "measureIngest",
29+
"assetId": "<assetId>",
30+
"engineId": "<engineId>",
31+
"slotName": "<slotName>"
32+
"body": {
33+
"dataSource": {
34+
"id": "<id>",
35+
// optional:
36+
"metadata": {
37+
// ...
38+
}
39+
},
40+
"measuredAt": "<measuredAt>"
41+
"values": {
42+
"<valueName>": "<value>",
43+
// ...
44+
}
45+
},
46+
47+
// optional:
48+
"engineGroup": "<engine group>"
49+
}
50+
```
51+
52+
---
53+
54+
## Arguments
55+
56+
- `engineId`: target engine id
57+
- `assetId`: target asset id
58+
- `slotName`: target measure slot name
59+
- `engineGroup` (optional): target engine group
60+
61+
## Body properties
62+
- `dataSource`: the measure source
63+
- `measuredAt`: the timestamp of when the measure was collected
64+
- `values`: the measure values
65+
66+
# Datasource properties
67+
68+
- `id`: the measure source unique identifier
69+
- `metadata`: (optional) additional metadata for the source
70+
71+
---
72+
73+
## Response
74+
75+
```js
76+
{
77+
"status": 200,
78+
"error": null,
79+
"controller": "device-manager/assets",
80+
"action": "measureIngest",
81+
"requestId": "<unique request identifier>",
82+
"result": null,
83+
}
84+
```
85+
86+
## Errors
87+
88+
Ingesting a measure with incorrect values will throw a [ MeasureValidationError ](../../../errors/measure-validation/index.md) with the HTTP code **400**.

‎doc/2/controllers/assets/ingest-measures/index.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
code: true
3+
type: page
4+
title: ingestMeasures
5+
description: Kuzzle IoT Platform - Device Manager - Assets Controller
6+
---
7+
8+
# ingestMeasures
9+
10+
Ingest measures from a data source into an asset.
11+
12+
---
13+
14+
## Query Syntax
15+
16+
### HTTP
17+
18+
```http
19+
URL: http://kuzzle:7512/_/device-manager/:engineId/assets/:assetId/_mMeasureIngest
20+
Method: POST
21+
```
22+
23+
### Other protocols
24+
25+
```js
26+
{
27+
"controller": "device-manager/assets",
28+
"action": "_mMeasureIngest",
29+
"assetId": "<assetId>",
30+
"engineId": "<engineId>",
31+
"body": {
32+
"dataSource": {
33+
"id": "<id>",
34+
// optional:
35+
"metadata": {
36+
// ...
37+
}
38+
},
39+
"measurements": [
40+
{
41+
"slotName": "<measureName>",
42+
"measuredAt": "<measuredAt>",
43+
"values": {
44+
"<valueName>": "<value>",
45+
// ...
46+
}
47+
}
48+
// ...
49+
]
50+
},
51+
52+
// optional:
53+
"engineGroup": "<engine group>"
54+
}
55+
```
56+
57+
---
58+
59+
## Arguments
60+
61+
- `engineId`: target engine id
62+
- `assetId`: target asset id
63+
- `engineGroup`: (optional): target engine group
64+
65+
## Body properties
66+
67+
- `dataSource`: the measures source
68+
- `measurements`: the list of measurements to ingest
69+
70+
# Datasource properties
71+
72+
- `id`: the measure source unique identifier
73+
- `metadata`: (optional) additional metadata for the source
74+
75+
# Measurement properties
76+
77+
- `slotName`: target measure slot name
78+
- `measuredAt`: the timestamp of when the measure was collected
79+
- `values`: the measure values
80+
81+
---
82+
83+
## Response
84+
85+
```js
86+
{
87+
"status": 200,
88+
"error": null,
89+
"controller": "device-manager/assets",
90+
"action": "mMeasureIngest",
91+
"requestId": "<unique request identifier>",
92+
"result": null,
93+
}
94+
```
95+
96+
## Errors
97+
98+
Ingesting measures with incorrect values will throw a [ MeasureValidationError ](../../../errors/measure-validation/index.md) with the HTTP code **400**.

‎doc/2/controllers/models/get-asset/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Gets an asset model.
1616
### HTTP
1717

1818
```http
19-
URL: http://kuzzle:7512/_/device-manager/models/asset/:_id
19+
URL: http://kuzzle:7512/_/device-manager/models/asset/:model
2020
Method: GET
2121
```
2222

‎doc/2/controllers/models/get-device/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Gets a device model.
1616
### HTTP
1717

1818
```http
19-
URL: http://kuzzle:7512/_/device-manager/models/device/:id
19+
URL: http://kuzzle:7512/_/device-manager/models/device/:model
2020
Method: GET
2121
```
2222

‎doc/2/controllers/models/get-measure/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Gets a measure model.
1616
### HTTP
1717

1818
```http
19-
URL: http://kuzzle:7512/_/device-manager/models/measure/:_id
19+
URL: http://kuzzle:7512/_/device-manager/models/measure/:type
2020
Method: GET
2121
```
2222

‎doc/2/controllers/models/write-asset/index.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,4 +160,8 @@ Method: POST
160160

161161
## Errors
162162

163-
Writing an asset with metadata mappings can cause conflicts, in this case a [ MappingsConflictsError ](../../../errors/mappings-conflicts/index.md) will be thrown with the HTTP code **409**.
163+
| error | code | cause |
164+
| ------------------------------------------------------------------------------ | ------- | --------------------------------------------------- |
165+
| [ MappingsConflictsError ](../../../errors/mappings-conflicts/index.md) | **409** | Writing an asset with conflicting metadata mappings |
166+
| [ MeasuresNamesDuplicatesError ](../../../errors/measures-duplicates/index.md) | **400** | Defining a measure name more than once |
167+

‎doc/2/controllers/models/write-measure/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,10 @@ Method: POST
3434
// Optional
3535
"valuesDetails":{
3636
// Values details and translation
37+
},
38+
// Optional
39+
"validationSchema": {
40+
// Valid JSON Schema
3741
}
3842
}
3943
}
@@ -46,6 +50,7 @@ Method: POST
4650
- `model`: Measure model name
4751
- `valuesMappings`: Mappings of the measure values in Elasticsearch format
4852
- `valuesDetails`: (optional) Measurement translations and units
53+
- `validationSchema`: (optional) Measurement validation JSON schema
4954

5055
---
5156

‎doc/2/errors/mappings-conflicts/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
code: false
33
type: page
44
title: Mappings Conflicts
5-
description: Mappings Conflicts
5+
description: Mappings Conflicts | Kuzzle Documentation
66
---
77

88
# Mappings Conflicts

‎doc/2/errors/measure-validation/index.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
code: false
3+
type: page
4+
title: Measure Validation
5+
description: Measure Validation | Kuzzle Documentation
6+
---
7+
8+
# Measure Validation
9+
10+
A `MeasureValidationError` is thrown when the provided measures values could not be validated by the JSON schema. It can occur on creation of a measure.
11+
12+
**HTTP status**: 400
13+
14+
**Additional Properties:**
15+
16+
| property | type | description |
17+
| -------- | ---------------- | ---------------------------------------------------- |
18+
| `errors` | array of objects | List of invalid data from measures, by measures names. |
19+
20+
Here is an example of a `errors` field:
21+
```js
22+
[
23+
{
24+
"measureName": "magiculeExt",
25+
"validationErrors": [
26+
{
27+
"instancePath": "/magicule",
28+
"schemaPath": "#/properties/magicule/type",
29+
"keyword": "type",
30+
"params": {
31+
"type": "integer"
32+
},
33+
"message": "must be integer"
34+
}
35+
]
36+
},
37+
{
38+
"measureName": "magiculeInt",
39+
"validationErrors": [
40+
{
41+
"instancePath": "/magicule",
42+
"schemaPath": "#/properties/magicule/type",
43+
"keyword": "type",
44+
"params": {
45+
"type": "integer"
46+
},
47+
"message": "must be integer"
48+
}
49+
]
50+
}
51+
]
52+
```
53+
54+
Errors fields:
55+
| field | type | description |
56+
| -------------------- | ---------------- | ------------------------------------------------ |
57+
| `measureName` | string | The measure name where validation errors occured |
58+
| `validationErrors` | array of objects | The list of validation errors (AJV formated) |
59+
60+
61+
The validation errors array contain standard AJV errors, please refer to their documentation about [errors](https://ajv.js.org/api.html#error-objects) for more informations. `instancePath`, in our case, refer to the model name.

‎doc/2/errors/measures-duplicates/index.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
code: false
3+
type: page
4+
title: Measures Names Duplicates
5+
description: Measures Names Duplicates | Kuzzle Documentation
6+
---
7+
8+
# Measures Duplicates
9+
10+
A `MeasuresNamesDuplicatesError` is thrown when one or multiple measures names is defined more than once inside the same model.
11+
12+
**HTTP status**: 400
13+
14+
**Additional Properties:**
15+
16+
| property | type | description |
17+
| ------------ | --------------- | --------------------------------- |
18+
| `duplicates` | array of string | List of duplicated measures names |

0 commit comments

Comments
 (0)