通过

如何使用 Azure CLI 自动迁移 IoT 中心

  • 项目

使用 Azure CLI 将 IoT 中心迁移到新区域、新层或新配置。

如果想要执行以下操作，本文中的步骤将会非常有用：

  • 从免费层升级到基本层或标准层 IoT 中心。
  • 将 IoT 中心移动到新区域。
  • 将 IoT 中心状态信息导出为备份。
  • 增加 IoT 中心的分区数目。
  • 为开发环境而不是生产环境设置中心。

比较自动和手动迁移步骤

本文的结果类似于如何使用 Azure 资源管理器模板迁移 Azure IoT 中心，但过程不同。 在开始之前，请确定适用于方案的过程。

  • Azure CLI 过程（本文）：

    • 迁移设备注册表、路由和终结点信息，以及其他配置详细信息，例如 IoT Edge 部署或自动设备管理配置。
    • 迁移少量设备（例如，最多 10,000 台）更轻松。
    • 不需要 Azure 存储帐户。
    • 收集路由和文件上传终结点的连接字符串，并将其包含在 ARM 模板输出中。

  • 手动过程：

    • 迁移设备注册表以及路由和终结点信息。 必须在新的 IoT 中心手动重新创建其他配置详细信息。
    • 迁移大量设备（例如，超过 100,000 台）的速度更快。
    • 使用 Azure 存储帐户传输设备注册表。
    • 从 ARM 模板输出中清理路由和文件上传终结点的连接字符串，而且需要手动重新添加这些字符串。

先决条件

  • Azure CLI

    本文中所述的功能需要 0.20.0 或更高版本的 azure-iot 扩展。 要检查扩展版本，请运行 az --version。 若要更新扩展，请运行 az extension update --name azure-iot。

    如果仍然安装旧版 azure-cli-iot-ext 扩展，请先移除该扩展，然后再添加 azure-iot 扩展。

IoT 中心状态

在谈到迁移 IoT 中心的状态时，我们指的是三个方面的组合：

  • Azure 资源管理器 (ARM) 资源。 这是可在资源模板中定义的所有内容，并且与从 Azure 门户中的 IoT 中心导出资源模板时获取的信息相同。 作为 Azure 资源管理器方面的一部分所捕获的信息包括：

    • 内置事件中心的保留时间
    • 证书
    • 云到设备属性
    • 禁用设备 SAS
    • 禁用本地身份验证
    • 启用文件上传通知
    • 文件上传存储终结点
    • 标识
      • 用户分配的标识
      • 系统分配的标识（已启用或已禁用）
    • 网络规则集
    • 路由
      • 自定义终结点
      • 回退路由
      • 路由
    • 标记

  • 配置。 此方面适用于未在 ARM 模板中表示的 IoT 中心的各个方面。 具体而言，此方面涵盖了自动设备管理配置和 IoT Edge 部署。

  • 设备。 此方面表示设备注册表中的信息，其中包括：

    • 设备标识和孪生
    • 模块标识和孪生

未在此处列出的任何 IoT 中心属性或配置可能无法正确导出或导入。

导出 IoT 中心的状态

使用 az iot hub state export 命令将 IoT 中心的状态导出到 JSON 文件。

如果要在一个命令中同时运行导出和导入步骤，请参阅本文后面的迁移 IoT 中心部分。

在导出 IoT 中心的状态时，可以选择导出哪些方面。

参数 详细信息
--aspects 要导出的状态方面。 指定一个或多个接受的值：arm、配置或设备。 如果忽略此参数，则导出所有三个方面。
--state-file -f 写入状态信息的文件的路径。
--replace -r 如果包含此参数，则 export 命令将覆盖状态文件的内容。
--hub-name -n
or
--login -l		 源 IoT 中心的名称（-n）或源 IoT 中心的连接字符串（-l）。 如果同时提供两者，则连接字符串优先。
--resource-group -g 源 IoT 中心资源组的名称。

以下示例可将 IoT 中心状态的所有方面导出到名为 myHub-state 的文件：

az iot hub state export --hub-name myHub --state-file ./myHub-state.json

以下示例仅导出 IoT 中心状态的设备和 Azure 资源管理器方面，并覆盖现有文件的内容：

az iot hub state export --hub-name myHub --state-file ./myHub-state.json --aspects arm devices --replace

导出终结点

如果选择导出 IoT 中心的 Azure 资源管理器方面，则 export 命令会检索具有基于密钥身份验证的任何终结点的连接字符串，并将其包含在输出 ARM 模板中。

export 命令还会检查所有终结点，以验证它连接到的资源是否仍然存在。 如果不存在，则不会导出该终结点以及使用该终结点的任何路由。

