Iot Hub Resource - Create Or Update

Service:
IoT Hub
API Version:
2017-01-19

Create or update the metadata of an IoT hub.

Create or update the metadata of an Iot hub. The usual pattern to modify a property is to retrieve the IoT hub metadata and security metadata, and then combine them with the modified values in a new body to update the IoT hub.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}?api-version={api-version}

URI Parameters

Name In Required Type Description
subscriptionId
 path True
  • string

The subscription identifier.
resourceGroupName
 path True
  • string

The name of the resource group that contains the IoT hub.
resourceName
 path True
  • string

The name of the IoT hub to create or update.
api-version
 query True
  • string

The version of the API.

Request Body

Name Required Type Description
etag
  • string

The Etag field is not required. If it is provided in the response body, it must also be provided as a header per the normal ETag convention.
location
  • string

The resource location.
properties

The properties of an IoT hub.
resourcegroup True
  • string

The name of the resource group that contains the IoT hub. A resource group name uniquely identifies the resource group within the subscription.
sku

Information about the SKU of the IoT hub.
subscriptionid True
  • string

The subscription identifier.
tags
  • <string, string>

The resource tags.

Responses

Name Type Description
201 Created

This is a long running operation. The operation returns a 201 if the validation is complete. The response includes an Azure-AsyncOperation header that contains a status URL. Clients are expected to poll the status URL for the status of the operation. If successful, the operation returns HTTP status code of 201 (OK).
200 OK

This is returned as a response to the status polling request for the create or update operation. The body contains the resource representation that indicates a transitional provisioning state.
Other Status Codes

DefaultErrorResponse

Definitions

CloudToDeviceProperties

The IoT hub cloud-to-device messaging properties.
ErrorDetails
FallbackRouteProperties

The properties of the route that is used as a fall-back route when none of the conditions specified in the 'routes' section are met. This is an optional parameter. When this property is not set, the messages which do not meet any of the conditions specified in the 'routes' section get routed to the built-in eventhub endpoint.
FeedbackProperties

The properties of the feedback queue for cloud-to-device messages.
IotHubDescription
IotHubProperties

The properties of an IoT hub.
IotHubSkuInfo

Information about the SKU of the IoT hub.
IpFilterRule

The IP filter rules for the IoT hub.
OperationsMonitoringProperties

The operations monitoring properties for the IoT hub. The possible keys to the dictionary are Connections, DeviceTelemetry, C2DCommands, DeviceIdentityOperations, FileUploadOperations, Routes, D2CTwinOperations, C2DTwinOperations, TwinQueries, JobsOperations, DirectMethods.
RouteProperties

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

The properties related to the custom endpoints to which your IoT hub routes messages based on the routing rules. A maximum of 10 custom endpoints are allowed across all endpoint types for paid hubs and only 1 custom endpoint is allowed across all endpoint types for free hubs.
RoutingEventHubProperties

The properties related to an event hub endpoint.
RoutingProperties

The routing related properties of the IoT hub. See: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messaging
RoutingServiceBusQueueEndpointProperties

The properties related to service bus queue endpoint types.
RoutingServiceBusTopicEndpointProperties

The properties related to service bus topic endpoint types.
SharedAccessSignatureAuthorizationRule

The properties of an IoT hub shared access policy.

The IoT hub cloud-to-device messaging properties.

Name Type Description
defaultTtlAsIso8601
  • string
    duration

The default time to live for cloud-to-device messages in the device queue. See: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messaging#cloud-to-device-messages.
feedback

The properties of the feedback queue for cloud-to-device messages.
maxDeliveryCount
  • integer
    int32

The max delivery count for cloud-to-device messages in the device queue. See: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messaging#cloud-to-device-messages.
Name Type Description
Code
  • string

The error code.
Details
  • string

The error details.
HttpStatusCode
  • string

The HTTP status code.
Message
  • string

The error message.

The properties of the route that is used as a fall-back route when none of the conditions specified in the 'routes' section are met. This is an optional parameter. When this property is not set, the messages which do not meet any of the conditions specified in the 'routes' section get routed to the built-in eventhub endpoint.

Name Type Description
condition
  • string

