az iot device c2d-message

Is this page helpful?

Any additional feedback?

Feedback will be sent to Microsoft: By pressing the submit button, your feedback will be used to improve Microsoft products and services. Privacy policy.

Note

This reference is part of the azure-iot extension for the Azure CLI (version 2.24.1 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

az iot device c2d-message abandon	Abandon a cloud-to-device message.
az iot device c2d-message complete	Complete a cloud-to-device message.
az iot device c2d-message purge	Purge cloud-to-device message queue for a target device.
az iot device c2d-message receive	Receive a cloud-to-device message.
az iot device c2d-message reject	Reject or deadletter a cloud-to-device message.
az iot device c2d-message send	Send a cloud-to-device message.

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

--device-id -d

Target Device.

--etag -e

Etag or entity tag corresponding to the last state of the resource. If no etag is provided the value '*' is used.

Optional Parameters

--hub-name -n

IoT Hub name. 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.

--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 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

--device-id -d

Target Device.

--etag -e

Etag or entity tag corresponding to the last state of the resource. If no etag is provided the value '*' is used.

Optional Parameters

--hub-name -n

IoT Hub name. 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.

--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 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

--device-id -d

Target Device.

Optional Parameters

--hub-name -n

IoT Hub name. 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.

--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 c2d-message receive

Receive a cloud-to-device message.

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]
                                  [--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

--device-id -d

Target Device.

Optional Parameters

--abandon

Abandon the cloud-to-device message after receipt.

accepted values: false, true

--complete

Complete the cloud-to-device message after receipt.

accepted values: false, true

--hub-name -n

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

--lock-timeout --lt

Specifies the amount of time a message will be invisible to other receive calls.

default value: 60

--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.

--reject

Reject the cloud-to-device message after receipt.

accepted values: false, true

--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.

--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 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

--device-id -d

Target Device.

--etag -e

Etag or entity tag corresponding to the last state of the resource. If no etag is provided the value '*' is used.

Optional Parameters

--hub-name -n

IoT Hub name. 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.

--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 c2d-message send

Send a cloud-to-device message.

EXPERIMENTAL requires Python 3.4+ This command relies on and may install dependent Cython package (uamqp) upon first execution. https://github.com/Azure/azure-uamqp-python.

az iot device c2d-message send --device-id
                               [--ack {full, negative, positive}]
                               [--auth-type {key, login}]
                               [--ce]
                               [--cid]
                               [--content-type]
                               [--da]
                               [--expiry]
                               [--hub-name]
                               [--login]
                               [--message-id]
                               [--properties]
                               [--repair {false, true}]
                               [--resource-group]
                               [--uid]
                               [--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

Required Parameters

--device-id -d

Target Device.

Optional Parameters

--ack

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.

accepted values: full, negative, positive

--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>.

accepted values: key, login

default value: key

--ce --content-encoding

The encoding for the C2D message body.

default value: utf-8

--cid --correlation-id

The correlation Id associated with the C2D message.

--content-type --ct

The content type for the C2D message body.

--da --data

Message body.

default value: Ping from Az CLI IoT Extension

--expiry --expiry-time-utc

Units are milliseconds since unix epoch. If no time is indicated the default IoT Hub C2D message TTL is used.

--hub-name -n

IoT Hub name. 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.

--message-id --mid

The C2D message Id. If no message Id is provided a UUID will be generated.

--properties --props -p

Message property bag in key-value pairs with the following format: a=b;c=d.

--repair -r

Reinstall uamqp dependency compatible with extension version. Default: false.

accepted values: false, true

--resource-group -g

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

--uid --user-id

The C2D message, user Id property.

--wait -w

If set the c2d send operation will block until device feedback has been received.

accepted values: false, true

--yes -y

Skip user prompts. Indicates acceptance of dependency installation (if required). Used primarily for automation scenarios. Default: false.

accepted values: false, true

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.

--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.