az iot device c2d-message
Note
This reference is part of the azure-iot extension for the Azure CLI (version 2.59.0 or higher). The extension will automatically install the first time you run an az iot device c2d-message command. Learn more about extensions.
Cloud-to-device messaging commands.
Commands
Name | Description | Type | Status |
---|---|---|---|
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 c2d-message abandon
Abandon a cloud-to-device message.
az iot device c2d-message abandon --device-id
[--etag]
[--hub-name]
[--login]
[--resource-group]
Required Parameters
Target Device Id.
Optional Parameters
The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.
Etag or entity tag corresponding to the last state of the resource. If no etag is provided the value '*' is used.
IoT Hub name or hostname. Required if --login is not provided.
Property | Value |
---|---|
Parameter group: | IoT Hub Identifier Arguments |
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.
Property | Value |
---|---|
Parameter group: | IoT Hub Identifier Arguments |
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Global Parameters
Increase logging verbosity to show all debug logs.
Property | Value |
---|---|
Default value: | False |
Show this help message and exit.
Only show errors, suppressing warnings.
Property | Value |
---|---|
Default value: | False |
Output format.
Property | Value |
---|---|
Default value: | json |
Accepted values: | json, jsonc, none, table, tsv, yaml, yamlc |
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Increase logging verbosity. Use --debug for full debug logs.
Property | Value |
---|---|
Default value: | False |
az iot device c2d-message complete
Complete a cloud-to-device message.
az iot device c2d-message complete --device-id
[--etag]
[--hub-name]
[--login]
[--resource-group]
Required Parameters
Target Device Id.
Optional Parameters
The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.
Etag or entity tag corresponding to the last state of the resource. If no etag is provided the value '*' is used.
IoT Hub name or hostname. Required if --login is not provided.
Property | Value |
---|---|
Parameter group: | IoT Hub Identifier Arguments |
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.
Property | Value |
---|---|
Parameter group: | IoT Hub Identifier Arguments |
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Global Parameters
Increase logging verbosity to show all debug logs.
Property | Value |
---|---|
Default value: | False |
Show this help message and exit.
Only show errors, suppressing warnings.
Property | Value |
---|---|
Default value: | False |
Output format.
Property | Value |
---|---|
Default value: | json |
Accepted values: | json, jsonc, none, table, tsv, yaml, yamlc |
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Increase logging verbosity. Use --debug for full debug logs.
Property | Value |
---|---|
Default value: | False |
az iot device c2d-message purge
Purge cloud-to-device message queue for a target device.
az iot device c2d-message purge --device-id
[--hub-name]
[--login]
[--resource-group]
Required Parameters
Target Device Id.
Optional Parameters
The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.
IoT Hub name or hostname. Required if --login is not provided.
Property | Value |
---|---|
Parameter group: | IoT Hub Identifier Arguments |
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.
Property | Value |
---|---|
Parameter group: | IoT Hub Identifier Arguments |
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Global Parameters
Increase logging verbosity to show all debug logs.
Property | Value |
---|---|
Default value: | False |
Show this help message and exit.
Only show errors, suppressing warnings.
Property | Value |
---|---|
Default value: | False |
Output format.
Property | Value |
---|---|
Default value: | json |
Accepted values: | json, jsonc, none, table, tsv, yaml, yamlc |
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Increase logging verbosity. Use --debug for full debug logs.
Property | Value |
---|---|
Default value: | False |
az iot device c2d-message receive
Receive a cloud-to-device message.
The received message body will only be decoded when its content-encoding is set to 'utf-8', 'utf-16' or 'utf-32'. The message payload will be displayed as {{non-decodable payload}} when content-encoding is not set to one of the above, or fails to decode even when content-encoding is set to one of the above.
Note: Only one message ack argument [--complete, --reject, --abandon] will be accepted.
az iot device c2d-message receive --device-id
[--abandon {false, true}]
[--complete {false, true}]
[--hub-name]
[--lock-timeout --lt]
[--login]
[--reject {false, true}]
[--resource-group]
Examples
Basic usage
az iot device c2d-message receive -d {device_id} -n {hub_name} -g {resource_group}
Receive a message and set a lock timeout of 30 seconds for that message
az iot device c2d-message receive -d {device_id} -n {hub_name} -g {resource_group} --lt {30}
Receive a message and ack it as 'complete' after it is received
az iot device c2d-message receive -d {device_id} -n {hub_name} -g {resource_group} --complete
Receive a message and reject it after it is received
az iot device c2d-message receive -d {device_id} -n {hub_name} -g {resource_group} --reject
Required Parameters
Target Device Id.
Optional Parameters
The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.
Abandon the cloud-to-device message after receipt.
Property | Value |
---|---|
Parameter group: | Message Ack Arguments |
Default value: | False |
Accepted values: | false, true |
Complete the cloud-to-device message after receipt.
Property | Value |
---|---|
Parameter group: | Message Ack Arguments |
Default value: | False |
Accepted values: | false, true |
IoT Hub name or hostname. Required if --login is not provided.
Property | Value |
---|---|
Parameter group: | IoT Hub Identifier Arguments |
Specifies the amount of time a message will be invisible to other receive calls.
Property | Value |
---|---|
Default value: | 60 |
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.
Property | Value |
---|---|
Parameter group: | IoT Hub Identifier Arguments |
Reject the cloud-to-device message after receipt.
Property | Value |
---|---|
Parameter group: | Message Ack Arguments |
Default value: | False |
Accepted values: | false, true |
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Global Parameters
Increase logging verbosity to show all debug logs.
Property | Value |
---|---|
Default value: | False |
Show this help message and exit.
Only show errors, suppressing warnings.
Property | Value |
---|---|
Default value: | False |
Output format.
Property | Value |
---|---|
Default value: | json |
Accepted values: | json, jsonc, none, table, tsv, yaml, yamlc |
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Increase logging verbosity. Use --debug for full debug logs.
Property | Value |
---|---|
Default value: | False |
az iot device c2d-message reject
Reject or deadletter a cloud-to-device message.
az iot device c2d-message reject --device-id
[--etag]
[--hub-name]
[--login]
[--resource-group]
Required Parameters
Target Device Id.
Optional Parameters
The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.
Etag or entity tag corresponding to the last state of the resource. If no etag is provided the value '*' is used.
IoT Hub name or hostname. Required if --login is not provided.
Property | Value |
---|---|
Parameter group: | IoT Hub Identifier Arguments |
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.
Property | Value |
---|---|
Parameter group: | IoT Hub Identifier Arguments |
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Global Parameters
Increase logging verbosity to show all debug logs.
Property | Value |
---|---|
Default value: | False |
Show this help message and exit.
Only show errors, suppressing warnings.
Property | Value |
---|---|
Default value: | False |
Output format.
Property | Value |
---|---|
Default value: | json |
Accepted values: | json, jsonc, none, table, tsv, yaml, yamlc |
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Increase logging verbosity. Use --debug for full debug logs.
Property | Value |
---|---|
Default value: | False |
az iot device c2d-message send
Send a cloud-to-device message.
This command relies on and may install dependent Cython package (uamqp) upon first execution. https://github.com/Azure/azure-uamqp-python
Note: Content-encoding is defaulted to utf-8. The command will send the message body with encoding action when the content-encoding property is either utf-8, utf-16 or utf-32. If the content-encoding value is not one of these, the property will still be sent with no encoding action taken.
When sending a binary message body, the content must be provided from a file
(via --data-file-path
) and content-type must be set to application/octet-stream
.
az iot device c2d-message send --device-id
[--ack {full, negative, positive}]
[--auth-type {key, login}]
[--ce --content-encoding]
[--cid --correlation-id]
[--content-type --ct]
[--da --data]
[--data-file-path --dfp]
[--expiry --expiry-time-utc]
[--hub-name]
[--login]
[--message-id --mid]
[--properties --props]
[--repair {false, true}]
[--resource-group]
[--uid --user-id]
[--wait {false, true}]
[--yes {false, true}]
Examples
Basic usage with default message body
az iot device c2d-message send -d {device_id} -n {iothub_name}
Send cloud-to-device message with custom data and properties.
az iot device c2d-message send -d {device_id} -n {iothub_name} --data 'Hello World' --props 'key0=value0;key1=value1'
Send a C2D message and wait for device acknowledgement
az iot device c2d-message send -d {device_id} -n {iothub_name} --ack full --wait
Send a C2D message in binary format from a file.
az iot device c2d-message send -d {device_id} -n {iothub_name} --data-file-path {file_path} --content-type 'application/octet-stream'
Send a C2D message in JSON format from a file.
az iot device c2d-message send -d {device_id} -n {iothub_name} --data-file-path {file_path} --content-type 'application/json'
Required Parameters
Target Device Id.
Optional Parameters
The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.
Request the delivery of per-message feedback regarding the final state of that message. The description of ack values is as follows. Positive: If the c2d message reaches the Completed state, IoT Hub generates a feedback message. Negative: If the c2d message reaches the Dead lettered state, IoT Hub generates a feedback message. Full: IoT Hub generates a feedback message in either case. By default, no ack is requested.
Property | Value |
---|---|
Accepted values: | full, negative, positive |
Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type={auth-type-value}
.
Property | Value |
---|---|
Parameter group: | Access Control Arguments |
Default value: | key |
Accepted values: | key, login |
The encoding for the C2D message body.
Property | Value |
---|---|
Default value: | utf-8 |
The correlation Id associated with the C2D message.
The content type for the C2D message body.
Message body. Provide text or raw json.
Property | Value |
---|---|
Default value: | Ping from Az CLI IoT Extension |
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.
Units are milliseconds since unix epoch. If no time is indicated the default IoT Hub C2D message TTL is used.
IoT Hub name or hostname. Required if --login is not provided.
Property | Value |
---|---|
Parameter group: | IoT Hub Identifier Arguments |
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.
Property | Value |
---|---|
Parameter group: | IoT Hub Identifier Arguments |
The C2D message Id. If no message Id is provided a UUID will be generated.
Message property bag in key-value pairs with the following format: a=b;c=d.
Reinstall uamqp dependency compatible with extension version. Default: false.
Property | Value |
---|---|
Default value: | False |
Accepted values: | false, true |
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
The C2D message, user Id property.
If set the c2d send operation will block until device feedback has been received.
Property | Value |
---|---|
Default value: | False |
Accepted values: | false, true |
Skip user prompts. Indicates acceptance of action. Used primarily for automation scenarios. Default: false.
Property | Value |
---|---|
Default value: | False |
Accepted values: | false, true |
Global Parameters
Increase logging verbosity to show all debug logs.
Property | Value |
---|---|
Default value: | False |
Show this help message and exit.
Only show errors, suppressing warnings.
Property | Value |
---|---|
Default value: | False |
Output format.
Property | Value |
---|---|
Default value: | json |
Accepted values: | json, jsonc, none, table, tsv, yaml, yamlc |
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Increase logging verbosity. Use --debug for full debug logs.
Property | Value |
---|---|
Default value: | False |