Microsoft Azure POST API

openapi: 3.2.0
info:
  version: 2021-07-02-preview
  title: Microsoft Azure iotHubClient POST API
  description: Use this API to manage the IoT hubs in your Azure subscription.
  x-ms-code-generation-settings:
    header: MICROSOFT_MIT_NO_VERSION
servers:
- url: https://management.azure.com
security:
- azure_auth:
  - user_impersonation
tags:
- name: Post
paths:
  /subscriptions/{subscriptionId}/providers/Microsoft.Devices/checkNameAvailability:
    post:
      tags:
      - Post
      summary: Microsoft Azure Check If An Iot Hub Name Is Available
      description: Check if an IoT hub name is available.
      operationId: microsoftAzureIothubresourceChecknameavailability
      x-ms-examples:
        IotHubResource_CheckNameAvailability:
          $ref: ./examples/checkNameAvailability.json
      parameters:
      - $ref: '#/components/parameters/api-version'
      - $ref: '#/components/parameters/subscriptionId'
      responses:
        '200':
          description: This is a synchronous operation. The body contains a JSON-serialized response that specifies whether the IoT hub name is available. If the name is not available, the body contains the reason.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IotHubNameAvailabilityInfo'
        default:
          description: DefaultErrorResponse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperationInputs'
        description: Set the name parameter in the OperationInputs structure to the name of the IoT hub to check.
        required: true
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{iotHubName}/routing/routes/$testall
  : post:
      tags:
      - Post
      operationId: microsoftAzureIothubresourceTestallroutes
      summary: Microsoft Azure Test All Routes
      description: Test all routes configured in this Iot Hub
      x-ms-examples:
        IotHubResource_TestAllRoutes:
          $ref: ./examples/iothub_testallroutes.json
      parameters:
      - name: iotHubName
        description: IotHub to be tested
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/subscriptionId'
      - name: resourceGroupName
        description: resource group which Iot Hub belongs to
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/api-version'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestAllRoutesResult'
        default:
          description: DefaultErrorResponse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestAllRoutesInput'
        description: Input for testing all routes
        required: true
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{iotHubName}/routing/routes/$testnew
  : post:
      tags:
      - Post
      operationId: microsoftAzureIothubresourceTestroute
      summary: Microsoft Azure Test The New Route
      description: Test the new route for this Iot Hub
      x-ms-examples:
        IotHubResource_TestRoute:
          $ref: ./examples/iothub_testnewroute.json
      parameters:
      - name: iotHubName
        description: IotHub to be tested
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/subscriptionId'
      - name: resourceGroupName
        description: resource group which Iot Hub belongs to
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/api-version'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestRouteResult'
        default:
          description: DefaultErrorResponse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestRouteInput'
        description: Route that needs to be tested
        required: true
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/listkeys
  : post:
      tags:
      - Post
      summary: Microsoft Azure Get The Security Metadata For An Iot Hub For More Information…
      description: 'Get the security metadata for an IoT hub. For more information, see: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-security.'
      operationId: microsoftAzureIothubresourceListkeys
      x-ms-examples:
        IotHubResource_ListKeys:
          $ref: ./examples/iothub_listkeys.json
      parameters:
      - $ref: '#/components/parameters/api-version'
      - $ref: '#/components/parameters/subscriptionId'
      - $ref: '#/components/parameters/resourceGroupName'
      - $ref: '#/components/parameters/resourceName'
      responses:
        '200':
          description: This is a synchronous operation. The body contains a JSON-serialized array of shared access policies, including keys, that you can use to access the IoT hub endpoints.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedAccessSignatureAuthorizationRuleListResult'
        default:
          description: DefaultErrorResponse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
      deprecated: false
      x-ms-pageable:
        nextLinkName: nextLink
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/IotHubKeys/{keyName}/listkeys
  : post:
      tags:
      - Post
      summary: Microsoft Azure Get A Shared Access Policy By Name From An Iot Hub For More…
      description: 'Get a shared access policy by name from an IoT hub. For more information, see: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-security.'
      operationId: microsoftAzureIothubresourceGetkeysforkeyname
      x-ms-examples:
        IotHubResource_GetKeysForKeyName:
          $ref: ./examples/iothub_getkey.json
      parameters:
      - $ref: '#/components/parameters/api-version'
      - $ref: '#/components/parameters/subscriptionId'
      - $ref: '#/components/parameters/resourceGroupName'
      - $ref: '#/components/parameters/resourceName'
      - name: keyName
        in: path
        description: The name of the shared access policy.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: This is a synchronous operation. The body contains a JSON-serialized shared access policy, including keys, that you can use to access one or more IoT hub endpoints.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedAccessSignatureAuthorizationRule'
        default:
          description: DefaultErrorResponse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
      deprecated: false
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/exportDevices
  : post:
      tags:
      - Post
      summary: Microsoft Azure Exports All The Device Identities In The Iot Hub Identity…
      description: 'Exports all the device identities in the IoT hub identity registry to an Azure Storage blob container. For more information, see: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities.'
      operationId: microsoftAzureIothubresourceExportdevices
      x-ms-examples:
        IotHubResource_ExportDevices:
          $ref: ./examples/iothub_exportdevices.json
      parameters:
      - $ref: '#/components/parameters/api-version'
      - $ref: '#/components/parameters/subscriptionId'
      - $ref: '#/components/parameters/resourceGroupName'
      - $ref: '#/components/parameters/resourceName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        default:
          description: DefaultErrorResponse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportDevicesRequest'
        description: The parameters that specify the export devices operation.
        required: true
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/importDevices
  : post:
      tags:
      - Post
      summary: Microsoft Azure Import, Update, Or Delete Device Identities In The Iot Hub…
      description: 'Import, update, or delete device identities in the IoT hub identity registry from a blob. For more information, see: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities.'
      operationId: microsoftAzureIothubresourceImportdevices
      x-ms-examples:
        IotHubResource_ImportDevices:
          $ref: ./examples/iothub_importdevices.json
      parameters:
      - $ref: '#/components/parameters/api-version'
      - $ref: '#/components/parameters/subscriptionId'
      - $ref: '#/components/parameters/resourceGroupName'
      - $ref: '#/components/parameters/resourceName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        default:
          description: DefaultErrorResponse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportDevicesRequest'
        description: The parameters that specify the import devices operation.
        required: true
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{iotHubName}/failover
  : post:
      tags:
      - Post
      operationId: microsoftAzureIothubManualfailover
      summary: Microsoft Azure Manually Initiate A Failover For The Iot Hub To Its Secondary…
      description: Manually initiate a failover for the IoT Hub to its secondary region. To learn more, see https://aka.ms/manualfailover
      x-ms-examples:
        IotHub_ManualFailover:
          $ref: ./examples/IotHub_ManualFailover.json
      x-ms-long-running-operation: true
      parameters:
      - name: iotHubName
        description: Name of the IoT hub to failover
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/subscriptionId'
      - name: resourceGroupName
        description: Name of the resource group containing the IoT hub resource
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/api-version'
      responses:
        '200':
          description: Long running manual failover operation for the IoT hub completed
        '202':
          description: Manual failover initiated
        default:
          description: DefaultErrorResponse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FailoverInput'
        description: Region to failover to. Must be the Azure paired region. Get the value from the secondary location in the locations property. To learn more, see https://aka.ms/manualfailover/region
        required: true
