ADU dataplane GA refresh (#570)

Azure · Sep 2, 2022 · cbd8337 · cbd8337
1 parent e62cdb3
commit cbd8337
Show file tree

Hide file tree

Showing 30 changed files with 413 additions and 5,121 deletions.
diff --git a/HISTORY.rst b/HISTORY.rst
@@ -12,8 +12,14 @@ unreleased
 
 **Device Update**
 
-* The Device Update control plane or infrastructure command groups `az iot device-update account` and
+* The Device Update control plane (or infrastructure related) command groups `az iot device-update account` and
   `az iot device-update instance` now use the GA API version of 2022-10-01.
+* The Device Update data plane command groups `az iot device-update device` and
+  `az iot device-update update` now use the GA API version of 2022-10-01.
+* The command `az iot device-update device class list` adds support for `--filter` when no `--group-id` is provided.
+* The parameters `--account`, `--instance`, and `--resource-group` support setting default overridable values via config.
+  Use `az config set` i.e. `az config set defaults.adu_account=<name>` or `az configure` i.e. `az configure --defaults adu_account=<name>`.
+* Improved built-in documentation.
 
 
 0.17.0

diff --git a/azext_iot/constants.py b/azext_iot/constants.py
@@ -7,7 +7,7 @@
 
 import os
 
-VERSION = "0.17.0"
+VERSION = "0.17.1"
 EXTENSION_NAME = "azure-iot"
 EXTENSION_ROOT = os.path.dirname(os.path.abspath(__file__))
 EXTENSION_CONFIG_ROOT_KEY = "iotext"

diff --git a/azext_iot/deviceupdate/_help.py b/azext_iot/deviceupdate/_help.py
@@ -421,11 +421,15 @@ def load_deviceupdate_help():
           text: >
             az iot device-update device class list -n {account_name} -i {instance_name}
 
+        - name: List instance device classes filtered by friendly name.
+          text: >
+            az iot device-update device class list -n {account_name} -i {instance_name} --filter "friendlyName eq 'my-favorite-class'"
+
         - name: List device class subgroups for the group.
           text: >
             az iot device-update device class list -n {account_name} -i {instance_name} --group-id {device_group_id}
 
-        - name: List device class subgroups for the group, filtered by compatProperties/manufacturer
+        - name: List device class subgroups for the group, filtered by compatProperties/manufacturer.
           text: >
             az iot device-update device class list -n {account_name} -i {instance_name} --group-id {device_group_id} --filter "compatProperties/manufacturer eq 'Contoso'"
     """
@@ -471,7 +475,7 @@ def load_deviceupdate_help():
         type: command
         short-summary: Delete a device class or device class subgroup.
         long-summary: >
-          Device classes are created automatically when Device Update-enabled devices are connected to
+          Device classes are automatically created when Device Update-enabled devices are connected to
           the hub but are not automatically cleaned up since they are referenced by device class subgroups.
           If all device class subgroups for a target device class are deleted then the device class itself can also be deleted
           to remove the records from the system and to stop checking the compatibility of the device class with new

diff --git a/azext_iot/deviceupdate/commands_device.py b/azext_iot/deviceupdate/commands_device.py
@@ -133,15 +133,12 @@ def show_update_compliance(cmd, name: str, instance_name: str, resource_group_na
         handle_service_exception(e)
 
 
-# @digimaun, pageable but not attributed correctly.
 def list_device_health(cmd, name: str, instance_name: str, filter: str, resource_group_name: Optional[str] = None):
     data_manager = DeviceUpdateDataManager(
         cmd=cmd, account_name=name, instance_name=instance_name, resource_group=resource_group_name
     )
 
     try:
-        # "deviceId eq 'd0'"
-        # "state eq 'Healthy'"
-        return data_manager.data_client.device_management.list_device_health(filter=filter)
+        return data_manager.data_client.device_management.list_health_of_devices(filter=filter)
     except AzureError as e:
         handle_service_exception(e)
diff --git a/azext_iot/deviceupdate/commands_device_class.py b/azext_iot/deviceupdate/commands_device_class.py
@@ -28,15 +28,13 @@ def list_device_classes(
     data_manager = DeviceUpdateDataManager(
         cmd=cmd, account_name=name, instance_name=instance_name, resource_group=resource_group_name
     )
-    if filter and not device_group_id:
-        raise ArgumentUsageError("--group-id is required when using --filter")
 
     if device_group_id:
         return data_manager.data_client.device_management.list_device_class_subgroups_for_group(
             group_id=device_group_id, filter=filter
         )
     try:
-        return data_manager.data_client.device_management.list_device_classes()
+        return data_manager.data_client.device_management.list_device_classes(filter=filter)
     except AzureError as e:
         handle_service_exception(e)
 
@@ -112,7 +110,6 @@ def update_device_class(
         logger.warning("No patch body option values provided. Update device class has no work to be done.")
 
 
-# @digimaun, this operation doesn't work yet.
 def delete_device_class(
     cmd,
     name: str,
@@ -129,6 +126,7 @@ def delete_device_class(
             return data_manager.data_client.device_management.delete_device_class_subgroup(
                 device_class_id=device_class_id, group_id=device_group_id
             )
+        # @digimaun, this operation returns a 404 today.
         return data_manager.data_client.device_management.delete_device_class(device_class_id=device_class_id)
     except AzureError as e:
         handle_service_exception(e)
diff --git a/azext_iot/deviceupdate/commands_update.py b/azext_iot/deviceupdate/commands_update.py
@@ -181,6 +181,9 @@ def import_handler(lro: ARMPolling):
                 )
             elif lro.status() == "Failed":
                 try:
+                    logger.warning(
+                        "Cached contents (if any) from usage of --defer were not removed. "
+                        "Use 'az cache' command group to manage.")
                     logger.error(lro._pipeline_response.http_response.text())
                 except Exception:
                     pass
@@ -207,30 +210,3 @@ def delete_update(
     return data_manager.data_client.device_update.begin_delete_update(
         name=update_name, provider=update_provider, version=update_version
     )
-
-
-def list_operations(
-    cmd,
-    name: str,
-    instance_name: str,
-    filter=None,
-    top: Optional[int] = None,
-    resource_group_name: Optional[str] = None,
-):
-    data_manager = DeviceUpdateDataManager(
-        cmd=cmd, account_name=name, instance_name=instance_name, resource_group=resource_group_name
-    )
-    try:
-        return data_manager.data_client.device_update.list_operations(filter=filter, top=top)
-    except AzureError as e:
-        handle_service_exception(e)
-
-
-def show_operation(cmd, name: str, instance_name: str, operation_id: str, resource_group_name: Optional[str] = None):
-    data_manager = DeviceUpdateDataManager(
-        cmd=cmd, account_name=name, instance_name=instance_name, resource_group=resource_group_name
-    )
-    try:
-        return data_manager.data_client.device_update.get_operation(operation_id=operation_id)
-    except AzureError as e:
-        handle_service_exception(e)
diff --git a/azext_iot/deviceupdate/params.py b/azext_iot/deviceupdate/params.py
@@ -31,17 +31,25 @@ def load_deviceupdate_arguments(self, _):
             "resource_group_name",
             arg_type=resource_group_name_type,
             help="Device Update account resource group name. "
-            "You can configure the default group using `az configure --defaults group=<name>`.",
+            "You can configure the default group using `az config set defaults.adu_group=<name>`.",
             arg_group="Account Identifier",
+            configured_default="adu_group",
         )
         context.argument(
-            "name", options_list=["-n", "--account"], help="Device Update account name.", arg_group="Account Identifier"
+            "name",
+            options_list=["-n", "--account"],
+            help="Device Update account name. "
+            "You can configure the default account name using `az config set defaults.adu_account=<name>`.",
+            arg_group="Account Identifier",
+            configured_default="adu_account",
         )
         context.argument(
             "instance_name",
             options_list=["-i", "--instance"],
-            help="Device Update instance name.",
+            help="Device Update instance name."
+            "You can configure the default instance name using `az config set defaults.adu_instance=<name>`.",
             arg_group="Account Identifier",
+            configured_default="adu_instance",
         )
         context.argument(
             "public_network_access",
@@ -169,14 +177,14 @@ def load_deviceupdate_arguments(self, _):
             "search",
             options_list=["--search"],
             help="Request updates matching a free-text search expression. "
-            "Supported by list updates with no constraints.",
+            "Supported when listing updates with no constraints.",
             arg_group="Filter",
         )
         context.argument(
             "filter",
             options_list=["--filter"],
             help="Restricts the set of updates returned by property values. "
-            "Supported by list update versions and list updates with no constraints.",
+            "Supported when listing updates with no constraints or when listing by version.",
             arg_group="Filter",
         )
 
@@ -211,8 +219,18 @@ def load_deviceupdate_arguments(self, _):
         )
 
     with self.argument_context("iot device-update device") as context:
-        context.argument("device_group_id", options_list=["--group-id", "--gid"], help="Device group Id.")
-        context.argument("device_class_id", options_list=["--class-id", "--cid"], help="Device class Id.")
+        context.argument(
+            "device_group_id",
+            options_list=["--group-id", "--gid"],
+            help="Device group Id. This is created from the value of the ADUGroup tag in the connected IoT Hub's "
+            "device/module twin or $default for devices with no tag.",
+        )
+        context.argument(
+            "device_class_id",
+            options_list=["--class-id", "--cid"],
+            help="Device class Id. This is generated from the model Id and the compat properties reported by the "
+            "device update agent in the Device Update PnP interface in IoT Hub. It is a hex-encoded SHA1 hash.",
+        )
 
     with self.argument_context("iot device-update device list") as context:
         context.argument(
@@ -243,7 +261,7 @@ def load_deviceupdate_arguments(self, _):
             options_list=["--best-update"],
             help="Flag indicating the command should fetch the best available update for the device class subgroup including "
             "a count of how many devices need the update. Group Id is required for this flag. "
-            "A best update is the lastest update that meets all compatibility specifications of a device class. ",
+            "A best update is the latest update that meets all compatibility specifications of a device class. ",
             arg_group="Update",
             arg_type=get_three_state_flag(),
         )
@@ -259,15 +277,17 @@ def load_deviceupdate_arguments(self, _):
         context.argument(
             "friendly_name",
             options_list=["--friendly-name"],
-            help="Friendly name associated with the device class.",
+            help="The device class friendly name. The friendly name must be 1 - 100 characters and supports "
+            "alphanumeric, dot and dash values.",
         )
 
     with self.argument_context("iot device-update device class list") as context:
         context.argument(
             "filter",
             options_list=["--filter"],
-            help="Filters device class subgroups based on device class compat property names and values. "
-            "For example \"compatProperties/manufacturer eq 'Contoso'\". --group-id is required to use --filter."
+            help="If provided with --group-id, supports filtering based on device class compat property names "
+            "and values. For example \"compatProperties/manufacturer eq 'Contoso'\". "
+            "Otherwise supports filtering by class friendly name.",
         )
 
     with self.argument_context("iot device-update device group") as context:
@@ -276,7 +296,7 @@ def load_deviceupdate_arguments(self, _):
             options_list=["--best-updates"],
             help="Flag indicating the command should fetch the best available updates for the device group including "
             "a count of how many devices need each update. "
-            "A best update is the lastest update that meets all compatibility specifications of a device class. ",
+            "A best update is the latest update that meets all compatibility specifications of a device class. ",
             arg_group="Update",
             arg_type=get_three_state_flag(),
         )
@@ -305,7 +325,13 @@ def load_deviceupdate_arguments(self, _):
         )
 
     with self.argument_context("iot device-update device deployment") as context:
-        context.argument("deployment_id", options_list=["--deployment-id", "--did"], help="Deployment Id.")
+        context.argument(
+            "deployment_id",
+            options_list=["--deployment-id", "--did"],
+            help="The caller-provided deployment Id. This cannot be longer than 73 characters, "
+            "must be all lower-case, and cannot contain '&', '^', '[', ']', '{', '}', '|', '<', '>', "
+            "forward slash, backslash, or double quote.",
+        )
         context.argument(
             "status",
             options_list=["--status"],

diff --git a/azext_iot/sdk/deviceupdate/dataplane/__init__.py b/azext_iot/sdk/deviceupdate/dataplane/__init__.py
@@ -1,6 +1,6 @@
 # coding=utf-8
 # --------------------------------------------------------------------------
-# Code generated by Microsoft (R) AutoRest Code Generator (autorest: 3.8.4, generator: @autorest/[email protected])
+# Code generated by Microsoft (R) AutoRest Code Generator (autorest: 3.9.2, generator: @autorest/[email protected])
 # Changes may cause incorrect behavior and will be lost if the code is regenerated.
 # --------------------------------------------------------------------------
 

diff --git a/azext_iot/sdk/deviceupdate/dataplane/_configuration.py b/azext_iot/sdk/deviceupdate/dataplane/_configuration.py
@@ -1,6 +1,6 @@
 # coding=utf-8
 # --------------------------------------------------------------------------
-# Code generated by Microsoft (R) AutoRest Code Generator (autorest: 3.8.4, generator: @autorest/[email protected])
+# Code generated by Microsoft (R) AutoRest Code Generator (autorest: 3.9.2, generator: @autorest/[email protected])
 # Changes may cause incorrect behavior and will be lost if the code is regenerated.
 # --------------------------------------------------------------------------
 
@@ -24,12 +24,13 @@ class DeviceUpdateClientConfiguration(Configuration):  # pylint: disable=too-man
 
     :param credential: Credential needed for the client to connect to Azure. Required.
     :type credential: ~azure.core.credentials.TokenCredential
-    :param endpoint: Account endpoint. Required.
+    :param endpoint: The Device Update for IoT Hub account endpoint (hostname only, no protocol).
+     Required.
     :type endpoint: str
-    :param instance_id: Account instance identifier. Required.
+    :param instance_id: The Device Update for IoT Hub account instance identifier. Required.
     :type instance_id: str
-    :keyword api_version: Api Version. Default value is "2022-07-01-preview". Note that overriding
-     this default value may result in unsupported behavior.
+    :keyword api_version: Api Version. Default value is "2022-10-01". Note that overriding this
+     default value may result in unsupported behavior.
     :paramtype api_version: str
     """
 
@@ -41,7 +42,7 @@ def __init__(
         **kwargs: Any
     ) -> None:
         super(DeviceUpdateClientConfiguration, self).__init__(**kwargs)
-        api_version = kwargs.pop('api_version', "2022-07-01-preview")  # type: str
+        api_version = kwargs.pop('api_version', "2022-10-01")  # type: str
 
         if credential is None:
             raise ValueError("Parameter 'credential' must not be None.")

diff --git a/azext_iot/sdk/deviceupdate/dataplane/_device_update_client.py b/azext_iot/sdk/deviceupdate/dataplane/_device_update_client.py
@@ -1,6 +1,6 @@
 # coding=utf-8
 # --------------------------------------------------------------------------
-# Code generated by Microsoft (R) AutoRest Code Generator (autorest: 3.8.4, generator: @autorest/[email protected])
+# Code generated by Microsoft (R) AutoRest Code Generator (autorest: 3.9.2, generator: @autorest/[email protected])
 # Changes may cause incorrect behavior and will be lost if the code is regenerated.
 # --------------------------------------------------------------------------
 
@@ -20,7 +20,7 @@
     from azure.core.credentials import TokenCredential
 
 class DeviceUpdateClient:  # pylint: disable=client-accepts-api-version-keyword
-    """Device Update for IoT Hub is an Azure service that enables customers to publish update for
+    """Device Update for IoT Hub is an Azure service that enables customers to publish updates for
     their IoT devices to the cloud, and then deploy that update to their devices (approve updates
     to groups of devices managed and provisioned in IoT Hub). It leverages the proven security and
     reliability of the Windows Update platform, optimized for IoT devices. It works globally and
@@ -33,12 +33,13 @@ class DeviceUpdateClient:  # pylint: disable=client-accepts-api-version-keyword
     :vartype device_management: deviceupdateclient.operations.DeviceManagementOperations
     :param credential: Credential needed for the client to connect to Azure. Required.
     :type credential: ~azure.core.credentials.TokenCredential
-    :param endpoint: Account endpoint. Required.
+    :param endpoint: The Device Update for IoT Hub account endpoint (hostname only, no protocol).
+     Required.
     :type endpoint: str
-    :param instance_id: Account instance identifier. Required.
+    :param instance_id: The Device Update for IoT Hub account instance identifier. Required.
     :type instance_id: str
-    :keyword api_version: Api Version. Default value is "2022-07-01-preview". Note that overriding
-     this default value may result in unsupported behavior.
+    :keyword api_version: Api Version. Default value is "2022-10-01". Note that overriding this
+     default value may result in unsupported behavior.
     :paramtype api_version: str
     :keyword int polling_interval: Default waiting time between two polls for LRO operations if no
      Retry-After header is present.

diff --git a/azext_iot/sdk/deviceupdate/dataplane/_vendor.py b/azext_iot/sdk/deviceupdate/dataplane/_vendor.py
@@ -1,5 +1,5 @@
 # --------------------------------------------------------------------------
-# Code generated by Microsoft (R) AutoRest Code Generator (autorest: 3.8.4, generator: @autorest/[email protected])
+# Code generated by Microsoft (R) AutoRest Code Generator (autorest: 3.9.2, generator: @autorest/[email protected])
 # Changes may cause incorrect behavior and will be lost if the code is regenerated.
 # --------------------------------------------------------------------------
 

diff --git a/azext_iot/sdk/deviceupdate/dataplane/_version.py b/azext_iot/sdk/deviceupdate/dataplane/_version.py
@@ -1,6 +1,6 @@
 # coding=utf-8
 # --------------------------------------------------------------------------
-# Code generated by Microsoft (R) AutoRest Code Generator (autorest: 3.8.4, generator: @autorest/[email protected])
+# Code generated by Microsoft (R) AutoRest Code Generator (autorest: 3.9.2, generator: @autorest/[email protected])
 # Changes may cause incorrect behavior and will be lost if the code is regenerated.
 # --------------------------------------------------------------------------
 

diff --git a/azext_iot/sdk/deviceupdate/dataplane/aio/__init__.py b/azext_iot/sdk/deviceupdate/dataplane/aio/__init__.py