The condition which is evaluated in order to apply the fallback route. If the condition is not provided it will evaluate 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 the messages that satisfy the condition are routed to. Currently only 1 endpoint is allowed.
isEnabled
  • boolean

Used to specify whether the fallback route is enabled or not.
source
  • enum:
    • DeviceMessages

The source to which the routing rule is to be applied to. e.g. DeviceMessages

The properties of the feedback queue for cloud-to-device messages.

Name Type Description
lockDurationAsIso8601
  • string
    duration

The lock duration for the feedback queue. See: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messaging#cloud-to-device-messages.
maxDeliveryCount
  • integer
    int32

The number of times the IoT hub attempts to deliver a message on the feedback queue. See: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messaging#cloud-to-device-messages.
ttlAsIso8601
  • string
    duration

The period of time for which a message is available to consume before it is expired by the IoT hub. See: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messaging#cloud-to-device-messages.
Name Type Description
etag
  • string

The Etag field is not required. If it is provided in the response body, it must also be provided as a header per the normal ETag convention.
id
  • string

The resource identifier.
location
  • string

The resource location.
name
  • string

The resource name.

Regex pattern: ^(?![0-9]+$)(?!-)[a-zA-Z0-9-]{2,49}[a-zA-Z0-9]$
properties

The properties of an IoT hub.
resourcegroup
  • string

The name of the resource group that contains the IoT hub. A resource group name uniquely identifies the resource group within the subscription.
sku

Information about the SKU of the IoT hub.
subscriptionid
  • string

The subscription identifier.
tags
  • <string, string>

The resource tags.
type
  • string

The resource type.

The properties of an IoT hub.

Name Type Description
authorizationPolicies

The shared access policies you can use to secure a connection to the IoT hub.
cloudToDevice

The IoT hub cloud-to-device messaging properties.
comments
  • string

Comments.
enableFileUploadNotifications
  • boolean

If True, file upload notifications are enabled.
eventHubEndpoints
  • <string, object>

The Event Hub-compatible endpoint properties. The possible keys to this dictionary are events and operationsMonitoringEvents. Both of these keys have to be present in the dictionary while making create or update calls for the IoT hub.
features
  • enum:
    • None
    • DeviceManagement

The capabilities and features enabled for the IoT hub.
hostName
  • string

The name of the host.
ipFilterRules

The IP filter rules.
messagingEndpoints
  • <string, object>

The messaging endpoint properties for the file upload notification queue.
operationsMonitoringProperties

The operations monitoring properties for the IoT hub. The possible keys to the dictionary are Connections, DeviceTelemetry, C2DCommands, DeviceIdentityOperations, FileUploadOperations, Routes, D2CTwinOperations, C2DTwinOperations, TwinQueries, JobsOperations, DirectMethods.
provisioningState
  • string

The provisioning state.
routing

The routing related properties of the IoT hub. See: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messaging
storageEndpoints
  • <string, object>

The list of Azure Storage endpoints where you can upload files. Currently you can configure only one Azure Storage account and that MUST have its key as $default. Specifying more than one storage account causes an error to be thrown. Not specifying a value for this property when the enableFileUploadNotifications property is set to True, causes an error to be thrown.

Information about the SKU of the IoT hub.

Name Type Description
capacity
  • integer
    int64

The number of provisioned IoT Hub units. See: https://docs.microsoft.com/azure/azure-subscription-service-limits#iot-hub-limits.
name
  • enum:
    • F1
    • S1
    • S2
    • S3

The name of the SKU.
tier
  • enum:
    • Free
    • Standard

The billing tier for the IoT hub.

The IP filter rules for the IoT hub.

Name Type Description
action
  • enum:
    • Accept
    • Reject

The desired action for requests captured by this rule.
filterName
  • string

The name of the IP filter rule.
ipMask
  • string

A string that contains the IP address range in CIDR notation for the rule.

The operations monitoring properties for the IoT hub. The possible keys to the dictionary are Connections, DeviceTelemetry, C2DCommands, DeviceIdentityOperations, FileUploadOperations, Routes, D2CTwinOperations, C2DTwinOperations, TwinQueries, JobsOperations, DirectMethods.

Name Type Description
events
  • <string, string>

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

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.

