Create and Monitor a Car Sharing Application
In this example, we have a Car Sharing app we want to manage using the REST API for Oracle Management Cloud.
Background
- Shared Car
- Driver
Each Shared Car has 0 to N Drivers assigned to them. The model properties and metrics are the following:
{
"entityType":"SharedCar",
"typeDisplayName": "Shared Car",
"properties": [
{
"name":"licensePlate",
"displayName":"License Plate",
"identifyingProperty":true
}
],
"metrics": [
{
"metric":"usedDistance",
"dimensions": [ "driver" ],
"type":"NUM"
},
{
"metric":"gasUsage",
"dimensions": [],
"type":"NUM"
}
]
}
{
"entityType":"Driver",
"typeDisplayName":"Driver"
}
- Create the custom Entity Types for the Shared Car and Driver.
- Create the custom Entities for the Shared Car and Driver.
- Associate the Drivers to their Shared Cars.
- Upload Metrics for our Entities.
- Query data collected from our Entities.
Task | Procedure / REST API Call |
---|---|
1. Create the SharedCar and Driver Entity Types | Create entity types using |
2. Create the SharedCar Entities | Create entities using |
3. Create and Associate the Drivers to their Shared Cars | Create and Associate entities using POST /serviceapi/entityModel/uds/entities . |
4. Upload Metrics for our Entities | Upload metrics using POST /serviceapi/entityModel/uds/metrics . |
5. Query Data Collected from our Entities | Get metrics using GET /serviceapi/entityModel/uds/metrics . |
Create the SharedCar and Driver Entity Types
The first step in the workflow is to create the entity types using the Entity Types API.
Create the Shared Car Entity Type
Create a new JSON file called sharedCar.json and paste the following:
{
"entityType":"SharedCar",
"typeDisplayName": "Shared Car",
"properties": [
{
"name":"licensePlate",
"displayName":"License Plate",
"identifyingProperty":true
}
],
"metrics": [
{
"metric":"usedDistance",
"dimensions": [ "driver" ],
"type":"NUM"
},
{
"metric":"gasUsage",
"dimensions": [],
"type":"NUM"
}
]
}
This will create a new entity type SharedCar with a license plate as its unique identifying property and two metrics: usedDistance and gasUsage.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entityTypes -d "@sharedcar.json"
Create a new JSON file called driver.json and paste the following:
{
"entityType":"Driver",
"entityName":"Driver"
}
This cURL call will create the Driver entity type:
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities -d "@test.json"
Create the SharedCar Entities
With the Entity Types created, let's create some entities for our Shared Cars using the Entities API.
Create the SharedCar Entities
Car 001:
Create a new JSON file called car001.json and paste the following:
{
"entityType":"SharedCar",
"entityName":"Car001",
"entityDisplayName":"Car 001",
"properties": {
"licensePlate":"ABC 012"
},
"tags":{
"color":"red",
"make":"Ford"
}
}
This cURL call will create the entity Car001:
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities -d "@car001.json"
Car 002:
Create a new JSON file called car002.json and paste the following:
{
"entityType":"SharedCar",
"entityName":"Car002",
"entityDisplayName":"Car 002",
"properties": {
"licensePlate":"XYZ 789"
},
"tags":{
"color":"blue",
"make":"Mercedes"
}
}
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities -d "@car002.json"
Create and Associate the Drivers to their Shared Cars
With the Shared Car entities ready, the next step is to create Driver entities and associate them to the Shared Cars using the Entities API.
Karl:
Create a new JSON file called karl.json and paste the following:
{
"entityType":"Driver",
"entityName":"Karl",
"associations": [
{
"tags":{
"usuallyDrives":""
},
"entityType":"SharedCar",
"entityName":"Car001"
}
]
}
This cURL call will create the Karl entity and associate it to Car001.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities -d "@karl.json"
Peter:
Create a new JSON file called peter.json and paste the following:
{
"entityType":"Driver",
"entityName":"Peter",
"associations": [
{
"tags":{
"usuallyDrives":""
},
"entityType":"SharedCar",
"entityName":"Car002"
}
]
}
This cURL call will create the Peter entity and associate it to Car002.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities -d "@peter.json"
Ana:
Create a new JSON file called ana.json and paste the following:
{
"entityType":"Driver",
"entityName":"Ana",
"associations": [
{
"tags":{
"usuallyDrives":""
},
"entityType":"SharedCar",
"entityName":"Car001"
}
]
}
This cURL call will create the Ana entity and associate it to Car001.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities -d "@ana.json"
Mary:
Create a new JSON file called mary.json and paste the following:
{
"entityType":"Driver",
"entityName":"Mary",
"associations": [
{
"tags":{
"usuallyDrives":""
},
"entityType":"SharedCar",
"entityName":"Car002"
}
]
}
This cURL call will create the Mary entity and associate it to Car002.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities -d "@mary.json"
Upload Metrics for our Entities
With entity types and entities ready, the next step is to upload metrics using the Metrics API.
Metrics uploaded Feb 05:
Create a new JSON file called feb05.json and paste the following:
[
{
"entityType":"SharedCar",
"entityName":"Car001",
"collectionTime":"2019-02-05T23:00:00.000Z",
"dimension":{"driver":"Karl"},
"metric":"usedDistance",
"value":10
},
{
"entityType":"SharedCar",
"entityName":"Car002",
"collectionTime":"2019-02-05T23:00:00.000Z",
"dimension":{"driver":"Peter"},
"metric":"usedDistance",
"value":75
},
{
"entityType":"SharedCar",
"entityName":"Car001",
"collectionTime":"2019-02-05T23:00:00.000Z",
"dimension":{"driver":"Ana"},
"metric":"usedDistance",
"value":20
},
{
"entityType":"SharedCar",
"entityName":"Car002",
"collectionTime":"2019-02-05T23:00:00.000Z",
"dimension":{"driver":"Mary"},
"metric":"usedDistance",
"value":25
}
]
This cURL call will upload metrics for the Shared Cars collected during Feb 05.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/metrics -d "@feb05.json"
Metrics uploaded Feb 08:
Create a new JSON file called feb08.json and paste the following:
[
{
"entityType":"SharedCar",
"entityName":"Car001",
"collectionTime":"2019-02-08T23:00:00.000Z",
"dimension":{"driver":"Karl"},
"metric":"usedDistance",
"value":25
},
{
"entityType":"SharedCar",
"entityName":"Car001",
"collectionTime":"2019-02-08T23:00:00.000Z",
"dimension":{"driver":"Peter"},
"metric":"usedDistance",
"value":0
},
{
"entityType":"SharedCar",
"entityName":"Car002",
"collectionTime":"2019-02-08T23:00:00.000Z",
"dimension":{"driver":"Ana"},
"metric":"usedDistance",
"value":55
},
{
"entityType":"SharedCar",
"entityName":"Car002",
"collectionTime":"2019-02-08T23:00:00.000Z",
"dimension":{"driver":"Mary"},
"metric":"usedDistance",
"value":15
}
]
This cURL call will upload metrics for the Shared Cars collected during Feb 08.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/metrics -d "@feb08.json"
Query Data Collected from our Entities
With the entities setup and some metrics collected, metrics collected can now be queried using the Metrics API.
Query all usedDistance data points from Karl between Feb 04 - Feb 08:
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/metrics?entityType=SharedCar&entityName=Car001&metric=usedDistance&startTime=2019-02-04T00:00:00.000Z&endTime=2019-02-08T23:59:59.999Z&dimension=driver=Karl
Response:
{
"entityType": "SharedCar",
"entityName": "Car001",
"metric": "usedDistance",
"dimension": {
"driver": "Karl"
},
"startTime": "2019-02-04T00:00:00.000Z",
"endTime": "2019-02-08T23:59:59.999Z",
"dataPoints": [
[
"2019-02-07T23:00:00.000Z",
10
],
[
"2019-02-08T23:00:00.000Z",
25
]
]
}