Follow an End-to-End Example Journey Using REST API
This example will go over an end-to-end workflow on how to create, update, query, and delete your resources using the REST API for Oracle Management Cloud.
| Task | Procedure / REST API Call |
|---|---|
| 1. Create an Entity Type | Create a new Entity Type using |
| 2. Create an Entity | Create your new Entities using |
| 3. Create, Associate, and Group an Application to a Host | Create, associate, and group your application Entity Type to your Entity using |
| 4. Query your Entities | Query your Entities using |
| 5. Follow an End-to-End Example Journey Using REST API | Upload your host's Metrics using |
| 6. Follow an End-to-End Example Journey Using REST API | Get a list of your host's Metrics using |
| 7. Follow an End-to-End Example Journey Using REST API | Delete your Entities using |
Create a new Entity Type
Oracle Management Cloud offers different options to create a new entity type.
Option 1: Create an Entity Type and an Entity in one operation
Oracle Management Cloud will automatically create the entity type without any metrics if the entity type doesn't exist yet. This command will create an entity MyHostEntity001 and the entity type MyHostType. To implement custom metrics for the entity type, the definition must be updated using POST /serviceapi/entityModel/uds/entityTypes.
Create a new JSON file called myEntity000.json and paste the following:
{
"entityType":"MyHostType",
"entityName":"MyHostEntity000"
}
This cURL call will create a new entity called MyHostEntity000 of type MyHostType.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities -d "@myEntity000.json"
This option is useful for an all in one solution. The drawback to this is that the entity type definition will be empty and will require the definition of the entity type to be updated manually. The next option starts with creating an entity type, where there is more control over the metrics and properties of the entities.
Option 2: Create an entity type, then move to step 2 to create an Entity.
Create a new JSON file called myEntityType.json and paste the following:
{
"entityType": "MyHostType",
"properties": [
{
"name":"id",
"displayName":"Id",
"identifyingProperty":true
}
],
"metrics": [
{
"dimensions": [
"cpuId"
],
"metric": "cpuUser"
},
{
"dimensions": [
"cpuId"
],
"metric": "cpuSystem"
},
{
"dimensions": [
"cpuId"
],
"metric": "cpuIdle"
}
],
"typeDisplayName": "My Host Type"
}This will create a new entity type MyHostType with a unique identifying property id with three metrics cpuUser, cpuSystem and cpuIdle inside the dimension cpuId. Separating metrics inside dimensions will be useful later when querying entities and data points.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entityTypes -d "@myEntityType.json"
The next step will go more in-depth about the versatility of the Entities API.
Create a new Entity
The Entities API lets you create entities and entity types, it also manages the infrastructure by using tags.
Option 1: Create a basic Entity
A cURL call with a payload including an entity type and an entity name is all that's needed to create an Entity. If the entity type doesn't exist, Oracle Management Cloud will create one automatically.{
"entityType":"MyHostType",
"entityName":"MyHostEntity000"
}
Send the following cURL call to create a new entity called MyHostEntity000 with entity type MyHostType.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities -d "@myentity000.json"
Option 2: Create an Entity with some tags and a display Name
Create a new JSON file called myEntity001.json and paste the following:
{
"entityType":"MyHostType",
"entityName":"MyHostEntity001",
"entityDisplayName":"My Host Entity 001",
"properties": {
"id":"001"
},
"tags":{
"loc":"foo",
"os":"bar"
}
}This option is more robust and has more control over the entity. This cURL call will create a new entity with name MyHostEntity001, located in foo, with OS bar.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities -d "@myEntity001.json"
In the following step we will go over the functionality of the Tag API.
Create, Associate, and Group an Application to a Host
Associations and tags are a way to create a link between two or more entities. Group entities together to organize and query entities together.
Assume that an application is now running in MyHostEntity001. This step will create a new entity MyApplication of type MyApplicationType and associate it to previously created entity MyHostEntity001. An association parameter will be included in the payload to MyHostEntity001 with tags for runs_on and loc, these tags will be useful when grouping and querying resources.
Create a new JSON called myApplication.json and paste the following:
{
"entityType": "MyApplicationType",
"entityName": "MyApplication",
"associations": [
{
"entityType": "MyHostType",
"entityName": "MyHostEntity001",
"tags": {
"runs_on": "java",
"loc": "foo"
}
}
]
}Using the Create Entities API, an entity type MyApplicationType will be created automatically.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities -d "@myapplication.json"
Create a Group containing all Entities located in foo
Create a new JSON file called groupEntities.json and paste the following:
{
"groupName":"MyFooGroup",
"groupDisplayName": "My Entities in foo",
"tagCriteria":"loc=foo"
}Create a new group for all entities located in foo.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/groups -d "@groupEntities.json"
Query your Entities
REST API for Oracle Management Cloud offers a way to query entities by name, type, and tags using the Entities API.
Query entities by using a GET or POST call. With the GET call, specify the query parameters directly in the path. For the POST call, send a JSON payload with the search criteria.
Get an Entity of Type MyHostType and Name MyHostEntity001
This cURL call will get MyHostEntity001 of type MyHostType.
curl -u USER:PASSWORD -X GET -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities?entityType=MyHostType&entityName=MyHostEntity001
Get all Entities of a Specific Type
This cURL call will get all entities of type MyHostType.
curl -u USER:PASSWORD -X GET -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities?entityType=MyHostType
Get all Entities Using Wildcards in the Name
This cURL call will get all entities starting with My*. To use a wildcard, use an asterisk *. Wildcards can only be used in entity name and tags.
curl -u USER:PASSWORD -X GET -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities?entityName=My*
Get all Entities that are Located in foo
This cURL call will get all entities that are located in foo using tags in the path.
curl -u USER:PASSWORD -X GET -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities?tagKey=loc&tagValue=foo
The following examples are using POST calls. POST calls accept queries with more complex criteria. These queries can be written down as logical statements or expressions. (e.g Queries can be concatenated using AND or OR statements.)
Query all Entities that are Located in foo and have OS bar
Create a new JSON file with name locAndOS.json and paste the following:
{
"entityType":"MyHostType",
"tagCriteria":"(loc=foo and os=bar)"
}curl -u USER:PASSWORD -X POST -H "Content-Type:application/json" -d "@locAndOS.json" OMC_URL:PORT/serviceapi/entityModel/uds/entities/query"
Query all Entities with names starting with My that are located in foo
Create a new JSON file called wildcard.json and paste the following:
{
"entityType":"MyHostType",
"entityName":"My*"
"tagCriteria":"loc=foo"
}Wildcards can also be used inside the JSON payload when querying for entity name or tag values.
curl -u USER:PASSWORD -X POST -H "Content-Type:application/json" -d "@wildcard.json" OMC_URL:PORT/serviceapi/entityModel/uds/entities/query"
Query all Entities that are located in foo but don't have OS bar
Create a new JSON file called locNotOS.json and paste the following:
{
"entityType":"MyHostType",
"tagCriteria":"loc=foo and os!=bar"
}curl -u USER:PASSWORD -X POST -H "Content-Type:application/json" -d "@locNotOS.json" OMC_URL:PORT/serviceapi/entityModel/uds/entities/query"
Next step will go over uploading metrics to entities.
Upload Metrics
Get and upload metrics to resources using the Metrics API in the REST API for Oracle Management Cloud.
Uploading can be done synchronous or asynchronous by defining the async parameter in the path. The response will contain a status link to get the status of the upload. Uploading multiple metrics for multiple entities and multiple collection times can be done in one request.
Create a new JSON file called metricsEntity001.json and paste the following:
[
{
"entityType": "MyHostType",
"entityName": "MyHostEntity001",
"collectionTime": "2018-10-11T13:14:15.001Z",
"dimension": {
"cpuId": "0"
},
"metric": "cpuUser",
"value": 20
},
{
"entityType": "MyHostType",
"entityName": "MyHostEntity001",
"collectionTime": "2018-10-11T13:14:15.001Z",
"dimension": {
"cpuId": "0"
},
"metric": "cpuSystem",
"value": 50
},
{
"entityType": "MyHostType",
"entityName": "MyHostEntity001",
"collectionTime": "2018-10-11T13:14:15.001Z",
"dimension": {
"cpuId": "0"
},
"metric": "cpuIdle",
"value": 30
},
{
"entityType": "MyHostType",
"entityName": "MyHostEntity001",
"collectionTime": "2018-10-11T13:14:15.001Z",
"dimension": {
"cpuId": "1"
},
"metric": "cpuUser",
"value": 10
},
{
"entityType": "MyHostType",
"entityName": "MyHostEntity001",
"collectionTime": "2018-10-11T13:14:15.001Z",
"dimension": {
"cpuId": "1"
},
"metric": "cpuSystem",
"value": 5
},
{
"entityType": "MyHostType",
"entityName": "MyHostEntity001",
"collectionTime": "2018-10-11T13:14:15.001Z",
"dimension": {
"cpuId": "1"
},
"metric": "cpuIdle",
"value": 85
}
]The following cURL call will upload some metrics to MyHostEntity001. These metrics contain information for every metric in dimension cpuId 0 and 1.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/metrics?async=false -d "@metricsEntity001.json"
List metric timeseries
REST API for Oracle Management Cloud offers various ways to query data points in your metrics.
Time series can be queried by raw data points, aggregated data over a time interval in seconds, or split interval periods in seconds. All time must be written following the format: UTC YYYY-MM-DDTHH:MM:SS.SSSZ
Supported Functions:
The following are the supported aggregated functions that you can use to query:
- STDDEV
- MAX
- MEDIAN
- MIN
- PERCENTILE_DISC
- LAST_VALUE
- FIRST_VALUE
- AVG
Get all time points
The following cURL call will print all data uploaded from MyHostEntity001 between October 10 and October 20.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/metrics?startTime=2018-10-10T12:00:00.000Z&endTime=2018-10-20T12:00:00.000Z&entityType=MyHostType&entityName=MyHostEntity001
Get all time points for cpuIdle in cpuId = 0
The following cURL call will print all data from cpuIdle in dimension cpuId=0 uploaded from MyHostEntity001 between October 10 and October 20.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/metrics?startTime=2018-10-10T12:00:00.000Z&endTime=2018-10-20T12:00:00.000Z&entityType=MyHostType&entityName=MyHostEntity001&dimension=cpuId=0&metric=cpuIdle
Get the average cpuIdle in cpuId = 0
The following cURL call will print the average cpuIdle value in dimension cpuId=0 uploaded from MyHostEntity001 between October 10 and October 20.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/metrics?startTime=2018-10-10T12:00:00.000Z&endTime=2018-10-20T12:00:00.000Z&entityType=MyHostType&entityName=MyHostEntity001&dimension=cpuId=0&metric=cpuIdle&function=AVG
Get the average cpuIdle in cpuId = 0 divided into intervals of 300 seconds
The following cURL call will print the average cpuIdle value in dimension cpuId=0 calculated in intervals of 300 seconds uploaded from MyHostEntity001 between October 10 and October 20.
curl -u USER:PASSWORD -X POST -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/metrics?startTime=2018-10-10T12:00:00.000Z&endTime=2018-10-20T12:00:00.000Z&entityType=MyHostType&entityName=MyHostEntity001&dimension=cpuId=0&metric=cpuIdle&function=AVG&period=300
Delete Entities
Delete your Entities and Groups using the Delete call.
Delete MyHostEntity001 and MyApplication
curl -u USER:PASSWORD -X DELETE -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities?entityType=MyHostType&entityName=MyHostEntity001
curl -u USER:PASSWORD -X DELETE -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/entities?entityType=MyApplicationType&entityName=MyApplication
Delete MyFooGroup
curl -u USER:PASSWORD -X DELETE -H "Content-Type: application/json" https://OMC_URL:PORT/serviceapi/entityModel/uds/groups/MyFooGroup