Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon IoT Core for Amazon Sidewalk API operations for bulk provisioning

You can perform the following API operations for bulk provisioning your Sidewalk end devices:

The following sections show you how to get, list, update, and delete import tasks. For information about creating import tasks, see Amazon IoT Core for Amazon Sidewalk API operations for bulk provisioning.

Get information about your import task

You can use the ListDevicesForWirelessDeviceImportTask API operation to retrieve information about a particular import task and the onboarding status of devices in that task. As input to the API operation, specify the import task ID that you obtained from either the StartWirelessDeviceImportTask or StartSingleWirelessDeviceImportTask API operations. The API will then return information about the import task matching the specified identifier.

The following shows an example CLI command:

aws iotwireless list-devices-for-wireless-device-import-task --id e2a5995e-743b-41f2-a1e4-3ca6a5c5249f

Running this command returns your import task information and device onboarding status.

{
   "DestinationName": "SidewalkDestination",
   "ImportedWirelessDeviceList": [ 
      { 
         "Sidewalk": { 
            "OnboardingStatus": "ONBOARDED",
            "LastUpdateTime": "2023-02021T06:11:09.151Z",
            "SidewalkManufacturingSn": "82B83C8B35E856F43CE9C3D59B418CC96B996071016DB1C3BE5901F0F3071A4A"
         },
         "Sidewalk": {
             "OnboardingStatus": "PENDING",
             "LastUpdateTime": "2023-02021T06:22:12.061Z",
             "SidewalkManufacturingSn": "12345ABCDE6789FABDESBDEF123456789012345FEABC0123679AFEBC01234EF"
         },        
      }
   ]
}

Get import task device summary

To get a count of summary information of the onboarding status of devices that you added to a particular import task, use the GetWirelessDeviceImportTask API operation. The following shows an example CLI command.

aws iotwireless get-wireless-device-import-task --Id "e2a5995e-743b-41f2-a1e4-3ca6a5c5249f"

The following code shows a sample response from the command.

{
   "NumberOfFailedImportedDevices": 2,
   "NumberOfOnboardedImportedDevices": 4,
   "NumberOfPendingImportedDevices": 1
}

Add devices to import task

Use the UpdateWirelessDeviceImportTask API operation to add devices to an existing import task that you added. You can use this API operation to add the serial numbers (SMSN) of devices that were not previously included the task that you created using the StartWirelessDeviceImportTask API operation.

To append devices to the import task, as part of the API request, specify a new CSV file in an Amazon S3 bucket that contains the serial numbers of devices to be added. The request will be accepted only if the onboarding process hasn't already started for devices that are currently in the import task. If the onboarding process has already started, then the UpdateWirelessDeviceImportTask API request will fail.

If you still want to append devices to the import task, you can perform the UpdateWirelessDeviceImportTask API operation a second time. Before you perform this API operation, the first UpdateWirelessDeviceImportTask API request must have completed processing the CSV file in the S3 bucket.

The following shows an example CLI command.

aws iotwireless update-wireless-device-import task \
    --Id "e2a5995e-743b-41f2-a1e4-3ca6a5c5249f" \
    --sidewalk '{"FileForCreateDevices": "s3://import_task_bucket/import_file3"}'

List import tasks in your Amazon Web Services account

Use the ListWirelessDeviceImportTasks API or the list-imported-wireless-device-tasks CLI command to list import tasks in your Amazon Web Services account. The following shows an example CLI command.

aws iotwireless list-wireless-device-import-tasks

Running this command returns a list of import tasks that you created. The list includes their Amazon S3 CSV files and the IAM role that was specified, the import task ID, and summary information of the device onboarding status.

{
   "ImportWirelessDeviceTaskList": [ 
      { 
         "FileForCreateDevices": "s3://import_task_bucket/import_file1",
         "ImportTaskId": "e2a5995e-743b-41f2-a1e4-3ca6a5c5249f",
         "NumberOfFailedImportedDevices": 1,
         "NumberOfOnboardedImportedDevices": 3,
         "NumberOfPendingImportedDevices": 2,
         "Role": "arn:aws:iam::123456789012:role/service-role/ACF1zBEI",
         "TimeStamp": "1012202218:23:55"
      },
      { 
         "FileForCreateDevices": "s3://import_task_bucket/import_file2",
         "ImportTaskId": "a1b234c5-67ef-21a2-a1b2-3cd4e5f6789a",
         "NumberOfFailedImportedDevices": 2,
         "NumberOfOnboardedImportedDevices": 4,
         "NumberOfPendingImportedDevices": 1,
         "Role": "arn:aws:iam::123456789012:role/service-role/CDEFaBC1",
         "TimeStamp": "1201202210:12:20"
      }      
   ]
}

Delete import tasks from your Amazon Web Services account

To delete an import task, pass the import task ID to the DeleteWirelessDeviceImportTask API operation or the delete-wireless-device-import-task CLI command.

When you perform the DeleteWirelessDeviceImportTask API request, a background process starts deleting the import task. When the request is in progress, the serial numbers (SMSN) of devices in the import tasks are in the process of deletion. Only after the deletion has completed, you'll be able to see this information using the ListImportedWirelessDeviceTasks or the GetImportedWirelessDeviceTasks API operations.

If an import task still contains devices that are waiting to be onboarded, the DeleteWirelessDeviceImportTask API request will be processed only after all the devices in the import task have either onboarded or failed to onboard. An import task expires after 90 days, and once the task has expired, it can be deleted from your account. However, devices that were onboarded successfully using the import task will not be deleted.

The following shows an example CLI command:

aws iotwireless delete-import-task --Id "e2a5995e-743b-41f2-a1e4-3ca6a5c5249f"

This command doesn't produce any output. After the task has been deleted, to verify that the import task has been removed from your account, you can use the GetWirelessDeviceImportTask API operation or the ListWirelessDeviceImportTasks API operation.