Jump to

• Request
• Response
• Examples

Get last known positions of resources

get

/rest/ofscCore/v1/resources/custom-actions/lastKnownPositions

This operation retrieves the last known position of the specified resources.

This operation is subject to the following conditions:

• Number of Resources Returned:
  • If 'resources' parameter is used, then the maximum number of resources with positions that can be retrieved in a single response is 300.
  • If 'resources' parameter is NOT used, then:
    • The system tries to get all resources with last known position available.
    • The maximum number of resources with positions that can be retrieved in a single response is 100000.
    • The resources that have no last known position are not included in the response.
    • The maximum number of 'Get last known positions of resources' requests that can be sent simultaneously without 'resources' parameter is three. Any additional requests are rejected with an error message.
• Response Size: The response for a single request is limited to 20 MB. If the response size is close to 20 MB, the operation returns fewer resources with positions than available, and the response contains the 'hasMore' flag set to 'true'. This flag indicates that there are more resources with positions to be returned. In this case, a new request with 'offset' parameter set to the last returned item count is sent.
• Operation Run Time: The maximum run time for a single operation is 30 seconds. When the 30-second time limit is reached, the operation returns fewer resources with positions than available and the response contains the 'hasMore' flag set to 'true'. This flag indicates that there are more resources with positions to be returned. In this case, a new request with 'offset' parameter set to the last returned item count is sent. If the time limit has exceeded before any resources with positions are included in the response (for example, due to slow storage response), an error is returned.

Request

Query Parameters

• offset: integer
  The record number from which the retrieval starts. The default value is zero. The value zero indicates that the retrieval will start from the beginning of the collection. The parameter is ignored if Resources parameter is specified
• resources: array[string]
  Collection Format: csv

  The comma-separated string of resource IDs as per swagger CSV format. For example, john.smith,scott.tiger.

Back to Top

Response

Supported Media Types

• application/json

200 Response

This section describes the 200 status response for this operation.

Body ()

Root Schema : Last known Positions of the Resources

Type: object

Title: Last known Positions of the Resources

The collection of the last known positions of the specified resources. The collection also includes error information.

Show Source

• hasMore: boolean
  Title: Has More Results

  Contains one of the following values: true or false. If true, then there are more results that can be retrieved with successive paging requests. If false or if the value is not present, then there are no more results or this is the final page.
• items: array Items
  Title: Items

  The array of resource IDs with their last known position information.
• offset: integer
  Title: Offset

  The offset value specified in the request.
• totalResults: integer
  Title: Total Results

  The total number of items returned by the operation.

{
    "title":"Last known Positions of the Resources",
    "description":"The collection of the last known positions of the specified resources. The collection also includes error information.",
    "type":"object",
    "properties":{
        "items":{
            "items":{
                "$ref":"#/definitions/lastKnownResourcesPositionsResponsePositionSchema"
            },
            "type":"array",
            "description":"The array of resource IDs with their last known position information.",
            "title":"Items"
        },
        "totalResults":{
            "type":"integer",
            "description":"The total number of items returned by the operation.",
            "title":"Total Results"
        },
        "offset":{
            "type":"integer",
            "description":"The offset value specified in the request.",
            "title":"Offset"
        },
        "hasMore":{
            "type":"boolean",
            "title":"Has More Results",
            "description":"Contains one of the following values: true or false. If true, then there are more results that can be retrieved with successive paging requests. If false or if the value is not present, then there are no more results or this is the final page."
        }
    }
}

Nested Schema : Items

Type: array

Title: Items

The array of resource IDs with their last known position information.

Show Source

• Array of: object Last Known Position
  Title: Last Known Position

  The last known position of the resource.

{
    "items":{
        "$ref":"#/definitions/lastKnownResourcesPositionsResponsePositionSchema"
    },
    "type":"array",
    "description":"The array of resource IDs with their last known position information.",
    "title":"Items"
}

Nested Schema : Last Known Position

Type: object

Title: Last Known Position

The last known position of the resource.