Regex pattern: ^[A-Za-z0-9-._]{1,64}$
source
  • enum:
    • DeviceMessages
    • TwinChangeEvents
    • DeviceLifecycleEvents
    • DeviceJobLifecycleEvents

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

The properties related to the custom endpoints to which your IoT hub routes messages based on the routing rules. A maximum of 10 custom endpoints are allowed across all endpoint types for paid hubs and only 1 custom endpoint is allowed across all endpoint types for free hubs.

Name Type Description
eventHubs

The list of Event Hubs endpoints that IoT hub routes messages to, based on the routing rules. This list does not include the built-in Event Hubs endpoint.
serviceBusQueues

The list of Service Bus queue endpoints that IoT hub routes the messages to, based on the routing rules.
serviceBusTopics

The list of Service Bus topic endpoints that the IoT hub routes the messages to, based on the routing rules.

The properties related to an event hub endpoint.

Name Type Description
connectionString
  • string

The connection string of the event hub endpoint.

name
  • string

The name of the event hub endpoint. The name can only include alphanumeric characters, periods, underscores, hyphens and has a maximum length of 64 characters. The following names are reserved; events, operationsMonitoringEvents, fileNotifications, $default. Endpoint names must be unique across endpoint types.

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

The name of the resource group of the event hub endpoint.
subscriptionId
  • string

The subscription identifier of the event hub endpoint.

The routing related properties of the IoT hub. See: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messaging

Name Type Description
endpoints

The properties related to the custom endpoints to which your IoT hub routes messages based on the routing rules. A maximum of 10 custom endpoints are allowed across all endpoint types for paid hubs and only 1 custom endpoint is allowed across all endpoint types for free hubs.
fallbackRoute

The properties of the route that is used as a fall-back route when none of the conditions specified in the 'routes' section are met. This is an optional parameter. When this property is not set, the messages which do not meet any of the conditions specified in the 'routes' section get routed to the built-in eventhub endpoint.
routes

The list of user-provided routing rules that the IoT hub uses to route messages to built-in and custom endpoints. A maximum of 100 routing rules are allowed for paid hubs and a maximum of 5 routing rules are allowed for free hubs.

The properties related to service bus queue endpoint types.

Name Type Description
connectionString
  • string

The connection string of the service bus queue endpoint.
name
  • string

The name of the service bus queue endpoint. The name can only include alphanumeric characters, periods, underscores, hyphens and has a maximum length of 64 characters. The following names are reserved; events, operationsMonitoringEvents, fileNotifications, $default. Endpoint names must be unique across endpoint types. The name need not be the same as the actual queue name.

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

The name of the resource group of the service bus queue endpoint.
subscriptionId
  • string

The subscription identifier of the service bus queue endpoint.

The properties related to service bus topic endpoint types.

Name Type Description
connectionString
  • string

The connection string of the service bus topic endpoint.
name
  • string

The name of the service bus topic endpoint. The name can only include alphanumeric characters, periods, underscores, hyphens and has a maximum length of 64 characters. The following names are reserved; events, operationsMonitoringEvents, fileNotifications, $default. Endpoint names must be unique across endpoint types. The name need not be the same as the actual topic name.

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

The name of the resource group of the service bus topic endpoint.
subscriptionId
  • string

The subscription identifier of the service bus topic endpoint.

The properties of an IoT hub shared access policy.

Name Type Description
keyName
  • string

The name of the shared access policy.
primaryKey
  • string

The primary key.
rights
  • enum:
    • RegistryRead
    • RegistryWrite
    • ServiceConnect
    • DeviceConnect
    • RegistryRead, RegistryWrite
    • RegistryRead, ServiceConnect
    • RegistryRead, DeviceConnect
    • RegistryWrite, ServiceConnect
    • RegistryWrite, DeviceConnect
    • ServiceConnect, DeviceConnect
    • RegistryRead, RegistryWrite, ServiceConnect
    • RegistryRead, RegistryWrite, DeviceConnect
    • RegistryRead, ServiceConnect, DeviceConnect
    • RegistryWrite, ServiceConnect, DeviceConnect
    • RegistryRead, RegistryWrite, ServiceConnect, DeviceConnect

The permissions assigned to the shared access policy.
secondaryKey
  • string

The secondary key.