components:
  schemas:
    TestAllRoutesResult:
      description: Result of testing all routes
      type: object
      properties:
        routes:
          description: JSON-serialized array of matched routes
          type: array
          items:
            $ref: '#/components/schemas/MatchedRoute'
    RouteCompilationError:
      description: Compilation error when evaluating route
      type: object
      properties:
        message:
          description: Route error message
          type: string
        severity:
          description: Severity of the route error
          enum:
          - error
          - warning
          type: string
          x-ms-enum:
            name: RouteErrorSeverity
            modelAsString: true
        location:
          description: Location where the route error happened
          $ref: '#/components/schemas/RouteErrorRange'
    TestRouteInput:
      required:
      - route
      description: Input for testing route
      type: object
      properties:
        message:
          description: Routing message
          $ref: '#/components/schemas/RoutingMessage'
        route:
          description: Route properties
          $ref: '#/components/schemas/RouteProperties'
        twin:
          description: Routing Twin Reference
          $ref: '#/components/schemas/RoutingTwin'
    TestRouteResult:
      description: Result of testing one route
      type: object
      properties:
        result:
          description: Result of testing route
          enum:
          - undefined
          - 'false'
          - 'true'
          type: string
          x-ms-enum:
            name: TestResultStatus
            modelAsString: true
        details:
          description: Detailed result of testing route
          $ref: '#/components/schemas/TestRouteResultDetails'
    JobResponse:
      description: The properties of the Job Response object.
      type: object
      properties:
        jobId:
          description: The job identifier.
          type: string
          readOnly: true
        startTimeUtc:
          format: date-time-rfc1123
          description: The start time of the job.
          type: string
          readOnly: true
        endTimeUtc:
          format: date-time-rfc1123
          description: The time the job stopped processing.
          type: string
          readOnly: true
        type:
          description: The type of the job.
          enum:
          - unknown
          - export
          - import
          - backup
          - readDeviceProperties
          - writeDeviceProperties
          - updateDeviceConfiguration
          - rebootDevice
          - factoryResetDevice
          - firmwareUpdate
          type: string
          readOnly: true
          x-ms-enum:
            name: JobType
            modelAsString: true
        status:
          description: The status of the job.
          enum:
          - unknown
          - enqueued
          - running
          - completed
          - failed
          - cancelled
          type: string
          readOnly: true
          x-ms-enum:
            name: JobStatus
            modelAsString: false
        failureReason:
          description: If status == failed, this string containing the reason for the failure.
          type: string
          readOnly: true
        statusMessage:
          description: The status message for the job.
          type: string
          readOnly: true
        parentJobId:
          description: The job identifier of the parent job, if any.
          type: string
          readOnly: true
    ErrorDetails:
      description: Error details.
      type: object
      properties:
        code:
          description: The error code.
          type: string
          readOnly: true
        httpStatusCode:
          description: The HTTP status code.
          type: string
          readOnly: true
        message:
          description: The error message.
          type: string
          readOnly: true
        details:
          description: The error details.
          type: string
          readOnly: true
    ImportDevicesRequest:
      description: Use to provide parameters when requesting an import of all devices in the hub.
      type: object
      properties:
        inputBlobContainerUri:
          description: The input blob container URI.
          type: string
        outputBlobContainerUri:
          description: The output blob container URI.
          type: string
        inputBlobName:
          description: The blob name to be used when importing from the provided input blob container.
          type: string
        outputBlobName:
          description: The blob name to use for storing the status of the import job.
          type: string
        authenticationType:
          description: Specifies authentication type being used for connecting to the storage account.
          enum:
          - keyBased
          - identityBased
          type: string
          x-ms-enum:
            name: AuthenticationType
            modelAsString: true
        identity:
          description: Managed identity properties of storage endpoint for import devices.
          $ref: '#/components/schemas/ManagedIdentity'
        includeConfigurations:
          description: The value indicating whether configurations should be imported.
          type: boolean
        configurationsBlobName:
          description: The blob name to be used when importing configurations from the provided input blob container.
          type: string
      required:
      - inputBlobContainerUri
      - outputBlobContainerUri
    TestRouteResultDetails:
      description: Detailed result of testing a route
      type: object
      properties:
        compilationErrors:
          description: JSON-serialized list of route compilation errors
          type: array
          items:
            $ref: '#/components/schemas/RouteCompilationError'
    RouteErrorRange:
      description: Range of route errors
      type: object
      properties:
        start:
          description: Start where the route error happened
          $ref: '#/components/schemas/RouteErrorPosition'
        end:
          description: End where the route error happened
          $ref: '#/components/schemas/RouteErrorPosition'
    TestAllRoutesInput:
      description: Input for testing all routes
      type: object
      properties:
        routingSource:
          description: Routing source
          enum:
          - Invalid
          - DeviceMessages
          - TwinChangeEvents
          - DeviceLifecycleEvents
          - DeviceJobLifecycleEvents
          - DigitalTwinChangeEvents
          - DeviceConnectionStateEvents
          - MqttBrokerMessages
          type: string
          x-ms-enum:
            name: RoutingSource
            modelAsString: true
        message:
          description: Routing message
          $ref: '#/components/schemas/RoutingMessage'
        twin:
          description: Routing Twin Reference
          $ref: '#/components/schemas/RoutingTwin'
    RouteErrorPosition:
      description: Position where the route error happened
      type: object
      properties:
        line:
          description: Line where the route error happened
          format: int32
          type: integer
        column:
          description: Column where the route error happened
          format: int32
          type: integer
    RoutingTwin:
      description: Twin reference input parameter. This is an optional parameter
      type: object
      properties:
        tags:
          description: Twin Tags
          type: object
        properties:
          properties:
            desired:
              description: Twin desired properties
              type: object
            reported:
              description: Twin desired properties
              type: object
    MatchedRoute:
      description: Routes that matched
      type: object
      properties:
        properties:
          description: Properties of routes that matched
          $ref: '#/components/schemas/RouteProperties'
    SharedAccessSignatureAuthorizationRuleListResult:
      description: The list of shared access policies with a next link.
      type: object
      properties:
        value:
          description: The list of shared access policies.
          type: array
          items:
            $ref: '#/components/schemas/SharedAccessSignatureAuthorizationRule'
        nextLink:
          description: The next link.
          type: string
          readOnly: true
    ExportDevicesRequest:
      description: Use to provide parameters when requesting an export of all devices in the IoT hub.
      type: object
      properties:
        exportBlobContainerUri:
          description: The export blob container URI.
          type: string
        excludeKeys:
          description: The value indicating whether keys should be excluded during export.
          type: boolean
        exportBlobName:
          description: The name of the blob that will be created in the provided output blob container. This blob will contain the exported device registry information for the IoT Hub.
          type: string
        authenticationType:
          description: Specifies authentication type being used for connecting to the storage account.
          enum:
          - keyBased
          - identityBased
          type: string
          x-ms-enum:
            name: AuthenticationType
            modelAsString: true
        identity:
          description: Managed identity properties of storage endpoint for export devices.
          $ref: '#/components/schemas/ManagedIdentity'
        includeConfigurations:
          description: The value indicating whether configurations should be exported.
          type: boolean
        configurationsBlobName:
          description: The name of the blob that will be created in the provided output blob container. This blob will contain the exported configurations for the Iot Hub.
          type: string
      required:
      - exportBlobContainerUri
      - excludeKeys
    RoutingMessage:
      description: Routing message
      type: object
      properties:
        body:
          description: Body of routing message
          type: string
        appProperties:
          description: App properties
          type: object
          additionalProperties:
            type: string
        systemProperties:
          description: System properties
          type: object
          additionalProperties:
            type: string
    FailoverInput:
      description: Use to provide failover region when requesting manual Failover for a hub.
      type: object
      properties:
        failoverRegion:
          description: Region the hub will be failed over to
          type: string
      required:
      - failoverRegion
    OperationInputs:
      description: Input values.
      type: object
      properties:
        name:
          description: The name of the IoT hub to check.
          type: string
      required:
      - name
    ManagedIdentity:
      description: The properties of the Managed identity.
      type: object
      properties:
        userAssignedIdentity:
          type: string
          description: The user assigned identity.
    SharedAccessSignatureAuthorizationRule:
      description: The properties of an IoT hub shared access policy.
      type: object
      properties:
        keyName:
          description: The name of the shared access policy.
          type: string
        primaryKey:
          description: The primary key.
          type: string
        secondaryKey:
          description: The secondary key.
          type: string
        rights:
          description: The permissions assigned to the shared access policy.
          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
          type: string
          x-ms-enum:
            name: AccessRights
            modelAsString: false
      required:
      - keyName
      - rights
    RouteProperties:
      description: The properties of a routing rule that your IoT hub uses to route messages to endpoints.
      type: object
      properties:
        name:
          description: 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.
          type: string
          pattern: ^[A-Za-z0-9-._]{1,64}$
        source:
          description: The source that the routing rule is to be applied to, such as DeviceMessages.
          enum:
          - Invalid
          - DeviceMessages
          - TwinChangeEvents
          - DeviceLifecycleEvents
          - DeviceJobLifecycleEvents
          - DigitalTwinChangeEvents
          - DeviceConnectionStateEvents
          - MqttBrokerMessages
          type: string
          x-ms-enum:
            name: RoutingSource
            modelAsString: true
        condition:
          description: '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'
          type: string
        endpointNames:
          description: The list of endpoints to which messages that satisfy the condition are routed. Currently only one endpoint is allowed.
          minItems: 1
          maxItems: 1
          type: array
          items:
            type: string
        isEnabled:
          description: Used to specify whether a route is enabled.
          type: boolean
      required:
      - name
      - endpointNames
      - source
      - isEnabled
    IotHubNameAvailabilityInfo:
      description: The properties indicating whether a given IoT hub name is available.
      type: object
      properties:
        nameAvailable:
          description: The value which indicates whether the provided name is available.
          type: boolean
          readOnly: true
        reason:
          description: The reason for unavailability.
          enum:
          - Invalid
          - AlreadyExists
          type: string
          readOnly: true
          x-ms-enum:
            name: IotHubNameUnavailabilityReason
            modelAsString: false
        message:
          description: The detailed reason message.
          type: string
  parameters:
    resourceName:
      name: resourceName
      in: path
      description: The name of the IoT hub.
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
    api-version:
      name: api-version
      in: query
      description: The version of the API.
      required: true
      schema:
        type: string
    subscriptionId:
      name: subscriptionId
      in: path
      description: The subscription identifier.
      required: true
      schema:
        type: string
    resourceGroupName:
      name: resourceGroupName
      description: The name of the resource group that contains the IoT hub.
      in: path
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
  securitySchemes:
    azure_auth:
      type: oauth2
      flows:
        implicit:
          scopes:
            user_impersonation: impersonate your user account
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
      description: Azure Active Directory OAuth2 Flow