az dt model

  • Reference

Note

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

Manage DTDL models and definitions on a Digital Twins instance.

Commands

Name Description Type Status
az dt model create

Uploads one or more models.

 Extension GA
az dt model delete

Delete a model. A model can only be deleted if no other models reference it.

 Extension GA
az dt model delete-all

Delete all models within a Digital Twins instance.

 Extension GA
az dt model list

List model metadata, definitions and dependencies.

 Extension GA
az dt model show

Retrieve a target model or model definition.

 Extension GA
az dt model update

Updates the metadata for a model. Currently a model can only be decommisioned.

 Extension GA

az dt model create

Uploads one or more models.

--models can be inline json or file path. Size of input model set (ontology) is constrained by max number of models which the DT instance can store (default is 10000 models).

az dt model create --dt-name
                   [--failure-policy {None, Rollback}]
                   [--fd]
                   [--max-models-per-batch]
                   [--models]
                   [--resource-group]

Examples

Bulk upload all .json or .dtdl model files from a target directory. Model processing is recursive.

az dt model create -n {instance_or_hostname} --from-directory {directory_path}

Upload model json inline or from file path.

az dt model create -n {instance_or_hostname} --models {file_path_or_inline_json}

Required Parameters

--dt-name --dtn -n

Digital Twins instance name or hostname. If an instance name is provided, the user subscription is first queried for the target instance to retrieve the hostname. If a hostname is provided, the subscription query is skipped and the provided value is used for subsequent interaction.

Optional Parameters

--failure-policy --fp

Indicates the failure policy when an error occurs while processing a models batch. In the 'Rollback' mode all models created in previous batches are deleted one at a time. When selected as 'None' the models created in previous batches are not deleted from DT instance.

accepted values: None, Rollback
default value: Rollback
--fd --from-directory

The directory JSON model files will be parsed from. Please Note: Models are created atomically when directory contains 250 or lesser models, hence in case of an error none of the models get created.Input model set is chunked & created in batches when directory has more than 250 models(API limit). In case of an error processing a batch, the behavior is determined by the --failure-policy parameter.

--max-models-per-batch --mmpb
Experimental

The maximum model size per batch when creating more than 250 models.Reduce this number to prevent a DTDLParser error.

default value: 30
--models

Inline model JSON or file path to model JSON. Please Note: Models are created atomically when model JSON contains 250 or lesser models, hence in case of an error none of the models get created.Input model set is chunked & created in batches when model JSON has more than 250 models(API limit). In case of an error processing a batch, the behavior is determined by the --failure-policy parameter.

--resource-group -g

Digital Twins instance 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 dt model delete

Delete a model. A model can only be deleted if no other models reference it.

az dt model delete --dt-name
                   --dtmi
                   [--resource-group]

Examples

Delete a target model.

az dt model delete -n {instance_or_hostname} --dtmi "dtmi:com:example:Floor;1"

Required Parameters

--dt-name --dtn -n

Digital Twins instance name or hostname. If an instance name is provided, the user subscription is first queried for the target instance to retrieve the hostname. If a hostname is provided, the subscription query is skipped and the provided value is used for subsequent interaction.

--dtmi --model-id -m

Digital Twins model Id. Example: dtmi:com:example:Room;2.

Optional Parameters

--resource-group -g

Digital Twins instance 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 dt model delete-all

Delete all models within a Digital Twins instance.

Twins configurations are not affected but may be broken without model definitions.

az dt model delete-all --dt-name
                       [--resource-group]
                       [--yes]

Examples

Delete all models.

az dt model delete-all -n {instance_or_hostname}

Required Parameters

--dt-name --dtn -n

Digital Twins instance name or hostname. If an instance name is provided, the user subscription is first queried for the target instance to retrieve the hostname. If a hostname is provided, the subscription query is skipped and the provided value is used for subsequent interaction.

Optional Parameters

--resource-group -g

Digital Twins instance resource group. You can configure the default group using az configure --defaults group=<name>.

--yes -y

Do not prompt for confirmation.

default value: False
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 dt model list

List model metadata, definitions and dependencies.

az dt model list --dt-name
                 [--def {false, true}]
                 [--dependencies-for]
                 [--resource-group]

Examples

List model metadata

az dt model list -n {instance_or_hostname}

List model definitions

az dt model list -n {instance_or_hostname} --definition

List dependencies of particular pre-existing model(s). Space separate dtmi values.

az dt model list -n {instance_or_hostname} --dependencies-for {model_id0} {model_id1}

Required Parameters

--dt-name --dtn -n

Digital Twins instance name or hostname. If an instance name is provided, the user subscription is first queried for the target instance to retrieve the hostname. If a hostname is provided, the subscription query is skipped and the provided value is used for subsequent interaction.

Optional Parameters

--def --definition

The operation will retrieve the model definition.

accepted values: false, true
default value: False
--dependencies-for

The set of models which will have their dependencies retrieved. If omitted, all models are retrieved. Format is a whitespace separated list.

--resource-group -g

Digital Twins instance 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 dt model show

Retrieve a target model or model definition.

az dt model show --dt-name
                 --dtmi
                 [--def {false, true}]
                 [--resource-group]

Examples

Show model meta data

az dt model show -n {instance_or_hostname} --dtmi "dtmi:com:example:Floor;1"

Show model meta data and definition

az dt model show -n {instance_or_hostname} --dtmi "dtmi:com:example:Floor;1" --definition

Required Parameters

--dt-name --dtn -n

Digital Twins instance name or hostname. If an instance name is provided, the user subscription is first queried for the target instance to retrieve the hostname. If a hostname is provided, the subscription query is skipped and the provided value is used for subsequent interaction.

--dtmi --model-id -m

Digital Twins model Id. Example: dtmi:com:example:Room;2.

Optional Parameters

--def --definition

The operation will retrieve the model definition.

accepted values: false, true
default value: False
--resource-group -g

Digital Twins instance 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 dt model update

Updates the metadata for a model. Currently a model can only be decommisioned.

az dt model update --dt-name
                   --dtmi
                   [--decommission {false, true}]
                   [--resource-group]

Examples

Decommision a target model

az dt model update -n {instance_or_hostname} --dtmi "dtmi:com:example:Floor;1" --decommission

Required Parameters

--dt-name --dtn -n

Digital Twins instance name or hostname. If an instance name is provided, the user subscription is first queried for the target instance to retrieve the hostname. If a hostname is provided, the subscription query is skipped and the provided value is used for subsequent interaction.

--dtmi --model-id -m

Digital Twins model Id. Example: dtmi:com:example:Room;2.

Optional Parameters

--decommission

Indicates intent to decommission a target model.

accepted values: false, true
--resource-group -g

Digital Twins instance 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.