Configuración del conector para ONVIF (versión preliminar)

En las operaciones de IoT de Azure, el conector para ONVIF ( versión preliminar) le permite controlar una cámara compatible con ONVIF que esté conectada a su clúster de operaciones de IoT de Azure. En este artículo se explica cómo configurar y usar el conector para ONVIF para realizar tareas como:

• Leer y escribir propiedades para controlar una cámara.
• Detectar las secuencias multimedia que admite una cámara.

Requisitos previos

Una instancia implementada de Operaciones de IoT de Azure. Si aún no tiene una instancia, consulte Inicio rápido: Ejecutar operaciones de Azure IoT en GitHub Codespaces con K3s.

Una cámara compatible con ONVIF conectada al clúster de Operaciones de IoT de Azure.

Implementación del conector para ONVIF

Para implementar la versión preliminar de los conectores, puede habilitarlos al implementar la instancia de Azure IoT Operations o habilitarlos después de implementar la instancia.

Para habilitar los conectores en versión preliminar al implementar la instancia de Azure IoT Operations:

Para habilitar los conectores en versión preliminar después de implementar la instancia de Azure IoT Operations:

az iot ops update -n <your-instance> -g <your-resource-group> --feature connectors.settings.preview=Enabled

Configuración del punto de conexión de recurso

Para configurar el conector ONVIF, primero cree un punto de conexión de recurso que defina la conexión al recurso de cámara compatible con ONVIF. El punto final de activos incluye la URL del punto final de descubrimiento ONVIF y cualquier credencial que necesite para acceder a la cámara.

Si la cámara requiere autenticación, cree un secreto en el clúster de Kubernetes que almacene el nombre de usuario y la contraseña de la cámara. El conector multimedia usa este secreto para autenticarse con la cámara:

1. Cree un archivo YAML denominado contoso-onvif-secrets.yaml con el siguiente contenido. Reemplace los marcadores de posición por el nombre de usuario y la contraseña de la cámara codificados en base64:

   apiVersion: v1
   kind: Secret
   metadata:
     name: contoso-onvif-secrets
   type: Opaque
   data:
     username: "<YOUR CAMERA USERNAME BASE64 ENCODED>"
     password: "<YOUR CAMERA PASSWORD BASE64 ENCODED>"
   

   Sugerencia

   Para codificar el nombre de usuario y la contraseña en base64 en una ventana de comandos de Bash, use el siguiente comando: echo -n "<STRING TO ENCODE>" | base64.

2. Para agregar el secreto al clúster en el espacio de nombres predeterminado de Azure IoT Operations, ejecute el siguiente comando:

   kubectl apply -f contoso-onvif-secrets.yaml -n azure-iot-operations
   

Para crear el punto de conexión del recurso mediante un archivo de Bicep:

En el fragmento de código siguiente se muestra el archivo de Bicep que usó para crear el punto de conexión del recurso:

metadata description = 'Asset endpoint profile for ONVIF connector'

@description('The ONVIF discovery endpoint.')
param onvifAddress string

@description('The name of the custom ___location you are using.')
param customLocationName string

@description('Specifies the name of the asset endpoint resource to create.')
param aepName string

@description('The name of the Kubernetes secret you are using to store the camera credentials.')
param secretName string

/*****************************************************************************/
/*                          Asset endpoint profile                           */
/*****************************************************************************/
resource assetEndpoint 'Microsoft.DeviceRegistry/assetEndpointProfiles@2024-11-01' = {
  name: aepName
  ___location: resourceGroup().___location
  extendedLocation: {
    type: 'CustomLocation'
    name: customLocationName
  }
  properties: {
    targetAddress: onvifAddress
    endpointProfileType: 'Microsoft.Onvif'
    #disable-next-line no-hardcoded-env-urls //Schema required during public preview
    additionalConfiguration: '{"@schema":"https://aiobrokers.blob.core.windows.net/aio-onvif-connector/1.0.0.json"}'
    authentication: {
      method: 'UsernamePassword'
      usernamePasswordCredentials: {
        passwordSecretName: '${secretName}/password'
        usernameSecretName: '${secretName}/username'
      }
    }
  }
}

En el ejemplo anterior se configura el punto de conexión del recurso para autenticarse con la cámara con un nombre de usuario y una contraseña. En el archivo de Bicep, la sección de autenticación del punto de conexión de recurso que creó es similar al ejemplo siguiente:

authentication: {
  method: 'UsernamePassword'
  usernamePasswordCredentials: {
    passwordSecretName: '${secretName}/password'
    usernameSecretName: '${secretName}/username'
    }

Si la cámara no requiere un nombre de usuario y una contraseña, configure la autenticación anónima como se muestra en el ejemplo siguiente:

authentication: {
  method: 'Anonymous'
}

Creación de los puntos de conexión y recursos de recursos para representar las funcionalidades de la cámara ONVIF

Después de crear el punto de conexión del recurso, el conector para ONVIF ejecuta un proceso de detección para detectar las funcionalidades de la cámara conectada. Los resultados del proceso de detección son DiscoverAsset y DiscoverAssetEndpointProfile recursos personalizados:

• Un recurso personalizado DiscoveredAsset representa uno de los servicios ONVIF , como el zoom panorámico (PTZ) que admite la cámara. La salida de kubectl get discoveredassets -n azure-iot-operations podría tener un aspecto similar al del ejemplo siguiente:

  NAME                       AGE
  contoso-onvif-aep-device    3m
  contoso-onvif-aep-media     3m
  contoso-onvif-aep-ptz       3m
  

• Un recurso personalizado DiscoveredAssetEndpointProfile representa un formato de secuencia de vídeo que expone la cámara. La salida de kubectl get discoveredassetendpointprofiles -n azure-iot-operations podría tener un aspecto similar al del ejemplo siguiente:

  NAME                                AGE
  contoso-onvif-aep-mainstream-http    3m
  contoso-onvif-aep-mainstream-rtsp    3m
  contoso-onvif-aep-mainstream-tcp     3m
  contoso-onvif-aep-mainstream-udp     3m
  contoso-onvif-aep-minorstream-http   3m
  contoso-onvif-aep-minorstream-rtsp   3m
  contoso-onvif-aep-minorstream-tcp    3m
  contoso-onvif-aep-minorstream-udp    3m
  

Actualmente, durante la versión preliminar pública, debe crear manualmente los recursos personalizados Asset y AssetEndpointProfile que representan las funciones de la cámara y sus secuencias de vídeo.

Acceso a las funcionalidades de PTZ de la cámara

Utilice las funcionalidades PTZ de una cámara compatible con ONVIF para controlar su posición y orientación. Para crear manualmente un recurso que represente las funcionalidades PTZ de la cámara detectadas anteriormente:

En el fragmento de código siguiente se muestra el archivo bicep que usó para crear el recurso. El -ptz sufijo al nombre del recurso es una convención necesaria para indicar que el recurso representa las funcionalidades PTZ de la cámara:

metadata description = 'ONVIF camera PTZ capabilities'
param aepName  string
param customLocationName string
param assetName     string = 'camera-ptz'
param displayName string = 'Camera PTZ service'

/*****************************************************************************/
/*                                    Asset                                  */
/*****************************************************************************/
resource asset 'Microsoft.DeviceRegistry/assets@2024-11-01' = {
  name: assetName
  ___location: resourceGroup().___location
  extendedLocation: {
    type: 'CustomLocation'
    name: customLocationName
  }
  properties: {
    displayName: displayName
    assetEndpointProfileRef: aepName
  }
}

Acceso a las funcionalidades multimedia de la cámara

Para crear manualmente un recurso que represente las funciones multimedia de la cámara detectadas anteriormente:

En el fragmento de código siguiente se muestra el archivo bicep que usó para crear el recurso. El -media sufijo al nombre del recurso es una convención necesaria para indicar que el recurso representa las capacidades multimedia de la cámara:

metadata description = 'ONVIF camera media capabilities'
param aepName  string
param customLocationName string
param assetName     string = 'camera-media'
param displayName string = 'Camera media service'

/*****************************************************************************/
/*                                    Asset                                  */
/*****************************************************************************/
resource asset 'Microsoft.DeviceRegistry/assets@2024-11-01' = {
  name: assetName
  ___location: resourceGroup().___location
  extendedLocation: {
    type: 'CustomLocation'
    name: customLocationName
  }
  properties: {
    displayName: displayName
    assetEndpointProfileRef: aepName
  }
}

Recibir eventos de la cámara

La cámara puede enviar notificaciones como eventos detectados de movimiento al clúster de operaciones de Azure IoT. El conector para ONVIF se suscribe al servicio de eventos de la cámara y publica los eventos en el agente MQTT de Azure IoT Operations.

Para buscar los eventos que puede enviar la cámara, use el siguiente comando para ver la descripción del recurso personalizado DiscoveredAsset que representa la cámara. El recurso detectado que muestra los eventos admitidos tiene un -device sufijo para el nombre del recurso:

kubectl describe discoveredasset your-discovered-asset-device -n azure-iot-operations

La salida del comando anterior incluye una Spec: sección similar al ejemplo siguiente:

Spec:
  Asset Endpoint Profile Ref:  your-asset-endpoint-profile-aep
  Datasets:
  Default Datasets Configuration:
  Default Events Configuration:
  Default Topic:
    Path:
    Retain:           Never
  Discovery Id:       a00b978b9d971450fa6378900b164736170bd2d790a2061da94a2238adee0d4f
  Documentation Uri:
  Events:
    Event Configuration:
    Event Notifier:       tns1:RuleEngine/CellMotionDetector/Motion
    Last Updated On:      2025-04-23T15:48:21.585502872+00:00
    Name:                 tns1:RuleEngine/CellMotionDetector/Motion
    Topic:
      Path:
      Retain:             Never
    Event Configuration:
    Event Notifier:       tns1:RuleEngine/TamperDetector/Tamper
    Last Updated On:      2025-04-23T15:48:21.585506712+00:00
    Name:                 tns1:RuleEngine/TamperDetector/Tamper
    Topic:
      Path:
      Retain:             Never

Durante la versión preliminar pública, debe agregar manualmente una definición de recurso en función de la información del recurso detectado. Para crear manualmente un recurso que represente las funciones multimedia de la cámara detectadas anteriormente:

En el fragmento de código siguiente se muestra el archivo bicep que usó para crear el recurso. El -device sufijo al nombre del recurso es una convención necesaria para indicar que el recurso representa las funcionalidades del dispositivo de la cámara:

metadata description = 'ONVIF camera device events'
param aepName  string
param customLocationName string
param assetName     string = 'camera-device'
param displayName string = 'Camera device motion detected'

/*****************************************************************************/
/*                                    Asset                                  */
/*****************************************************************************/
resource asset 'Microsoft.DeviceRegistry/assets@2024-11-01' = {
  name: assetName
  ___location: resourceGroup().___location
  extendedLocation: {
    type: 'CustomLocation'
    name: customLocationName
  }
  properties: {
    displayName: displayName
    assetEndpointProfileRef: aepName
    enabled: true
    events: [
      {
        eventNotifier: 'tns1:RuleEngine/CellMotionDetector/Motion'
        name: 'motionDetected'
      }
    ]
  }
}

El conector para ONVIF ahora recibe notificaciones de eventos de detección de movimiento de la cámara y las publica en el tema data/camera-device en el corredor MQTT:

{
  "name": "motionDetected",
  "eventNotifier": "tns1:RuleEngine/CellMotionDetector/Motion",
  "source": {
    "VideoSourceConfigurationToken": "vsconf",
    "VideoAnalyticsConfigurationToken": "VideoAnalyticsToken",
    "Rule": "MyMotionDetectorRule"
  },
  "data": {
    "IsMotion": "true"
  }
}

Administración y control de la cámara

Para interactuar con la cámara ONVIF, puede publicar mensajes MQTT a los que se suscribe el conector para ONVIF. El formato de mensaje se basa en las especificaciones de interfaz de red ONVIF.

La aplicación de ejemplo conector de Operaciones de Azure IoT para demostración de ONVIF PTZ muestra cómo usar el conector para ONVIF para:

• Utiliza la definición de recurso para recuperar un token de perfil del servicio multimedia de la cámara.
• Use el token de perfil cuando use las funcionalidades PTZ de la cámara para controlar su posición y orientación.

La aplicación de ejemplo usa el agente MQTT de Azure IoT Operations para enviar comandos para interactuar con el conector para ONVIF. Para más información, consulte Publicación y suscripción de mensajes MQTT mediante el agente MQTT.

Acceso a las secuencias de vídeo de la cámara

Para crear manualmente un punto de conexión de recurso y un recurso que permitan el acceso a las secuencias de vídeo de la cámara compatible con ONVIF:

1. Durante la versión preliminar pública, use primero una herramienta para detectar las direcciones URL de la secuencia RTSP de la cámara.

2. Use la dirección URL del flujo RTSP para crear el punto de conexión del recurso y el recurso. Para más información, consulte Configuración del conector multimedia (versión preliminar).