مشاركة عبر

az iot device

  • Reference

Note

This reference is part of the azure-iot extension for the Azure CLI (version 2.46.0 or higher). The extension will automatically install the first time you run an az iot device command. Learn more about extensions.

Leverage device simulation and other device-centric operations such as device-to-cloud or cloud-to-device messaging capabilities.

Commands

Name Description Type Status
az iot device c2d-message

Cloud-to-device messaging commands.

 Extension GA
az iot device c2d-message abandon

Abandon a cloud-to-device message.

 Extension GA
az iot device c2d-message complete

Complete a cloud-to-device message.

 Extension GA
az iot device c2d-message purge

Purge cloud-to-device message queue for a target device.

 Extension GA
az iot device c2d-message receive

Receive a cloud-to-device message.

 Extension GA
az iot device c2d-message reject

Reject or deadletter a cloud-to-device message.

 Extension GA
az iot device c2d-message send

Send a cloud-to-device message.

 Extension GA
az iot device registration

Manage IoT device registrations for the IoT Device Provisioning Service.

 Extension Preview
az iot device registration create

Register an IoT device with the IoT Device Provisioning Service.

 Extension Preview
az iot device send-d2c-message

Send an mqtt device-to-cloud message.

 Extension GA
az iot device simulate

Simulate a device in an Azure IoT Hub.

 Extension Experimental
az iot device upload-file

Upload a local file as a device to a pre-configured blob storage container.

 Extension GA

az iot device send-d2c-message

Send an mqtt device-to-cloud message.

The command supports sending messages with custom payload in unicode string or binary format. When intending to send binary, the data should come from a file (via --data-file-path) and content type should be set to application/octet-stream.

Note: The command only works for symmetric key auth (SAS) based devices. To enable querying on a message body in message routing, the contentType system property must be application/JSON and the contentEncoding system property must be one of the UTF encoding values supported by that system property(UTF-8, UTF-16 or UTF-32). If the content encoding isn't set when Azure Storage is used as routing endpoint, then IoT Hub writes the messages in base 64 encoded format. If using x509 authentication methods, the certificate and key files (and passphrase if needed) must be provided.

az iot device send-d2c-message --device-id
                               [--certificate-file-path]
                               [--da]
                               [--data-file-path]
                               [--dtmi]
                               [--hub-name]
                               [--key]
                               [--key-file-path]
                               [--login]
                               [--mc]
                               [--pass]
                               [--properties]
                               [--resource-group]

Examples

Basic usage

az iot device send-d2c-message -n {iothub_name} -d {device_id}

Basic usage for device registering the model Id of 'dtmi:com:example:Thermostat;1' upon connection

az iot device send-d2c-message -n {iothub_name} -d {device_id} --model-id 'dtmi:com:example:Thermostat;1'

Basic usage for device with x509 authentication

az iot device send-d2c-message -n {iothub_name} -d {device_id} --cp {certificate_file_path} --kp {key_file_path}

Basic usage for device with x509 authentication in which the key file has a passphrase

az iot device send-d2c-message -n {iothub_name} -d {device_id} --cp {certificate_file_path} --kp {key_file_path} --pass {passphrase}

Basic usage with custom data

az iot device send-d2c-message -n {iothub_name} -d {device_id} --data {message_body}

Send application properties

az iot device send-d2c-message -n {iothub_name} -d {device_id} --props 'key0=value0;key1=value1'

Send system properties (Message Id and Correlation Id)

az iot device send-d2c-message -n {iothub_name} -d {device_id} --props '$.mid={id};$.cid={id}'

Send custom data by specifying content-type and content-encoding in system properties

az iot device send-d2c-message -n {iothub_name} -d {device_id} --props '$.ct={content-type};$.ce={content-encoding}' --data {message_body}

Send custom data in binary format by specifying content-encoding in system properties

az iot device send-d2c-message -n {iothub_name} -d {device_id} --props '$.ct=application/octet-stream' --data-file-path {file_path}

Send custom data in JSON format by specifying content-type and content-encoding in system properties

az iot device send-d2c-message -n {iothub_name} -d {device_id} --props '$.ct=application/json;$.ce=utf-8' --data-file-path {file_path}

Required Parameters

--device-id -d

Target Device Id.

Optional Parameters

--certificate-file-path --cp

Path to certificate file.

--da --data

Message body. Provide text or raw json.

Default value: Ping from Az CLI IoT Extension
--data-file-path --dfp
Preview

Provide path to file for message body payload. Please note when the payload needs to be sent in binary format, set the content type to application/octet-stream.

--dtmi --model-id

The Digital Twin Model Id the device will report when connecting to the hub. See https://docs.microsoft.com/en-us/azure/iot-develop/overview-iot-plug-and-play for more details.

--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--key --symmetric-key

Symmetric key to use for the device. If the symmetric key and other device authentication arguments are provided, symmetric key takes priority.

--key-file-path --kp

Path to key file.

--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.

--mc --msg-count

Number of device messages to send to IoT Hub.

Default value: 1
--pass --passphrase

Passphrase for key file.

--properties --props -p

Message property bag in key-value pairs with the following format: a=b;c=d. For mqtt messaging - you are able to send system properties using $.=value. For instance $.cid=12345 sets the system correlation Id property. Other system property identifier examples include $.ct for content type, $.mid for message Id and $.ce for content encoding.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az iot device simulate

Experimental

This command is experimental and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Simulate a device in an Azure IoT Hub.

