1. OMC REST APIOracle Management Cloud Common REST API
  2. Get Started With Monitoring
  3. Use Cases
  4. Create and Monitor a Car Sharing Application

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

For the Car Sharing app, we have the following Entity Types:
  • Shared Car
  • Driver

Each Shared Car has 0 to N Drivers assigned to them. The model properties and metrics are the following:

Shared Car Model 
{   
  "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"
    }
  ]
}
Driver Model 
{
  "entityType":"Driver",   
  "typeDisplayName":"Driver"
}
Our goal for this exercise is to:
  1. Create the custom Entity Types for the Shared Car and Driver.
  2. Create the custom Entities for the Shared Car and Driver.
  3. Associate the Drivers to their Shared Cars.
  4. Upload Metrics for our Entities.
  5. Query data collected from our Entities.
Task Procedure / REST API Call
1. Create the SharedCar and Driver Entity Types

Create entity types using POST /serviceapi/entityModel/uds/entityTypes.

2. Create the SharedCar Entities

Create entities using POST /serviceapi/entityModel/uds/entities.

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
    ]
  ]
}