# 使用导入任务预置 Sidewalk 设备 本节介绍如何使用 AWS IoT 控制台、适用于 Amazon Sidewalk 的 AWS IoT Core API 操作或 AWS CLI 批量预置 Sidewalk 设备。下列各部分说明如何批量预置 Sidewalk 设备。 **Topics** + [Sidewalk 批量预置的工作原理](#provision-bulk-works) + [Sidewalk 批量预置的关键注意事项](#provision-bulk-considerations) + [CSV 文件格式](#provision-csv-format) + [如何使用 Sidewalk 批量预置](#provision-bulk-use) + [批量预置 Sidewalk 设备](sidewalk-bulk-provision-how.md) + [查看导入任务和设备登记状态](sidewalk-bulk-provision-status.md) ## Sidewalk 批量预置的工作原理 以下步骤说明了批量预置的工作原理。 1. **启动无线设备导入任务** 要批量预置 Sidewalk 设备，必须创建导入任务并提供要登记到适用于 Amazon Sidewalk 的 AWS IoT Core 的设备的 Sidewalk 制造序列号（SMSN）。在制造商将控制日志上传到 Amazon Sidewalk 后，您便通过电子邮件，以 CSV 文件的形式获得了设备的 Sidewalk 制造序列号（SMSN）。有关工作流以及如何获取控制日志的更多信息，请参阅《Amazon Sidewalk 文档》**中的[制造 Amazon Sidewalk 设备](https://docs.sidewalk.amazon/manufacturing/)。 1. **在后台运行导入进程** 当适用于 Amazon Sidewalk 的 AWS IoT Core 收到导入任务请求时，它开始设置事物，并启动一个频繁轮询系统的后台进程。后台进程收到导入任务指令后，就会开始读取 CSV 文件。适用于 Amazon Sidewalk 的 AWS IoT Core 同时检查是否已从 Amazon Sidewalk 收到控制日志。 1. **创建无线设备记录** 从 Amazon Sidewalk 收到控制日志后，适用于 Amazon Sidewalk 的 AWS IoT Core 会检查控制日志中的序列号是否与 CSV 文件中的 SMSN 值匹配。如果序列号匹配，适用于 Amazon Sidewalk 的 AWS IoT Core 将开始为与这些序列号对应的 Sidewalk 设备创建无线设备记录。登记所有设备后，导入任务将标记为*已完成*。 ## Sidewalk 批量预置的关键注意事项 在将 Sidewalk 设备批量预置到适用于 Amazon Sidewalk 的 AWS IoT Core 时，请关注以下一些主要注意事项。 + 您必须在创建设备配置文件的同一 AWS 账户中使用 AWS IoT 控制台或适用于 Amazon Sidewalk 的 AWS IoT Core API 操作执行批量预置。 + 在批量预置 Sidewalk 设备之前，设备配置文件必须已经包含表明工厂支持的 DAK 信息。否则，使用 AWS IoT 控制台进行批量预置或批量预置 API 操作可能会失败。 + 开始导入任务后，处理 CSV 文件、导入无线设备并将其登记到适用于 Amazon Sidewalk 的 AWS IoT Core 可能至少需要 10 分钟或更长时间。 + 无线设备导入任务一旦启动，就将运行达 90 天。在此期间，它会检查是否已从 Amazon Sidewalk 收到控制日志。如果在 90 天届满前未从 Amazon Sidewalk 收到控制日志，则当您查看任务详细信息时，该任务将标记为*已完成*，并显示一条消息表明该任务已过期。导入任务中等待控制日志的设备的登记状态将标记为*失败*。 + 当您尝试更新已创建的导入任务时，只能向该任务添加其他设备。在创建导入任务之后和在已添加到导入任务的设备上启动任务之前，您可以随时添加新设备。如果更新文件包含原始导入任务中已存在的设备的序列号，则这些序列号将被忽略。 + 当您请求更新操作时，将代入与您在创建导入任务时使用的相同 IAM 角色来访问 Amazon S3 桶中的 CSV 文件。 + 只有当导入任务已成功完成或任务更新失败时，才能删除该任务。在提供错误的 IAM 角色或找不到 Amazon S3 桶文件等情况下，任务可能无法更新。如果导入任务处于 `PENDING` 状态，则无法更新或删除此任务。 + 您导入到任务中的 CSV 文件必须使用下一部分中描述的格式。 ## CSV 文件格式 Amazon S3 桶中所包含的您为导入任务指定的 CSV 文件必须使用以下格式： + 第 1 行必须使用关键字 `smsn`，表示正在导入的 CSV 文件包含要导入的设备的 SMSN。 + 第 2 行及之后的行必须包含要登记的设备的 SMSN。设备 SMSN 必须采用 64 个十六进制字符格式。 此 JSON 文件显示了一个 CSV 文件格式示例。 ``` smsn 1C1A10B0AC0A200C012BBAC2CBB1B21CB12C0CA2AC1C1BB22CAA01C1B0B01122 B122C2B1121BACA2221001AC1B22012AAC11112C11C2A100C1C2B012A1100C10 02B222C110B0A210B0A0C2C112CCCAC21C1C0B0AA1221AB1022A2CC11B1B1122 C2C021CA1C111CCAB1221C0021C1C2AAA0AA1A2A01ABC10CBAACCA2A0121022A 0CB22C01BBC2CA2C0B11001121ACB2ABB0BB0121C2BA101C012CC2B20C011AC0 ``` ## 如何使用 Sidewalk 批量预置 下列步骤向您展示如何使用 Amazon Sidewalk 批量预置。 1. **提供设备序列号** 要预置 Sidewalk 设备，您必须提供要登记的设备的序列号。您可以使用以下任一方法来预置设备。 + 使用各台设备的 Sidewalk 制造序列号（SMSN）单独预置每台设备。如果您想测试工作流并更快地登记设备，而不必使用相应的 IAM 角色上传 CSV 文件，也不必等待设备准备好登记到此任务，则此方法很有用。 + 通过提供 Amazon S3 桶 URL 来批量预置设备，该 URL 带有包含待预置设备的 SMSN 的 CSV 文件路径。当您有大量设备要登记时，此方法尤其有用。在这种情况下，单独登记每台设备可能工作量很大。相反，您只需提供指向已上传到 Amazon S3 桶的 CSV 文件的路径以及访问该文件的 IAM 角色即可。 1. **获取导入任务和设备登记状态** 对于您创建的每个导入任务，您可以检索有关任务登记状态和添加到任务中的设备的登记状态的信息。您还可以查看其他状态信息，例如任务或设备登记失败的原因。有关更多信息，请参阅 1. **（可选）更新或删除导入任务** 您可以更新或删除已创建的导入任务。 + 在已添加的设备上开始导入任务之前，您可以随时更新导入任务并向该任务添加其他设备。适用于 Amazon Sidewalk 的 AWS IoT Core 代入您在创建导入任务时使用的相同 IAM 角色。创建任务时，请指定新的 CSV 文件，其中包含要添加到任务中的设备的序列号。 **注意** 更新现有导入任务时，只能向任务中添加设备。适用于 Amazon Sidewalk 的 AWS IoT Core 在导入任务中已经存在的设备与您试图添加到任务中的设备之间执行并集操作。如果新文件包含导入任务中已存在的设备的序列号，则这些序列号将被忽略。 + 您可以删除已成功完成的导入任务，也可以删除在 IAM 角色信息不正确或在创建或更新任务时 S3 桶文件不可用等情况下未能更新的导入任务。 **Topics** + [Sidewalk 批量预置的工作原理](#provision-bulk-works) + [Sidewalk 批量预置的关键注意事项](#provision-bulk-considerations) + [CSV 文件格式](#provision-csv-format) + [如何使用 Sidewalk 批量预置](#provision-bulk-use) + [批量预置 Sidewalk 设备](sidewalk-bulk-provision-how.md) + [查看导入任务和设备登记状态](sidewalk-bulk-provision-status.md) # 批量预置 Sidewalk 设备 本节介绍如何使用 AWS IoT 控制台和 AWS CLI 将 Sidewalk 设备批量预置到适用于 Amazon Sidewalk 的 AWS IoT Core。 ## 批量预置 Sidewalk 设备（控制台） 要使用 AWS IoT 控制台添加 Sidewalk 设备，请转到[设备中心的 Sidewalk 选项卡](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk)，选择**批量预调配设备**，然后执行以下步骤。 ![\[alt text not found\]](http://docs.aws.amazon.com/zh_cn/iot-wireless/latest/developerguide/images/sidewalk-bulk-provision.PNG) 1. **选择导入方法** 指定如何将要登记的设备批量导入适用于 Amazon Sidewalk 的 AWS IoT Core。 + 要使用 SMSN 预置单个设备，请选择**预置单个受工厂支持的设备**。 + 要通过提供包含设备列表及其 SMS 的 CSV 文件来批量预置设备，请选择**使用 S3 桶**。 1. **指定要登记的设备** 根据您选择登记设备的方法，添加设备信息及其序列号。 1. 如果您选择**预置单个受工厂支持的设备**，请指定以下信息： 1. 要登记的每个设备的**名称**。名称在您的 AWS 账户和 AWS 区域中必须是唯一的。 1. 设备的 Sidewalk 制造序列号（SMSN）位于**输入 SMSN** 字段中。 1. 一个**目标**，描述将消息从设备路由到其他 AWS 服务的 IoT 规则。 1. 如果您选择**使用 S3 桶**： 1. 提供 **S3 桶目标**信息，其中包含 S3 URL 信息。要提供您的 CSV 文件，请选择**浏览 S3**，然后选择要使用的 CSV 文件。 适用于 Amazon Sidewalk 的 AWS IoT Core 会自动填充 S3 URL，这是指向 S3 桶中 CSV 文件的路径。`s3://bucket_name/file_name` 路径的格式为：要在 [Amazon Simple Storage Service](https://console.aws.amazon.com/s3/)控制台中查看文件，选择 **View**（查看）。 1. 提供 **S3 预置角色**，该角色允许适用于 Amazon Sidewalk 的 AWS IoT Core 代表您访问 S3 桶中的 CSV 文件。您可以创建新的服务角色或选择现有角色。 要创建新角色，您可以提供**角色名称**，也可以将其留空以自动生成随机名称。 1. 提供一个**目标**，描述将消息从设备路由到其他 AWS 服务的 IoT 规则。 1. 开始导入任务 提供任何可选标签作为名称/值对，然后选择**提交**以开始无线设备导入任务。 ## 批量预置 Sidewalk 设备（CLI） 要针对适用于 Amazon Sidewalk 的 AWS IoT Core 将 Sidewalk 设备登记到您的账户，请使用以下任一 API 操作，具体取决于您是要单独添加设备，还是通过提供 S3 桶中包含的 CSV 文件来添加设备。 + **使用 S3 CSV 文件批量上传设备** 要通过提供 S3 桶中的 CSV 文件来批量上传设备，请使用 [https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_StartWirelessDeviceImportTask.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_StartWirelessDeviceImportTask.html) API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-wireless-device-import-task.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-wireless-device-import-task.html) AWS CLI 命令。创建任务时，请指定指向 Amazon S3 桶中 CSV 文件的路径，以及授予适用于 Amazon Sidewalk 的 AWS IoT Core 访问 CSV 文件的权限的 IAM 角色。 任务开始运行后，适用于 Amazon Sidewalk 的 AWS IoT Core 将开始读取 CSV 文件，并将文件中的序列号（SMSN）与从 Amazon Sidewalk 收到的控制日志中的相应信息进行比较。当序列号匹配时，它将开始创建与这些序列号对应的无线设备记录。 以下命令显示了创建导入任务的示例： ``` aws iotwireless start-wireless-device-import-task \ --cli-input-json "file://task.json" ``` 下面显示的是 `task.json` 文件的内容。 **task.json 的内容** ``` { "DestinationName": "Sidewalk_Destination", "Sidewalk": { "DeviceCreationFile": "s3://import_task_bucket/import_file1", "Role": "arn:aws:iam::123456789012:role/service-role/ACF1zBEI" } } ``` 运行此命令会返回导入任务的 ID 和 ARN。 ``` { "Arn": "arn:aws:iotwireless:us-east-1:123456789012:ImportTask/a1b234c5-67ef-21a2-a1b2-3cd4e5f6789a" "Id": "a1b234c5-67ef-21a2-a1b2-3cd4e5f6789a" } ``` + **使用 SMSN 单独预置设备** 要使用 SMSN 单独预置设备，请使用 [https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_StartSingleWirelessDeviceImportTask.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_StartSingleWirelessDeviceImportTask.html) API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-single-wireless-device-import-task.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-single-wireless-device-import-task.html) AWS CLI 命令。创建任务时，请指定 Sidewalk 目标和要登记的设备的序列号。 当序列号与从 Amazon Sidewalk 收到的控制日志中的相应信息匹配时，任务将运行并创建无线设备记录。 以下命令显示了创建导入任务的示例： ``` aws iotwireless start-single-wireless-device-import-task \ --destination-name sidewalk_destination \ --sidewalk '{"SidewalkManufacturingSn": "82B83C8B35E856F43CE9C3D59B418CC96B996071016DB1C3BE5901F0F3071A4A"}' ``` 运行此命令会返回导入任务的 ID 和 ARN。 ``` { "Arn": "arn:aws:iotwireless:us-east-1:123456789012:ImportTask/e2a5995e-743b-41f2-a1e4-3ca6a5c5249f" "Id": "e2a5995e-743b-41f2-a1e4-3ca6a5c5249f" } ``` ## 更新或删除导入任务 如果要向导入任务中添加其他设备，可以更新该任务。如果您不再需要该任务或任务失败，也可以删除该任务。有关何时更新或删除任务的信息，请参阅[如何使用 Sidewalk 批量预置](sidewalk-provision-bulk-import.md#provision-bulk-use)。 **警告** 删除是永久性操作，无法撤消。删除已成功完成的导入任务将不会移除已使用该任务登记的终端设备。 要更新或删除导入任务，请执行以下操作： + **使用 AWS IoT控制台** 下列步骤说明如何使用 AWS IoT 控制台更新或删除导入任务。 **要更新导入任务，请执行下列操作：** 1. 转至 AWS IoT 控制台的 [Sidewalk 设备中心](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk)。 1. 选择要更新的导入任务，然后选择**编辑**。 1. 提供另一个 S3 文件，其中包含要添加到任务中的设备的序列号，然后选择**提交**。 **要删除导入任务，请执行以下操作：** 1. 转至 AWS IoT 控制台的 [Sidewalk 设备中心](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk)。 1. 选择要删除的任务，然后选择**删除**。 + **使用 AWS IoT Wireless API 或 AWS CLI** 使用以下 AWS IoT Wireless API 操作或 CLI 命令更新或删除您的导入任务。 + **[https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_UpdateWirelessDeviceImportTask.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_UpdateWirelessDeviceImportTask.html) API 或 [https://docs.aws.amazon.com/cli/latest/reference/update-wireless-device-import-task.html](https://docs.aws.amazon.com/cli/latest/reference/update-wireless-device-import-task.html) CLI** 此 API 操作将 Amazon S3 CSV 文件的内容附加到现有的导入任务。您只能添加以前未包含在任务中的设备的序列号。 + **[https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_DeleteWirelessDeviceImportTask.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_DeleteWirelessDeviceImportTask.html) API 或 [https://docs.aws.amazon.com/cli/latest/reference/delete-wireless-device-import-task.html](https://docs.aws.amazon.com/cli/latest/reference/delete-wireless-device-import-task.html) CLI** 此 API 操作使用导入任务 ID 删除标记为待删除的导入任务。 # 查看导入任务和设备登记状态 您的无线设备导入任务和添加到该任务中的 Sidewalk 设备可能具有以下状态消息之一。您将看到这些消息显示在 AWS IoT 控制台中，或者，当您使用任何 AWS IoT Wireless API 操作或 AWS CLI 命令来检索有关这些任务及其设备的信息时，也会看到这些信息。 ## 查看导入任务状态信息 创建导入任务后，您可以查看您创建的导入任务以及添加到该任务中的设备的登记状态。登记状态指示待登记的设备数量、已成功登记的设备数量以及未能登记的设备数量。 刚创建导入任务后，**待处理计数**将显示一个与已添加的设备数量相对应的值。任务开始并读取 CSV 文件以创建无线设备记录后，随着设备成功登记，**待处理计数**将减少，而**成功计数**将增加。如果任何设备登记失败，则**失败计数**将增加。 要查看导入任务和设备登记状态，请执行以下操作： + **使用 AWS IoT控制台** 在 AWS IoT 控制台的 [Sidewalk 设备中心](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk)中，您可以看到您创建的导入任务以及设备登记状态信息摘要的计数。如果您查看您创建的任何导入任务的详细信息，则可以看到有关设备登记状态的其他信息。 + **使用 AWS IoT Wireless API 或 AWS CLI** 要查看设备登记状态，请使用以下任一 AWS IoT Wireless API 操作或相应的 AWS CLI 命令。 + **[https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_ListWirelessDeviceImportTasks.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_ListWirelessDeviceImportTasks.html) API 或 [https://docs.aws.amazon.com/cli/latest/reference/list-wireless-device-import-tasks.html](https://docs.aws.amazon.com/cli/latest/reference/list-wireless-device-import-tasks.html) CLI** 此 API 操作返回有关已针对 AWS IoT Wireless 添加到您的账户中的所有导入任务及其状态的信息。它还会返回这些任务中 Sidewalk 设备登记状态摘要的计数。 + **[https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_ListDevicesForWirelessDeviceImportTask.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_ListDevicesForWirelessDeviceImportTask.html) API 或 [https://docs.aws.amazon.com/cli/latest/reference/list-devices-for-wireless-device-import-task.html](https://docs.aws.amazon.com/cli/latest/reference/list-devices-for-wireless-device-import-task.html) CLI** 此 API 操作返回有关指定的导入任务及其状态的信息，以及有关已添加到导入任务中的所有 Sidewalk 设备及其登记状态信息。 + **[https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetWirelessDeviceImportTask.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetWirelessDeviceImportTask.html) API 或 [https://docs.aws.amazon.com/cli/latest/reference/get-wireless-device-import-task.html](https://docs.aws.amazon.com/cli/latest/reference/get-wireless-device-import-task.html) CLI** 此 API 操作返回有关指定的导入任务及其状态的信息，以及该任务中 Sidewalk 设备的登记状态摘要的计数。 ## 导入任务状态 在您的 AWS 账户中创建的导入任务可能具有以下状态消息之一。状态表示您的导入任务是已开始处理、已完成还是失败。还可以使用 AWS IoT 控制台或任何 AWS IoT Wireless API 操作的 `StatusReason` 参数来检索其他状态详细信息。 + **INITIALIZING** 适用于 Amazon Sidewalk 的 AWS IoT Core 已收到无线设备导入任务请求并且正在设置任务。 + **INITIALIZED** 适用于 Amazon Sidewalk 的 AWS IoT Core 已完成导入任务设置，正在等待控制日志到达，以便它可以使用设备的序列号（SMSN）导入设备并继续处理任务。 + **PENDING** 导入任务正在队列中等待处理。适用于 Amazon Sidewalk 的 AWS IoT Core 正在评估处理队列中的其他任务。 + **COMPLETE** 导入任务已处理并已完成。 + **FAILED** 导入任务或设备任务失败。您可以使用 `StatusReason` 参数来确定导入任务失败的原因，例如验证异常。 + **DELETING** 导入任务已标记为待删除，正在删除中。 ## 设备登记状态 您添加到导入任务中的 Sidewalk 设备可能具有以下状态消息之一。状态表明您的设备是已准备好供登记、已登记还是无法登记。还可以使用 AWS IoT 控制台或 AWS IoT Wireless API 操作 `ListDevicesForWirelessDeviceImportTask` 的 `OnboardingStatusReason` 参数来检索其他状态详细信息。 + **INITIALIZED** 适用于 Amazon Sidewalk 的 AWS IoT Core 已完成导入任务设置，正在等待控制日志到达，以便它可以使用设备的序列号（SMSN）导入设备并继续处理任务。 + **PENDING** 导入任务正在队列中等待处理并开始将设备登记到该任务。适用于 Amazon Sidewalk 的 AWS IoT Core 正在评估处理队列中的其他任务。 + **ONBOARDED** Sidewalk 设备已成功登记到导入任务。 + **FAILED** 导入任务或设备任务失败，Sidewalk 设备未能登记到任务。您可以使用 `OnboardingStatusReason` 参数来检索有关设备登记失败原因的更多详细信息。