Configuración del conector para HTTP/REST

En Azure IoT Operations, el conector para HTTP/REST permite el acceso a los datos de los puntos de conexión REST expuestos por los servicios HTTP.

Un recurso en Azure IoT Operations es una entidad lógica que se crea para representar un recurso físico o dispositivo. Un recurso de Azure IoT Operations puede tener propiedades personalizadas, puntos de datos, flujos y eventos que describen su comportamiento y características. Un recurso está asociado a uno o varios dispositivos. Azure IoT Operations almacena definiciones de recursos en Azure Device Registry.

Un dispositivo de Azure IoT Operations es una entidad lógica que define las conexiones a recursos físicos o dispositivos. Sin un dispositivo, los datos no pueden fluir desde un dispositivo o activo físico al agente MQTT. Al configurar un dispositivo y un recurso, se establece una conexión al recurso físico o al dispositivo y a los valores de punto de datos, eventos y flujos que llegan a la instancia de Azure IoT Operations. Un dispositivo tiene uno o varios puntos de conexión de entrada. Azure IoT Operations almacena definiciones de dispositivo en Azure Device Registry.

El conector para HTTP/REST admite las siguientes características:

• Reintentos automáticos cuando se producen errores de muestreo. Informa de un estado de fallo para errores que no se pueden reintentar.
• Integración con OpenTelemetry.
• Uso de puntos de conexión y recursos de dispositivo.
• Opcionalmente, puede transformar los datos entrantes mediante módulos WASM.
• Validación del punto de conexión del dispositivo y la definición de recursos para la compatibilidad con REST.
• Varios métodos de autenticación:
  • Autenticación HTTP básica de nombre de usuario y contraseña
  • Certificados de cliente x509
  • Acceso anónimo con fines de prueba
• Para establecer una conexión TLS al punto de conexión HTTP, puede configurar una lista de confianza de certificados para el conector.

Para cada conjunto de datos configurado, el conector para HTTP/REST:

• Realiza una solicitud GET a la dirección especificada en el punto de conexión del dispositivo y anexa el origen de datos del conjunto de datos del recurso.
• Genera un esquema de mensaje para cada conjunto de datos en función de los datos que recibe y los registra con el Registro de esquemas y el Registro de dispositivos de Azure.
• Reenvía los datos al destino especificado.

En este artículo se explica cómo usar el conector para HTTP/REST para realizar tareas como:

• Defina los dispositivos que conectan orígenes HTTP a la instancia de Operaciones de IoT de Azure.
• Agregue recursos y defina los puntos de datos para habilitar el flujo de datos desde el origen HTTP al corredor MQTT o el almacén de estado de corredor.

Prerrequisitos

Para configurar dispositivos y recursos, necesita una instancia en ejecución de Operaciones de IoT de Azure.

Para iniciar sesión en la experiencia de operaciones, necesita una cuenta de Id. de Microsoft Entra con al menos permisos de colaborador para el grupo de recursos que contiene la instancia de Kubernetes - Azure Arc. No puede iniciar sesión con una cuenta Microsoft (MSA). Para obtener más información, consulte Solución de problemas de acceso a la interfaz de usuario web de la experiencia de operaciones.

El administrador de TI debe configurar el conector para la plantilla HTTP/REST para la instancia de Azure IoT Operations en Azure Portal.

Necesita las credenciales necesarias para acceder al origen HTTP. Si el origen HTTP requiere autenticación, debe crear un secreto de Kubernetes que contenga el nombre de usuario y la contraseña del origen HTTP.

Implementación del conector para HTTP/REST

Al implementar Azure IoT Operations, la implementación incluye varios conectores. Para poder usar los conectores (como ONVIF, medios y HTTP/REST) en la interfaz de usuario web de la experiencia de operaciones, un administrador debe agregar instancias de plantilla de conector a la instancia de Azure IoT Operations.

Todos los conectores pueden publicar los datos capturados en el broker MQTT.