While the device simulation is running, the device will automatically receive and acknowledge cloud-to-device (c2d) messages. For mqtt simulation, all c2d messages will be acknowledged with completion. For http simulation c2d acknowledgement is based on user selection which can be complete, reject or abandon. The mqtt simulation also supports direct method invocation which can be acknowledged by a response status code and response payload. Note: The command by default will set content-type to application/json and content-encoding to utf-8. This can be overriden. Note: If using x509 authentication methods, the certificate and key files (and passphrase if needed) must be provided.

az iot device simulate --device-id
                       [--certificate-file-path]
                       [--da]
                       [--dtmi]
                       [--hub-name]
                       [--init-reported-properties]
                       [--key]
                       [--key-file-path]
                       [--login]
                       [--mc]
                       [--method-response-code]
                       [--method-response-payload]
                       [--mi]
                       [--pass]
                       [--properties]
                       [--proto {http, mqtt}]
                       [--receive-settle {abandon, complete, reject}]
                       [--resource-group]

Examples

Basic usage (mqtt)

az iot device simulate -n {iothub_name} -d {device_id}

Basic usage for device registering the model Id of 'dtmi:com:example:Thermostat;1' upon connection (mqtt)

az iot device simulate -n {iothub_name} -d {device_id} --model-id 'dtmi:com:example:Thermostat;1'

Basic usage for device with x509 authentication (mqtt)

az iot device simulate -n {iothub_name} -d {device_id} --cp {certificate_file_path} --kp {key_file_path}

Basic usage for device with x509 authentication (mqtt) in which the key file has a passphrase

az iot device simulate -n {iothub_name} -d {device_id} --cp {certificate_file_path} --kp {key_file_path} --pass {passphrase}

Send mixed properties (mqtt)

az iot device simulate -n {iothub_name} -d {device_id} --properties "myprop=myvalue;$.ct=application/json"

Send direct method response status code and direct method response payload as raw json (mqtt only)

az iot device simulate -n {iothub_name} -d {device_id} --method-response-code 201 --method-response-payload '{"result":"Direct method successful"}'

Send direct method response status code and direct method response payload as path to local file (mqtt only)

az iot device simulate -n {iothub_name} -d {device_id} --method-response-code 201 --method-response-payload '../my_direct_method_payload.json'

Send the initial state of device twin reported properties as raw json for the target device (mqtt only)

az iot device simulate -n {iothub_name} -d {device_id} --init-reported-properties '{"reported_prop_1":"val_1", "reported_prop_2":val_2}'

Send the initial state of device twin reported properties as path to local file for the target device (mqtt only)

az iot device simulate -n {iothub_name} -d {device_id} --init-reported-properties '../my_device_twin_reported_properties.json'

Basic usage (http)

az iot device simulate -n {iothub_name} -d {device_id} --protocol http

Send mixed properties (http)

az iot device simulate -n {iothub_name} -d {device_id} --protocol http --properties "iothub-app-myprop=myvalue;content-type=application/json;iothub-correlationid=12345"

Choose total message count and interval between messages

az iot device simulate -n {iothub_name} -d {device_id} --msg-count 1000 --msg-interval 5

Reject c2d messages (http only)

az iot device simulate -n {iothub_name} -d {device_id} --rs reject --protocol http

Abandon c2d messages (http only)

az iot device simulate -n {iothub_name} -d {device_id} --rs abandon --protocol http

Required Parameters

--device-id -d

Target Device Id.

Optional Parameters

--certificate-file-path --cp

Path to certificate file.

--da --data

Message body. Provide text or raw json.

Default value: Ping from Az CLI IoT Extension
--dtmi --model-id

The Digital Twin Model Id the device will report when connecting to the hub. See https://docs.microsoft.com/en-us/azure/iot-develop/overview-iot-plug-and-play for more details.

--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--init-reported-properties --irp

Initial state of twin reported properties for the target device when the simulator is run. Optional param, only supported for mqtt.

--key --symmetric-key

Symmetric key to use for the device. If the symmetric key and other device authentication arguments are provided, symmetric key takes priority.

--key-file-path --kp

Path to key file.

--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.

--mc --msg-count

Number of device messages to send to IoT Hub.

Default value: 100
--method-response-code --mrc

Status code to be returned when direct method is executed on device. Optional param, only supported for mqtt.

--method-response-payload --mrp

Payload to be returned when direct method is executed on device. Provide file path or raw json. Optional param, only supported for mqtt.

--mi --msg-interval

Delay in seconds between device-to-cloud messages.

Default value: 3
--pass --passphrase

Passphrase for key file.

--properties --props -p

Message property bag in key-value pairs with the following format: a=b;c=d. For mqtt messaging - you are able to send system properties using $.=value. For instance $.cid=12345 sets the system correlation Id property. Other system property identifier examples include $.ct for content type, $.mid for message Id and $.ce for content encoding. For http messaging - application properties are sent using iothub-app-=value, for instance iothub-app-myprop=myvalue. System properties are generally prefixed with iothub- like iothub-correlationid but there are exceptions such as content-type and content-encoding.

--proto --protocol

Indicates device-to-cloud message protocol.

Accepted values: http, mqtt
Default value: mqtt
--receive-settle --rs

Indicates how to settle received cloud-to-device messages. Supported with HTTP only.

Accepted values: abandon, complete, reject
Default value: complete
--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az iot device upload-file

Upload a local file as a device to a pre-configured blob storage container.

az iot device upload-file --content-type
                          --device-id
                          --file-path
                          [--hub-name]
                          [--login]
                          [--resource-group]

Required Parameters

--content-type --ct

MIME Type of file.

--device-id -d

Target Device Id.

--file-path --fp

Path to file for upload.

Optional Parameters

--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.