Microsoft IoTHub API

Microsoft IoTHub API Reference

Microsoft IoTHub API Examples

Create the bearer_token and store in a file in a secure local directory with 0600 permissions.

IoTHub GDR Creation

The iothubgdr endpoint allows to import all devices from selected Azure IoT Hub into RKVST.

Define the iothubgdr parameters and store in /path/to/jsonfile:

{
    "display_name": "RKVST",
    "secret": "Endpoint=sb://iothub-ns-test-org-1-1637462-0dd952fad8.servicebus.windows.net/;SharedAccessKeyName=iothubowner;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx;EntityPath=test-org-1",
    "arc_home_location_identity": "locations/47b575c0-ff0f-11e9-8f0b-362b9e155667"
}

And post to the endpoint:

curl -v -X POST \
    -H "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.rkvst.io/archivist/v2/iothubgdr

You should see the following responses:

{
    "identity": "iothubgdr/08838336-c357-460d-902a-3aba9528dd22",
    "done": false,
    "timestamp_accepted": "2019-11-07T15:31:49Z",
    "timestamp_finished": null,
    "result": {
        "display_name": "RKVST",
        "number_assets_imported": 0,
        "arc_home_location_identity": "locations/47b575c0-ff0f-11e9-8f0b-362b9e155667",
        "status": "STATUS_PENDING"
    }
}

Or in case of error:

{
    "identity": "iothubgdr/08838336-c357-460d-902a-3aba9528dd22",
    "done": true,
    "timestamp_accepted": "2019-11-07T15:31:49Z",
    "timestamp_finished": "2019-11-07T15:31:55Z",
    "error": {
        "display_name": "RKVST",
        "number_assets_imported": 0,
        "arc_home_location_identity": "locations/47b575c0-ff0f-11e9-8f0b-362b9e155667",
        "error_message": "invalid secret provided"
    }
}

IoTHub GDR Management

The iothubgdr endpoint allows to query and manage recent imports.

Listing All Imports

curl -v -X GET \
    -H "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    https://app.rkvst.io/archivist/v2/iothubgdr

This call will respond with a list containing all known imports. Individual items in list are identical to create Responses

Listing Specific Imports

To get specific import details you need the identity of the import, for example:

iothubgdr/47b58286-ff0f-11e9-8f0b-362b9e155667

Which can be used in the following request following request:

curl -v -X GET \
    -H "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    https://app.rkvst.io/archivist/v2/iothubgdr/47b58286-ff0f-11e9-8f0b-362b9e155667

Cancel IoTHub GDR Import Job

To cancel running import issue the following request:

curl -v -X POST \
    -H "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    https://app.rkvst.io/archivist/v2/iothubgdr/47b58286-ff0f-11e9-8f0b-362b9e155667:cancel

The response status should be set to STATUS_CANCELLED.

Delete an Import

To delete an import issue the following request:

curl -v -X DELETE \
    -H "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    https://app.rkvst.io/archivist/v2/iothubgdr/47b58286-ff0f-11e9-8f0b-362b9e155667

The import will be deleted from tracked imports but the underlying job will not stop. To stop the job cancel it before deleting.

Response to successful deletion is empty {}.

Microsoft IoTHub OpenAPI Docs

API to manage iot hub connections.

get  /archivist/v2/iothubgdr

List IoTHub GDR connections.

Description: Returns a list of IoTHub GDR connections

[
  {
    "done": "true",
    "identity": "iothubgdr/14e7f1c2-23ba-5642-9ce0-ffc3563da452",
    "result": {
      "arc_home_location_identity": "locations/25f812d3-10ab-4451-8bd1-fb02454c9361",
      "display_name": "My Company IoT Hub",
      "number_assets_imported": 66,
      "status": "STATUS_FINISHED"
    },
    "timestamp_accepted": "2019-11-27T14:44:19Z",
    "timestamp_finished": "2019-11-28T14:45:29Z"
  },
  {
    "done": "true",
    "identity": "iothubgdr/25f8a2d3-34cb-4531-8dc1-dcc4524db521",
    "result": {
      "arc_home_location_identity": "locations/15bb2ca4-21bc-5427-778c-d2ab6ddc1452",
      "display_name": "My Other Company IoT Hub",
      "number_assets_imported": 42,
      "status": "STATUS_CANCELLED"
    },
    "timestamp_accepted": "2019-11-29T12:54:56Z",
    "timestamp_finished": "2019-11-30T09:15:39Z"
  }
]
Response Parameter Type Description
operations array Long running operation
Responses Description
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to view Event.
defaultAn unexpected error response.