Para agregar una instancia de plantilla de conector a la instancia de Operaciones de IoT de Azure:

1. En Azure Portal, vaya a la instancia de Operaciones de IoT de Azure, seleccione Plantillas de conector y luego seleccione Agregar instancias de plantilla de conector:

   

2. En la primera página del Asistente para agregar una plantilla de conector de Akri , seleccione el tipo y la versión de la plantilla de conector que desea agregar, como ONVIF, Media, HTTP/REST, SSE o MQTT. A continuación, seleccione Metadatos.

   

3. En la página Metadatos, acepte los valores predeterminados y luego seleccione Tipo de punto de conexión de entrada del dispositivo.

4. En la página Tipo de punto de conexión entrante del dispositivo, acepte los valores predeterminados y luego seleccione Configuraciones de diagnóstico.

5. En la página Configuraciones de diagnóstico, acepte los valores predeterminados y luego seleccione Configuración en runtime.

6. En la página Configuración en tiempo de ejecución, acepte los valores predeterminados y seleccione Revisar.

7. En la página Revisar, revise los detalles de la instancia de plantilla del conector y luego seleccione Crear para crear la instancia de plantilla del conector.

Un usuario de OT ya puede utilizar la interfaz de usuario web de experiencia operativa para crear un dispositivo con un punto de conexión de conector.

---

Crear un dispositivo

Para configurar el conector para HTTP/REST, cree primero un dispositivo que defina la conexión al origen HTTP. El dispositivo incluye la dirección URL del origen HTTP y las credenciales que necesita para acceder al origen HTTP:

Experiencia de operaciones

1. En la interfaz de usuario web de experiencia operativa, seleccione Dispositivos en el panel de navegación izquierdo. A continuación, seleccione Crear nuevo.

2. Escriba un nombre para su dispositivo, como http-connector. Para agregar el punto de conexión para el conector para HTTP/REST, seleccione Nuevo en el icono Microsoft.Http .

3. Agregue los detalles del punto de conexión para el conector para HTTP/REST, incluidas las credenciales de autenticación:

   

   Seleccione Aplicar para guardar el punto de conexión.

4. En la página Detalles del dispositivo, seleccione Siguiente para continuar.

5. En la página Agregar propiedades personalizadas , agregue cualquier otra propiedad que quiera asociar al dispositivo. Por ejemplo, puede agregar una propiedad para indicar el fabricante de la cámara. Después, seleccione Siguiente para continuar.

6. En la página Resumen, revise los detalles del dispositivo y seleccione Crear para crear el recurso.

7. Una vez creado el dispositivo, puede verlo en la lista Dispositivos :

   

Azure CLI

Ejecute los comandos siguientes:

az iot ops ns device create -n rest-http-connector-cli -g {your resource group name} --instance {your instance name} 

az iot ops ns device endpoint inbound add rest --device rest-http-connector-cli -g {your resource group name} -i {your instance name}  --name rest-http-connector-0 --endpoint-address "https://rest-http-connector-0"

Para obtener más información, consulte az iot ops ns device.

Bíceps

Implemente la siguiente plantilla de Bicep para crear un dispositivo con un punto de conexión de entrada para el conector HTTP/REST. Reemplace los marcadores de posición <AIO_NAMESPACE_NAME> y <CUSTOM_LOCATION_NAME> con el nombre de su espacio de nombres de Azure IoT Operations y el nombre de su ubicación personalizada, respectivamente.

param aioNamespaceName string = '<AIO_NAMESPACE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'

