如何使用 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 -nor --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 -nor --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 --dhor --destination-hub-login --dl |
目标 IoT 中心的名称（--dh），或目标 IoT 中心的连接字符串（--dl）。 如果同时提供两者，则连接字符串优先。 |
--destination-resource-group --dg |
目标 IoT 中心资源组的名称。 如果目标中心不存在，则需要使用目标资源组。 |
--origin-hub --ohor --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 中心设备标识。