Share via

Iot Hub Resource - Test Route

Service:
IoT Hub
API Version:
2023-06-30

Test the new route for this Iot Hub

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{iotHubName}/routing/routes/$testnew?api-version=2023-06-30

URI Parameters

Name In Required Type Description
iotHubName
 path True

string

IotHub to be tested
resourceGroupName
 path True

string

resource group which Iot Hub belongs to
subscriptionId
 path True

string

The subscription identifier.
api-version
 query True

string

The version of the API.

Request Body

Name Required Type Description
route True

RouteProperties

Route properties
message

RoutingMessage

Routing message
twin

RoutingTwin

Routing Twin Reference

Responses

Name Type Description
200 OK

TestRouteResult

OK
Other Status Codes

ErrorDetails

DefaultErrorResponse

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

IotHubResource_TestRoute

Sample request

POST https://management.azure.com/subscriptions/91d12660-3dec-467a-be2a-213b5544ddc0/resourceGroups/myResourceGroup/providers/Microsoft.Devices/IotHubs/testHub/routing/routes/$testnew?api-version=2023-06-30

{
  "message": {
    "body": "Body of message",
    "appProperties": {
      "key1": "value1"
    },
    "systemProperties": {
      "key1": "value1"
    }
  },
  "route": {
    "name": "Routeid",
    "source": "DeviceMessages",
    "endpointNames": [
      "id1"
    ],
    "isEnabled": true
  }
}

Sample response

Status code:
200 
{
  "result": "false",
  "details": {
    "compilationErrors": [
      {
        "message": "string response",
        "severity": "error",
        "location": {
          "start": {
            "line": 12,
            "column": 12
          },
          "end": {
            "line": 12,
            "column": 24
          }
        }
      }
    ]
  }
}

Definitions

Name Description
ErrorDetails

Error details.
Properties
RouteCompilationError

Compilation error when evaluating route
RouteErrorPosition

Position where the route error happened
RouteErrorRange

Range of route errors
RouteErrorSeverity

Severity of the route error
RouteProperties

The properties of a routing rule that your IoT hub uses to route messages to endpoints.
RoutingMessage

Routing message
RoutingSource

The source that the routing rule is to be applied to, such as DeviceMessages.
RoutingTwin

Twin reference input parameter. This is an optional parameter
TestResultStatus

Result of testing route
TestRouteInput

Input for testing route
TestRouteResult

Result of testing one route
TestRouteResultDetails

Detailed result of testing a route

ErrorDetails

Object

Error details.

Name Type Description
code

string

The error code.
details

string

The error details.
httpStatusCode

string

The HTTP status code.
message

string

The error message.

Properties

Object
Name Type Description
desired

object

Twin desired properties
reported

object

Twin desired properties

RouteCompilationError

Object

Compilation error when evaluating route

Name Type Description
location

RouteErrorRange

Location where the route error happened
message

string

Route error message
severity

RouteErrorSeverity

Severity of the route error

RouteErrorPosition

Object

Position where the route error happened

Name Type Description
column

integer (int32)

Column where the route error happened
line

integer (int32)

Line where the route error happened

RouteErrorRange

Object

Range of route errors

Name Type Description
end

RouteErrorPosition

End where the route error happened
start

RouteErrorPosition

Start where the route error happened

RouteErrorSeverity

Enumeration

Severity of the route error

Value Description
error
warning

RouteProperties

Object

The properties of a routing rule that your IoT hub uses to route messages to endpoints.

Name Type Description
condition

string

The condition that is evaluated to apply the routing rule. If no condition is provided, it evaluates to true by default. For grammar, see: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-query-language
endpointNames

string[]

The list of endpoints to which messages that satisfy the condition are routed. Currently only one endpoint is allowed.
isEnabled

boolean

Used to specify whether a route is enabled.
name

string

pattern: ^[A-Za-z0-9-._]{1,64}$

The name of the route. The name can only include alphanumeric characters, periods, underscores, hyphens, has a maximum length of 64 characters, and must be unique.
source

RoutingSource

The source that the routing rule is to be applied to, such as DeviceMessages.

RoutingMessage

Object

Routing message

Name Type Description
appProperties

object

App properties
body

string

Body of routing message
systemProperties

object

System properties

RoutingSource

Enumeration

The source that the routing rule is to be applied to, such as DeviceMessages.

Value Description
Invalid
DeviceMessages
TwinChangeEvents
DeviceLifecycleEvents
DeviceJobLifecycleEvents
DeviceConnectionStateEvents

RoutingTwin

Object

Twin reference input parameter. This is an optional parameter

Name Type Description
properties

Properties

tags

object

Twin Tags

TestResultStatus

Enumeration

Result of testing route

Value Description
undefined
false
true

TestRouteInput

Object

Input for testing route

Name Type Description
message

RoutingMessage

Routing message
route

RouteProperties

Route properties
twin

RoutingTwin

Routing Twin Reference

TestRouteResult

Object

Result of testing one route

Name Type Description
details

TestRouteResultDetails

Detailed result of testing route
result

TestResultStatus

Result of testing route

TestRouteResultDetails

Object

Detailed result of testing a route

Name Type Description
compilationErrors

RouteCompilationError[]

JSON-serialized list of route compilation errors