resource namespace 'Microsoft.DeviceRegistry/namespaces@2025-10-01' existing = {
  name: aioNamespaceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource device 'Microsoft.DeviceRegistry/namespaces/devices@2025-10-01' = {
  name: 'http-connector'
  parent: namespace
  location: resourceGroup().location
  extendedLocation: {
    type: 'CustomLocation'
    name: customLocation.id
  }
  properties: {
    endpoints: {
      outbound: {
        assigned: {}
      }
      inbound: {
        'http-connector-0': {
          endpointType: 'Microsoft.Http'
          address: 'https://rest-http-connector-0'
        }
      }
    }
  }
}

Esta configuración implementa un nuevo recurso device llamado http-connector al clúster con un punto de conexión de entrada denominado http-connector-0.

Configuración de un dispositivo para usar un nombre de usuario y una contraseña

En el ejemplo anterior se usa el modo de autenticación Anonymous. Este modo no requiere un nombre de usuario ni una contraseña.

Para usar el modo de autenticación Username password, complete los pasos siguientes:

Experiencia de operaciones

Siga los pasos descritos en Administración de secretos para la implementación de Azure IoT Operations para agregar secretos para el nombre de usuario y la contraseña en Azure Key Vault, proyectarlos en el clúster de Kubernetes y hacer referencia a ellos desde la configuración del dispositivo.

Azure CLI

1. Siga los pasos descritos en Administración de secretos para la implementación de Azure IoT Operations para agregar secretos para el nombre de usuario y la contraseña en Azure Key Vault y proyectarlos en el clúster de Kubernetes.

2. Utilice el comando az iot ops ns device endpoint inbound add con los parámetros --user-ref y --pass-ref para agregar las referencias a los secretos de Azure Key Vault que creó.

Bíceps

1. Siga los pasos descritos en Administración de secretos para la implementación de Azure IoT Operations para agregar secretos para el nombre de usuario y la contraseña en Azure Key Vault y proyectarlos en el clúster de Kubernetes.

2. Modifique el authentication bloque de la configuración de Bicep para que el conector haga referencia a los secretos sincronizados para el nombre de usuario y la contraseña, como se muestra en el ejemplo siguiente:

   authentication: {
       method: 'UsernamePassword'
           usernamePasswordCredentials: {
               passwordSecretName: '<reference to synced password secret>'
               usernameSecretName: '<reference to synced username secret>'
           }
   }
   

Configuración de un dispositivo para usar un certificado X.509

Para usar el X509 certificate modo de autenticación, siga los pasos descritos en Administración de certificados para comunicaciones externas para agregar secretos para certificados en Azure Key Vault, proyectarlos en el clúster de Kubernetes y hacer referencia a ellos desde la configuración del dispositivo.

Configuración de una lista de confianza de certificados para un dispositivo que se va a usar

Para administrar la lista de certificados de confianza para el conector para HTTP/REST, consulte Administración de certificados para comunicaciones externas.

Creación de un recurso

Para definir un recurso que publica puntos de datos desde el punto de conexión HTTP, siga estos pasos:

Experiencia de operaciones

1. En la interfaz de usuario web de la experiencia de operaciones, seleccione Recursos en el panel de navegación izquierdo. A continuación, seleccione Crear recurso.

2. Seleccione el punto de conexión de entrada para el conector para HTTP/REST que creó en la sección anterior.

3. Escriba un nombre para el recurso, como my-http-source.

4. Agregue las propiedades personalizadas que quiera asociar al recurso. Por ejemplo, puede agregar una propiedad para indicar el fabricante de la cámara. Seleccione Next (Siguiente) para continuar.

Un conjunto de datos define dónde envía el conector los datos que recopila de una colección de puntos de datos. Un recurso HTTP/REST puede tener varios conjuntos de datos. Para crear un conjunto de datos:

1. Seleccione Crear conjunto de datos.

2. Escriba los detalles del conjunto de datos, como su nombre, el origen de datos, el intervalo de muestreo y el destino. En el caso de los recursos HTTP/REST, el origen de datos es la ruta de acceso en el punto de conexión REST. Para los recursos HTTP/REST, el destino es un tema MQTT o una clave del almacén de estado del bróker. Por ejemplo:

   

   Para transformar los datos entrantes, agregue la dirección URL de un módulo WebAssembly (WASM) en el campo Transformar . Para más información, consulte Transformación de datos entrantes.

3. Seleccione Crear y siguiente para crear el conjunto de datos.

   Sugerencia

   Use la opción Administrar valores predeterminados para configurar los valores predeterminados del conjunto de datos, como el intervalo de muestreo.

4. En la página Revisar, revise los detalles del recurso y seleccione Crear para crear el recurso. Después de unos minutos, el recurso aparece en la página Recursos:

   

Azure CLI

Ejecute los comandos siguientes:

az iot ops ns asset rest create --name myrestasset --instance {your instance name} -g {your resource group name} --device rest-http-connector-cli --endpoint rest-http-connector-0

az iot ops ns asset rest dataset add --asset myrestasset --instance {your instance name} -g {your resource group name} --name weatherdata --data-source "/api/weather" --dest topic="azure-iot-operations/data/erp" retain=Never qos=Qos1 ttl=3600 --sampling-int 30000

Para obtener más información, consulte az iot ops ns asset rest.

Bíceps

Implemente la siguiente plantilla de Bicep para crear un recurso que publique mensajes desde el dispositivo mostrado anteriormente en un tema MQTT. El origen de datos del conjunto de datos define la ruta de acceso en el punto de conexión REST que se va a consultar. Reemplace los marcadores de posición <AIO_NAMESPACE_NAME> y <CUSTOM_LOCATION_NAME> con el nombre de su espacio de nombres de Azure IoT Operations y el nombre de su ubicación personalizada, respectivamente.

param aioNamespaceName string = '<AIO_NAMESPACE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'

resource namespace 'Microsoft.DeviceRegistry/namespaces@2025-10-01' existing = {
  name: aioNamespaceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource asset 'Microsoft.DeviceRegistry/namespaces/assets@2025-10-01' = {
  name: 'myrestasset'
  parent: namespace
  location: resourceGroup().location
  extendedLocation: {
    type: 'CustomLocation'
    name: customLocation.id
  }
  properties: {
    displayName: 'myrestasset'
    description: 'An example HTTP asset'
    enabled: true

    deviceRef: {
      deviceName: 'http-connector'
      endpointName: 'http-connector-0'
    }

    defaultDatasetsConfiguration: '{}'
    defaultEventsConfiguration: '{}'

    datasets: [
      {
        name: 'weatherdata'
        dataSource: '/api/weather'
        datasetConfiguration: '{"samplingIntervalInMilliseconds":20000}'
        destinations: [
          {
            target: 'Mqtt'
            configuration: {
              topic: 'azure-iot-operations/data/erp'
              qos: 'Qos1'
              retain: 'Never'
              ttl: 3600
            }
          }
        ]
      }
    ]
  }
}

Transformación de datos entrantes

Para transformar los datos entrantes mediante un módulo WASM, complete los pasos siguientes:

1. Desarrolle un módulo WASM para realizar la transformación personalizada. Para obtener más información, consulte Desarrollo de módulos y definiciones de grafos de WebAssembly (WASM).

2. Configure el gráfico de transformación. Para obtener más información, vea Configurar definiciones de grafos de WebAssembly (WASM).

3. Implemente tanto el módulo como el grafo. Para obtener más información, vea Usar WebAssembly (WASM).

   Nota:

   Debe implementar al menos un grafo de flujo de datos para habilitar el procesamiento de grafos WASM, pero esta característica no usa el grafo de otro modo.

4. Configure el conjunto de datos con la dirección URL del grafo WASM desplegado en el campo Transform:

   

Una transformación de datos en el conector HTTP/REST solo requiere un único operador de mapa, pero los gráficos WASM son totalmente compatibles con las restricciones siguientes:

• El gráfico debe tener un solo source nodo y un solo sink nodo.
• El gráfico debe consumir y emitir el tipo de DataModel::Message datos.
• El gráfico debe estar sin estado. Actualmente, esta restricción implica que no se admiten operadores acumulativos.