post  /archivist/v2/iothubgdr

Create an IoTHub GDR connection.

Description: Create an IoTHub GDR connection.

{
  "arc_home_location_identity": "locations/25f812d3-10ab-4451-8bd1-fb02454c9361",
  "display_name": "My Company IoT Hub",
  "secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
Parameter Type Description
arc_home_location_identity string Identity of locationas inlocations/add30235-1424-4fda-840a-d5ef82c4c96f`
display_name string display name for this import
secret string secret used to connect to IoT Hub

{
  "done": "true",
  "identity": "iothubgdr/14e7f1c2-23ba-5642-9ce0-ffc3563da452",
  "result": {
    "arc_home_location_identity": "locations/25f812d3-10ab-4451-8bd1-fb02454c9361",
    "display_name": "My Company IoT Hub",
    "number_assets_imported": 66,
    "status": "STATUS_FINISHED"
  },
  "timestamp_accepted": "2019-11-27T14:44:19Z",
  "timestamp_finished": "2019-11-28T14:45:29Z"
}
Response Parameter Type Description
done boolean indicates if import is still running
error
identity string unique identity of this operations
result
timestamp_accepted string time when import has been accepted by the API
timestamp_finished string time import finished
Responses Description
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to view Event.
defaultAn unexpected error response.

delete  /archivist/v2/iothubgdr/{uuid}

Delete an IoTHub GDR connection.

Description: Delete an IoTHub GDR connection.

Responses Description
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to view Event.
404Returned when the IotHubGDR does not exist.
defaultAn unexpected error response.

get  /archivist/v2/iothubgdr/{uuid}

Retrieve an IoTHub GDR connection.

Description: Retrieve an IoTHub GDR connection.

{
  "done": "true",
  "identity": "iothubgdr/14e7f1c2-23ba-5642-9ce0-ffc3563da452",
  "result": {
    "arc_home_location_identity": "locations/25f812d3-10ab-4451-8bd1-fb02454c9361",
    "display_name": "My Company IoT Hub",
    "number_assets_imported": 66,
    "status": "STATUS_FINISHED"
  },
  "timestamp_accepted": "2019-11-27T14:44:19Z",
  "timestamp_finished": "2019-11-28T14:45:29Z"
}
Response Parameter Type Description
done boolean indicates if import is still running
error
identity string unique identity of this operations
result
timestamp_accepted string time when import has been accepted by the API
timestamp_finished string time import finished
Responses Description
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to view Event.
404Returned when the IotHubGDR does not exist.
defaultAn unexpected error response.

post  /archivist/v2/iothubgdr/{uuid}:cancel

Cancel an IoTHub GDR connection.

Description: Cancel an IoTHub GDR connection.

{
  "done": "true",
  "identity": "iothubgdr/14e7f1c2-23ba-5642-9ce0-ffc3563da452",
  "result": {
    "arc_home_location_identity": "locations/25f812d3-10ab-4451-8bd1-fb02454c9361",
    "display_name": "My Company IoT Hub",
    "number_assets_imported": 66,
    "status": "STATUS_FINISHED"
  },
  "timestamp_accepted": "2019-11-27T14:44:19Z",
  "timestamp_finished": "2019-11-28T14:45:29Z"
}
Response Parameter Type Description
done boolean indicates if import is still running
error
identity string unique identity of this operations
result
timestamp_accepted string time when import has been accepted by the API
timestamp_finished string time import finished
Responses Description
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to view Event.
404Returned when the IotHubGDR does not exist.
defaultAn unexpected error response.

Edit this page on GitHub