Procedimiento para usar la API REST de IoT Central para carga un archivo
IoT Central le permite cargar medios y otros archivos desde dispositivos conectados al almacenamiento en la nube. Configure la funcionalidad de carga de archivos en la aplicación IoT Central y a continuación implemente cargas de archivos en el código del dispositivo. En este artículo, aprenderá a:
- Usar la API REST para configurar la funcionalidad de carga de archivos en la aplicación de IoT Central.
- Probar la carga de archivos mediante la ejecución de código de dispositivo de ejemplo.
La API de REST de IoT Central le permite:
- Agregar una configuración de la cuenta de almacenamiento de carga de archivos
- Actualizar una configuración de la cuenta de almacenamiento de carga de archivos
- Obtener la configuración de la cuenta de almacenamiento de carga de archivos
- Eliminar la configuración de la cuenta de almacenamiento de carga de archivos
Cada llamada a la API REST de IoT Central requiere un encabezado de autorización. Para obtener más información, vea los procedimientos de autenticación y autorización de llamadas a la API REST de IoT Central.
Para ver la documentación de referencia sobre la API REST de IoT Central, consulte Referencia de la API REST de Azure IoT Central.
Sugerencia
Puede usar Postman para probar las llamadas API REST que se describen en este artículo. Descargue la colección de Postman de IoT Central e impórtela en Postman. En la colección, deberá establecer variables como el subdominio de la aplicación y el token de administrador.
Para obtener información sobre cómo cargar archivos mediante la interfaz de usuario de IoT Central, consulte Configuración de cargas de archivos.
Requisitos previos
Para probar la carga de archivos, instale los siguientes requisitos previos en el entorno de desarrollo local:
Agregar una configuración de la cuenta de almacenamiento de carga de archivos
Para agregar una configuración de la cuenta de almacenamiento de carga de archivos:
Crear una cuenta de almacenamiento
Para usar la API REST de Azure Storage, necesita un token de portador para el recurso management.azure.com. Para obtener un token de portador, puede usar la CLI de Azure:
az account get-access-token --resource https://management.azure.com
Si no tiene una cuenta de almacenamiento para los blobs, puede usar la solicitud siguiente para crear una en la suscripción:
PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}?api-version=2021-09-01
Los encabezados de solicitud tienen los campos siguientes:
subscriptionId: identificador de la suscripción de destino.resourceGroupName: nombre del grupo de recursos en la suscripción. El nombre distingue mayúsculas de minúsculas.accountName: nombre de la cuenta de almacenamiento dentro del grupo de recursos especificado. Los nombres de cuentas de almacenamiento deben tener entre 3 y 24 caracteres, y usar solo números y letras minúsculas.
El cuerpo de la solicitud tiene los campos obligatorios siguientes:
kind: tipo de cuenta de almacenamientolocation: ubicación geográfica donde reside el recursosku: nombre de SKU.
{
"kind": "BlockBlobStorage",
"location": "West US",
"sku": "Premium_LRS"
}
Creación de un contenedor
Use la solicitud siguiente para crear un contenedor llamado fileuploads en la cuenta de almacenamiento para los blobs:
PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/blobServices/default/containers/fileuploads?api-version=2021-09-01
containerName: los nombres de cuentas de almacenamiento deben tener entre 3 y 63 caracteres, y usar solo números, letras minúsculas y guiones (-). Todos los caracteres de guion (-) deben estar precedidos y seguidos inmediatamente por una letra o un número.
Envíe un cuerpo de solicitud vacío con esta solicitud, similar al ejemplo siguiente:
{
}
La respuesta a esta solicitud es similar al ejemplo siguiente:
{
"id": "/subscriptions/your-subscription-id/resourceGroups/yourResourceGroupName/providers/Microsoft.Storage/storageAccounts/yourAccountName/blobServices/default/containers/fileuploads",
"name": "fileuploads",
"type": "Microsoft.Storage/storageAccounts/blobServices/containers"
}
Obtenga las claves de cuenta de almacenamiento.
Use la solicitud siguiente para recuperar las claves de la cuenta de almacenamiento que necesita al configurar la carga en IoT Central:
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/listKeys?api-version=2021-09-01
La respuesta a esta solicitud es similar al ejemplo siguiente:
{
"keys": [
{
"creationTime": "2022-05-19T19:22:40.9132287Z",
"keyName": "key1",
"value": "j3UTm**************==",
"permissions": "FULL"
},
{
"creationTime": "2022-05-19T19:22:40.9132287Z",
"keyName": "key2",
"value": "Nbs3W**************==",
"permissions": "FULL"
}
]
}
Creación de la configuración de carga
Use la solicitud siguiente para crear una configuración de la cuenta de almacenamiento de blobs de carga de archivos en la aplicación de IoT Central:
PUT https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
El cuerpo de la solicitud tiene los campos siguientes:
account: nombre de la cuenta de almacenamiento donde se va a cargar el archivo.connectionString: cadena de conexión para conectarse a la cuenta de almacenamiento. Use uno de los valoresvaluede la solicitudlistKeysanterior como valorAccountKey.container: nombre del contenedor dentro de la cuenta de almacenamiento. En el ejemplo siguiente se usa el nombrefileuploads.etag: etiqueta de entidad para evitar conflictos con varias cargassasTtl: estándar de duración ISO 8601, la cantidad de tiempo que la solicitud del dispositivo para cargar un archivo es válida antes de que expire.
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "fileuploads",
"sasTtl": "PT1H"
}
La respuesta a esta solicitud es similar al ejemplo siguiente:
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "fileuploads",
"sasTtl": "PT1H",
"state": "pending",
"etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}
Obtener la configuración de la cuenta de almacenamiento de carga de archivos
Use la solicitud siguiente para recuperar detalles de una configuración de la cuenta de almacenamiento de blobs de carga de archivos en la aplicación de IoT Central:
GET https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
La respuesta a esta solicitud es similar al ejemplo siguiente:
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "yourContainerName",
"state": "succeeded",
"etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}
Actualización de la configuración de la cuenta de almacenamiento de carga de archivos
Use la siguiente solicitud para actualizar una cuenta de almacenamiento de blobs de carga de archivos cadena de conexión en la aplicación de IoT Central:
PATCH https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
{
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/"
}
La respuesta a esta solicitud es similar al ejemplo siguiente:
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "yourContainerName",
"sasTtl": "PT1H",
"state": "succeeded",
"etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}
Eliminación de la configuración de la cuenta de almacenamiento de carga de archivos
Use la solicitud siguiente para eliminar una configuración de cuenta de almacenamiento:
DELETE https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
Prueba de carga de archivos
Después de configurar las cargas de archivos en la aplicación de IoT Central, puede probarla con el código de ejemplo. Si todavía no ha clonado el repositorio de ejemplo de carga de archivos, use los comandos siguientes para clonarlo en una ubicación adecuada en el equipo local e instalar los paquetes dependientes:
git clone https://github.com/azure-Samples/iot-central-file-upload-device
cd iotc-file-upload-device
npm i
npm build
Creación de la plantilla de dispositivo e importación del modelo
Para probar la carga de archivos, ejecute una aplicación de dispositivo de ejemplo. Cree una plantilla de dispositivo para el dispositivo de ejemplo que se va a usar.
Abra la aplicación en la interfaz de usuario de IoT Central.
Vaya a la pestaña Plantillas de dispositivo en el panel izquierdo y seleccione + Nueva:
Elija Dispositivo IoT como tipo de plantilla.
En la página Personalizar del asistente, escriba un nombre como Ejemplo de dispositivo de carga de archivos para la plantilla de dispositivo.
En la página Revisar, seleccione Crear.
Seleccione Importar un modelo y cargue el archivo de modelos FileUploadDeviceDcm.json desde la carpeta
iotc-file-upload-device\setupdel repositorio que ha descargado antes.A continuación, seleccione Publicar para publicar la plantilla del dispositivo.
Agregar un dispositivo
Para agregar un dispositivo real a una aplicación de Azure IoT Central:
Elija Dispositivos en el panel izquierdo.
Seleccione la plantilla de dispositivo de ejemplo de carga de archivos que creó anteriormente.
Seleccione + Nuevo y después Crear.
Seleccione el dispositivo que creó y Seleccione Conectar
Copie los valores de ID scope, Device ID y Primary key. Estos valores se usan en el código de ejemplo del dispositivo.
Ejecución del código de ejemplo
Abra el repositorio git que descargó en VS Code. Cree un archivo ".env" en la raíz del proyecto y agregue los valores que copió anteriormente. El archivo debe ser similar al ejemplo siguiente con los valores que anotó anteriormente.
scopeId=<YOUR_SCOPE_ID>
deviceId=<YOUR_DEVICE_ID>
deviceKey=<YOUR_PRIMARY_KEY>
modelId=dtmi:IoTCentral:IotCentralFileUploadDevice;1
Abra el repositorio git que descargó en VS Code. Presione F5 para ejecutar y depurar el ejemplo. En la ventana del terminal, verá que el dispositivo se ha registrado y está conectado a IoT Central:
Starting IoT Central device...
> Machine: Windows_NT, 8 core, freemem=6674mb, totalmem=16157mb
Starting device registration...
DPS registration succeeded
Connecting the device...
IoT Central successfully connected device: 7z1xo26yd8
Sending telemetry: {
"TELEMETRY_SYSTEM_HEARTBEAT": 1
}
Sending telemetry: {
"TELEMETRY_SYSTEM_HEARTBEAT": 1
}
Sending telemetry: {
"TELEMETRY_SYSTEM_HEARTBEAT": 1
}
En el proyecto de ejemplo se incluye un archivo de ejemplo denominado datafile.json. Este archivo se carga cuando se usa el comando Cargar archivo en la aplicación de IoT Central.
Para probar la carga, abra la aplicación y seleccione el dispositivo que ha creado. Seleccione la pestaña Comando y verá un botón denominado Ejecutar. Al seleccionar ese botón, la aplicación de IoT Central llama a un método directo en el dispositivo para cargar el archivo. Puede ver este método directo en el código de ejemplo del archivo /device.ts. El nombre del método es uploadFileCommand.
Seleccione la pestaña Datos sin procesar para comprobar el estado de carga del archivo.
También puede realizar una llamada API REST para comprobar el estado de la carga de archivos en el contenedor de almacenamiento.
Pasos siguientes
Ahora que ha aprendido a configurar cargas de archivo con la API REST, el siguiente paso que se sugiere es crear plantillas de dispositivo desde la GUI de IoT Central.
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de