导入 IoT 中心的状态

使用 az iot hub state import 命令将状态信息从导出的文件导入到新的或现有 IoT 中心。

如果要在一个命令中同时运行导出和导入步骤，请参阅本文后面的迁移 IoT 中心部分。

参数 详细信息
--aspects 要导入的状态方面。 指定一个或多个接受的值：arm、配置或设备。 如果忽略此参数，则导入所有三个方面。
--state-file -f 导出的状态文件的路径。
--replace -r 如果包含此参数，则 import 命令将删除目标中心的当前状态。
--hub-name -n
or
--login -l		 目标 IoT 中心的名称（-n），或目标 IoT 中心的连接字符串（-l）。 如果同时提供两者，则连接字符串优先。
--resource-group -g 目标 IoT 中心资源组的名称。

以下示例会将所有方面导入到新的 IoT 中心，如果尚不存在，则会创建该中心：

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json

以下示例仅将设备和配置方面导入到必须已经存在的新 IoT 中心，并覆盖任何现有的设备和配置：

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json --aspects devices configurations --replace

通过状态导入创建新的 IoT 中心

可以使用 az iot hub state import 命令创建新的 IoT 中心或写入到现有 IoT 中心。

如果要创建新的 IoT 中心，则必须在导入命令中包含 arm 方面。 如果命令中未包含 arm，并且目标中心不存在，则导入命令将失败。

如果目标中心不存在，则导入命令还需要使用 --resource-group 参数。

通过状态导入更新现有 IoT 中心

如果目标 IoT 中心已存在，则 az iot hub state import 命令不需要 arm 方面。 如果确实包含了 arm 方面，则除以下在创建中心后无法更改的属性外，将会覆盖所有资源属性：

  • 位置
  • SKU
  • 内置事件中心分区计数
  • 数据驻留
  • 功能

如果在导入命令中指定了 --resource-group，并且它不同于 IoT 中心的当前资源组，则该命令会失败，因为它会尝试创建一个与已存在的中心同名的新中心。

如果在导入命令中包含 --replace 标记，则在上传中心状态之前，将从目标中心移除以下 IoT 中心方面：

  • ARM：将删除目标中心上的任何已上传证书。 如果证书存在，则需要更新实体标记。
  • 设备：删除所有设备和模块（包括边缘和非边缘）。
  • 配置：删除所有 ADM 配置和 IoT Edge 部署。

迁移 IoT 中心

使用 az iot hub state migrate 命令将一个 IoT 中心的状态迁移到新的或现有的 IoT 中心。

此命令可将导出和导入步骤包装到单个命令中，但没有输出文件。 导出 IoT 中心的状态和导入 IoT 中心的状态部分中介绍的所有指导和限制也适用于 state migrate 命令。

例如，如果要迁移包含许多设备的设备注册表（例如，数百台或数千台），则可能会发现单独运行导出和导入命令要比运行迁移命令更简单、更快。

参数 详细信息
--aspects 要迁移的状态方面。 指定一个或多个接受的值：arm、配置或设备。 如果忽略此参数，则迁移所有三个方面。
--replace -r 如果包含此参数，则迁移命令将删除目标中心的当前状态。
--destination-hub --dh
or
--destination-hub-login --dl		 目标 IoT 中心的名称（--dh），或目标 IoT 中心的连接字符串（--dl）。 如果同时提供两者，则连接字符串优先。
--destination-resource-group --dg 目标 IoT 中心资源组的名称。 如果目标中心不存在，则需要使用目标资源组。
--origin-hub --oh
or
--origin-hub-login --ol		 源 IoT 中心的名称（--oh）或源 IoT 中心的连接字符串（--ol）。 如果同时提供两者，则连接字符串优先。 使用连接字符串可避免必须登录到 Azure CLI 会话。
--origin-resource-group --og 源 IoT 中心资源组的名称。

以下示例可将源中心的所有方面迁移到目标中心，如果目标中心不存在，则会创建该中心：

az iot hub state migrate --origin-hub myHub --origin-resource-group myGroup  --destination-hub myNewHub --destination-resource-group myNewGroup

排查迁移问题

如果无法导出或导入设备或配置，请检查是否有权访问这些属性。 验证访问权限的一种方法是运行 az iot hub device-identity list 或 az iot hub configuration list 命令。

如果 az iot hub state migrate 命令失败，可尝试单独运行导出和导入命令。 这两个命令会分别生成与 migrate 命令相同的功能，但通过单独运行它们，可以查看根据 import 命令创建的状态文件。

后续步骤

有关对 IoT 中心内的标识注册表执行批量操作的详细信息，请参阅导入和导出 IoT 中心设备标识。