Device Twin Api

  • Get Device Twin

    Get a device twin.

    Get a device twin. See https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-device-twins for more information.

    Request

    GET /twins/{id}?api-version=2016-11-14

    Properties

    Returns (HTTP Response Codes)

    • 200 response

      OK

      typeDeviceTwinInfo
      • DeviceId

        The deviceId uniquely identifies the device in the IoT hub's identity registry. A case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.

        typestring
      • LastActivityTimeUtc

        The last time the device connected, received or sent a message. In ISO8601 datetime format in UTC, for example, 2015-01-28T16:24:48.789Z. This does not update if the device uses the HTTP/1 protocol to perform messaging operations.

        typeobject
        typeVariantValueDateTime
        • Value

          read onlyTrue
          typedate-time
        • ObjectValue

          read onlyTrue
          typeobject
        • IsNull

          read onlyTrue
          typeboolean
      • IsConnected

        Indicates if the device is currently connected to the IoT hub or not.

        typeboolean
      • LastConnectedTimeUtc

        The last time the device connected to the IoT hub. In ISO8601 datetime format in UTC, for example, 2015-01-28T16:24:48.789Z. This does not update if the device uses the HTTP/1 protocol to perform messaging operations.

        typeobject
        typeVariantValueDateTime
        • Value

          read onlyTrue
          typedate-time
        • ObjectValue

          read onlyTrue
          typeobject
        • IsNull

          read onlyTrue
          typeboolean
      • Version

        Version for device twin, including tags and desired properties

        typeint64
      • Tags

        A JSON document read and written by the solution back end. Tags are not visible to device apps.

        typeobject
      • DesiredProperties

        Used in conjunction with reported properties to synchronize device configuration or condition. Desired properties can only be set by the solution back end and can be read by the device app. The device app can also be notified in real time of changes on the desired properties.

        typeobject
        typeDeviceTwinProperties
        • Version

          Version of device twin properties.

          typeint64
        • Properties

          Properties JSON element.

          typeobject
        • Metadata

          Metadata information for the properties JSON document.

          typeobject
          typeMetadata
          • LastUpdatedUtc

            The last time the properties were updated. In ISO8601 datetime format in UTC, for example, 2015-01-28T16:24:48.789Z.

            typeobject
            typeVariantValueDateTime
            • Value

              read onlyTrue
              typedate-time
            • ObjectValue

              read onlyTrue
              typeobject
            • IsNull

              read onlyTrue
              typeboolean
          • LastUpdatedVersion

            This SHOULD be null for Reported properties metadata and MUST not be null for Desired properties metadata.

            typeint64
          • HasChildren

            True if nested properies are present.

            read onlyTrue
            typeboolean
          • Nested

            Nested properties.

            read onlyTrue
            typeobject
      • ReportedProperties

        Used in conjunction with desired properties to synchronize device configuration or condition. Reported properties can only be set by the device app and can be read and queried by the solution back end.

        typeobject
        typeDeviceTwinProperties
        • Version

          Version of device twin properties.

          typeint64
        • Properties

          Properties JSON element.

          typeobject
        • Metadata

          Metadata information for the properties JSON document.

          typeobject
          typeMetadata
          • LastUpdatedUtc

            The last time the properties were updated. In ISO8601 datetime format in UTC, for example, 2015-01-28T16:24:48.789Z.

            typeobject
            typeVariantValueDateTime
            • Value

              read onlyTrue
              typedate-time
            • ObjectValue

              read onlyTrue
              typeobject
            • IsNull

              read onlyTrue
              typeboolean
          • LastUpdatedVersion

            This SHOULD be null for Reported properties metadata and MUST not be null for Desired properties metadata.

            typeint64
          • HasChildren

            True if nested properies are present.

            read onlyTrue
            typeboolean
          • Nested

            Nested properties.

            read onlyTrue
            typeobject
      • ProvisioningState

        Provisioning state of device twin.

        typeProvisioningState { Creating, Deleting, Active, Deleted }
  • Invoke Device Method

    Invoke a direct method on a device.

    Invoke a direct method on a device. See https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-direct-methods for more information.

    Request

    POST /twins/{id}/methods?api-version=2016-11-14

    Properties

    • api-version

      The version of the API.

      inquery
      requiredTrue
      typestring
    • deviceid

      Invoke a direct method on a device. See https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-direct-methods for more information.

      inpath
      requiredTrue
      typestring
    • directMethodRequest

      Invoke a direct method on a device. See https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-direct-methods for more information.

      inbody
      requiredTrue
      typeCloudToDeviceMethod
      • methodName

        Name of the direct method.

        requiredTrue
        typestring
      • payload

        Payload of the direct method request.

        typeobject
      • responseTimeoutInSeconds

        Maximum time allowed between the device app receiving the direct method request and sending the corresponding response.

        typeint32
      • connectTimeoutInSeconds

        Maximum time allowed to deliver a direct method request if a device is offline.

        typeint32

    Returns (HTTP Response Codes)

    • 200 response

      OK

      typeCloudToDeviceMethodResult
      • status

        Method invocation result status.

        typeint32
      • payload

        Method invocation result payload.

        typeobject
  • Update Device Twin

    Updates tags and desired properties of a device twin.

    Update a device twin. See https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-device-twins for more information.

    Request

    PATCH /twins/{id}?api-version=2016-11-14

    Properties

    • api-version

      The version of the API.

      inquery
      requiredTrue
      typestring
    • deviceTwinInfo

      Update a device twin. See https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-device-twins for more information.

      inbody
      requiredTrue
      typeDeviceTwinInfo
      • DeviceId

        The deviceId uniquely identifies the device in the IoT hub's identity registry. A case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.

        typestring
      • LastActivityTimeUtc

        The last time the device connected, received or sent a message. In ISO8601 datetime format in UTC, for example, 2015-01-28T16:24:48.789Z. This does not update if the device uses the HTTP/1 protocol to perform messaging operations.

        typeobject
        typeVariantValueDateTime
        • Value

          read onlyTrue
          typedate-time
        • ObjectValue

          read onlyTrue
          typeobject
        • IsNull

          read onlyTrue
          typeboolean
      • IsConnected

        Indicates if the device is currently connected to the IoT hub or not.

        typeboolean
      • LastConnectedTimeUtc

        The last time the device connected to the IoT hub. In ISO8601 datetime format in UTC, for example, 2015-01-28T16:24:48.789Z. This does not update if the device uses the HTTP/1 protocol to perform messaging operations.

        typeobject
        typeVariantValueDateTime
        • Value

          read onlyTrue
          typedate-time
        • ObjectValue

          read onlyTrue
          typeobject
        • IsNull

          read onlyTrue
          typeboolean
      • Version

        Version for device twin, including tags and desired properties

        typeint64
      • Tags

        A JSON document read and written by the solution back end. Tags are not visible to device apps.

        typeobject
      • DesiredProperties

        Used in conjunction with reported properties to synchronize device configuration or condition. Desired properties can only be set by the solution back end and can be read by the device app. The device app can also be notified in real time of changes on the desired properties.

        typeobject
        typeDeviceTwinProperties
        • Version

          Version of device twin properties.

          typeint64
        • Properties

          Properties JSON element.

          typeobject
        • Metadata

          Metadata information for the properties JSON document.

          typeobject
          typeMetadata
          • LastUpdatedUtc

            The last time the properties were updated. In ISO8601 datetime format in UTC, for example, 2015-01-28T16:24:48.789Z.

            typeobject
            typeVariantValueDateTime
            • Value

              read onlyTrue
              typedate-time
            • ObjectValue

              read onlyTrue
              typeobject
            • IsNull

              read onlyTrue
              typeboolean
          • LastUpdatedVersion

            This SHOULD be null for Reported properties metadata and MUST not be null for Desired properties metadata.

            typeint64
          • HasChildren

            True if nested properies are present.

            read onlyTrue
            typeboolean
          • Nested

            Nested properties.

            read onlyTrue
            typeobject
      • ReportedProperties

        Used in conjunction with desired properties to synchronize device configuration or condition. Reported properties can only be set by the device app and can be read and queried by the solution back end.

        typeobject
        typeDeviceTwinProperties
        • Version

          Version of device twin properties.

          typeint64
        • Properties

          Properties JSON element.

          typeobject
        • Metadata

          Metadata information for the properties JSON document.

          typeobject
          typeMetadata
          • LastUpdatedUtc

            The last time the properties were updated. In ISO8601 datetime format in UTC, for example, 2015-01-28T16:24:48.789Z.

            typeobject
            typeVariantValueDateTime
            • Value

              read onlyTrue
              typedate-time
            • ObjectValue

              read onlyTrue
              typeobject
            • IsNull

              read onlyTrue
              typeboolean
          • LastUpdatedVersion

            This SHOULD be null for Reported properties metadata and MUST not be null for Desired properties metadata.

            typeint64
          • HasChildren

            True if nested properies are present.

            read onlyTrue
            typeboolean
          • Nested

            Nested properties.

            read onlyTrue
            typeobject
      • ProvisioningState

        Provisioning state of device twin.

        typeProvisioningState { Creating, Deleting, Active, Deleted }
    • deviceid

      Update a device twin. See https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-device-twins for more information.

      inpath
      requiredTrue
      typestring

    Returns (HTTP Response Codes)

    • 200 response

      OK

      typeDeviceTwinInfo
      • DeviceId

        The deviceId uniquely identifies the device in the IoT hub's identity registry. A case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.

        typestring
      • LastActivityTimeUtc

        The last time the device connected, received or sent a message. In ISO8601 datetime format in UTC, for example, 2015-01-28T16:24:48.789Z. This does not update if the device uses the HTTP/1 protocol to perform messaging operations.

        typeobject
        typeVariantValueDateTime
        • Value

          read onlyTrue
          typedate-time
        • ObjectValue

          read onlyTrue
          typeobject
        • IsNull

          read onlyTrue
          typeboolean
      • IsConnected

        Indicates if the device is currently connected to the IoT hub or not.

        typeboolean
      • LastConnectedTimeUtc

        The last time the device connected to the IoT hub. In ISO8601 datetime format in UTC, for example, 2015-01-28T16:24:48.789Z. This does not update if the device uses the HTTP/1 protocol to perform messaging operations.

        typeobject
        typeVariantValueDateTime
        • Value

          read onlyTrue
          typedate-time
        • ObjectValue

          read onlyTrue
          typeobject
        • IsNull

          read onlyTrue
          typeboolean
      • Version

        Version for device twin, including tags and desired properties

        typeint64
      • Tags

        A JSON document read and written by the solution back end. Tags are not visible to device apps.

        typeobject
      • DesiredProperties

        Used in conjunction with reported properties to synchronize device configuration or condition. Desired properties can only be set by the solution back end and can be read by the device app. The device app can also be notified in real time of changes on the desired properties.

        typeobject
        typeDeviceTwinProperties
        • Version

          Version of device twin properties.

          typeint64
        • Properties

          Properties JSON element.

          typeobject
        • Metadata

          Metadata information for the properties JSON document.

          typeobject
          typeMetadata
          • LastUpdatedUtc

            The last time the properties were updated. In ISO8601 datetime format in UTC, for example, 2015-01-28T16:24:48.789Z.

            typeobject
            typeVariantValueDateTime
            • Value

              read onlyTrue
              typedate-time
            • ObjectValue

              read onlyTrue
              typeobject
            • IsNull

              read onlyTrue
              typeboolean
          • LastUpdatedVersion

            This SHOULD be null for Reported properties metadata and MUST not be null for Desired properties metadata.

            typeint64
          • HasChildren

            True if nested properies are present.

            read onlyTrue
            typeboolean
          • Nested

            Nested properties.

            read onlyTrue
            typeobject
      • ReportedProperties

        Used in conjunction with desired properties to synchronize device configuration or condition. Reported properties can only be set by the device app and can be read and queried by the solution back end.

        typeobject
        typeDeviceTwinProperties
        • Version

          Version of device twin properties.

          typeint64
        • Properties

          Properties JSON element.

          typeobject
        • Metadata

          Metadata information for the properties JSON document.

          typeobject
          typeMetadata
          • LastUpdatedUtc

            The last time the properties were updated. In ISO8601 datetime format in UTC, for example, 2015-01-28T16:24:48.789Z.

            typeobject
            typeVariantValueDateTime
            • Value

              read onlyTrue
              typedate-time
            • ObjectValue

              read onlyTrue
              typeobject
            • IsNull

              read onlyTrue
              typeboolean
          • LastUpdatedVersion

            This SHOULD be null for Reported properties metadata and MUST not be null for Desired properties metadata.

            typeint64
          • HasChildren

            True if nested properies are present.

            read onlyTrue
            typeboolean
          • Nested

            Nested properties.

            read onlyTrue
            typeobject
      • ProvisioningState

        Provisioning state of device twin.

        typeProvisioningState { Creating, Deleting, Active, Deleted }