Show Source

• errorMessage: string
  Title: Error Message

  The error message corresponding to the resource IDs.
• lat: number
  Title: Latitude

  Minimum Value: -90

  Maximum Value: 90

  The latitude coordinate (in degrees) of the position. A maximum of five digits after the decimal point are returned.
• lng: number
  Title: Longitude

  Minimum Value: -180

  Maximum Value: 180

  The longitude coordinate (in degrees) of the position. A maximum of five digits after the decimal point are returned.
• resourceId: string
  Title: Resource ID

  The external identifier of the resource.
• time: string(timestamp-date-time-iso8601)
  Title: Time

  The date in the Internet Date-Time format. For example, 2018-06-27T06:06:05+0000.

{
    "title":"Last Known Position",
    "description":"The last known position of the resource.",
    "type":"object",
    "properties":{
        "resourceId":{
            "type":"string",
            "description":"The external identifier of the resource.",
            "title":"Resource ID"
        },
        "time":{
            "type":"string",
            "description":"The date in the Internet Date-Time format. For example, 2018-06-27T06:06:05+0000.",
            "title":"Time",
            "format":"timestamp-date-time-iso8601"
        },
        "lat":{
            "type":"number",
            "minimum":"-90",
            "maximum":"90",
            "description":"The latitude coordinate (in degrees) of the position.  A maximum of five digits after the decimal point are returned.",
            "title":"Latitude"
        },
        "lng":{
            "type":"number",
            "minimum":"-180",
            "maximum":"180",
            "description":"The longitude coordinate (in degrees) of the position.  A maximum of five digits after the decimal point are returned.",
            "title":"Longitude"
        },
        "errorMessage":{
            "type":"string",
            "description":"The error message corresponding to the resource IDs.",
            "title":"Error Message"
        }
    }
}

Default Response

This section describes the default error response for this operation.

Body ()

Root Schema : Error

Type: object

Show Source

• detail: string
  The detailed description of this error.
• status: string
  The HTTP status code of this error.
• title(required): string
  The brief description of this error.
• type(required): string
  The URL of the web page containing more details about this error.

{
    "properties":{
        "type":{
            "type":"string",
            "description":"The URL of the web page containing more details about this error."
        },
        "title":{
            "type":"string",
            "description":"The brief description of this error."
        },
        "status":{
            "type":"string",
            "description":"The HTTP status code of this error."
        },
        "detail":{
            "type":"string",
            "description":"The detailed description of this error."
        }
    },
    "required":[
        "type",
        "title"
    ]
}

Back to Top

Examples

The following example shows how to retrieve the last known position of the specified resources by submitting a GET request on the REST resource using cURL:

cURL command Example

curl -X GET \
  https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/resources/custom-actions/lastKnownPositions?resources=get_position1,get_position2,get_position3,not_existing_id \
  -H 'Authorization: Bearer eyJ0eXAiO...rest of the access token skipped for brevity'

Response Header Example

The following shows an example of the response header.

HTTP/1.1 200 OK
Server: nginx/1.2.7
Date: Wed, 27 Jun 2018 12:44:50 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive

Response Body Example

The following shows an example of the response body in JSON format.

{
    "totalResults": 4,
    "items": [
        {
            "resourceId": "not_existing_id",
            "errorMessage": "Resource not found"
        },
        {
            "resourceId": "get_position1",
            "time": "2018-06-27T06:05:18+0000",
            "lat": 49.98106,
            "lng": 36.28188
        },
        {
            "resourceId": "get_position2",
            "time": "2018-06-27T06:06:05+0000",
            "lat": 49.98206,
            "lng": 36.28288
        },
        {
            "resourceId": "get_position3",
            "errorMessage": "Last known position is not found for resource"
        }
    ],
    "links": [
        {
            "rel": "canonical",
            "href": "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/resources/custom-actions/lastKnownPositions?resources=get_position1%2Cget_position2%2Cget_position3%2Cnot_existing_id"
        }
    ]
}

Back to Top