配置 ONVIF 连接器（预览版）

在 Azure IoT 操作中，使用 ONVIF 连接器（预览版）可以控制连接到 Azure IoT 操作群集的 ONVIF 兼容相机。 本文介绍如何配置和使用 ONVIF 的连接器来执行如下任务：

• 读取和写入属性以控制相机。
• 发现相机支持的媒体流。

先决条件

Azure IoT 操作的已部署实例。 如果还没有实例，请参阅快速入门：使用 K3s 在 GitHub Codespaces 中运行 Azure IoT 操作。

连接到 Azure IoT 操作群集的 ONVIF 兼容相机。

为 ONVIF 部署连接器

若要部署连接器的预览版本，可以在部署 Azure IoT作实例时启用它们，也可以在部署实例后启用它们。

若要在部署 Azure IoT 操作实例时启用预览连接器，请执行以下步骤。

若要在部署 Azure IoT Operations 实例后启用预览连接器，请执行以下操作：

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

资产终结点配置

若要配置 ONVIF 连接器，请先创建一个资产终结点，用于定义与 ONVIF 兼容的相机资产的连接。 资产终结点包括 ONVIF 发现终结点的 URL 以及访问相机所需的任何凭据。

如果相机需要身份验证，请在 Kubernetes 群集中创建一个用于存储相机用户名和密码的机密。 媒体连接器使用此机密通过相机进行身份验证：

1. 创建包含以下内容的 名为 contoso-onvif-secrets.yaml 的 YAML 文件。 将占位符替换为以 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>"
   

   小窍门

   若要在 Bash 提示符下对 base64 中的用户名和密码进行编码，请使用以下命令： echo -n "<STRING TO ENCODE>" | base64

2. 若要将机密添加到默认 Azure IoT作命名空间中的群集，请运行以下命令：

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

使用 Bicep 文件创建资产终结点：

以下代码片段显示用于创建资产终结点的 Bicep 文件：

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'
      }
    }
  }
}

前面的示例将资产终结点配置为使用用户名和密码通过相机进行身份验证。 在 Bicep 文件中，所创建资产终结点的身份验证部分如以下示例所示：

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

如果相机不需要用户名和密码，请配置匿名身份验证，如以下示例所示：

authentication: {
  method: 'Anonymous'
}

创建用于表示 ONVIF 相机功能的资产终结点和资产

创建资产终结点后，ONVIF 的连接器将运行发现过程来检测连接的相机的功能。 发现过程的结果是 DiscoveredAsset 和 DiscoverAssetEndpointProfile 自定义资源：

• DiscoveredAsset 自定义资源表示相机支持的平移缩放（PTZ）等 ONVIF 服务之一。 来自 kubectl get discoveredassets -n azure-iot-operations 的输出可能如下示例所示：

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

• DiscoveredAssetEndpointProfile 自定义资源表示相机所提供的视频流格式。 来自 kubectl get discoveredassetendpointprofiles -n azure-iot-operations 的输出可能如下示例所示：

  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
  

目前，在公共预览版中，必须手动创建资产和表示相机及其视频流的功能的 AssetEndpointProfile 自定义资源。

访问相机的 PTZ 功能

使用符合 ONVIF 的相机的 PTZ 功能来控制其位置和方向。 若要手动创建表示之前发现的相机的 PTZ 功能的资产：

以下代码片段显示用于创建资产的 bicep 文件。 资产 -ptz 名称的后缀是一个必需约定，用于指示资产表示相机的 PTZ 功能：

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
  }
}

访问相机的媒体功能

若要手动创建一个表示之前发现的相机媒体功能的资产：

以下代码片段显示用于创建资产的 bicep 文件。 资产 -media 名称的后缀是一个必需约定，用于指示资产表示相机的媒体功能：

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
  }
}

从相机接收事件

相机可以将运动检测到的事件等通知发送到 Azure IoT作群集。 ONVIF 的连接器订阅相机的事件服务，并将事件发布到 Azure IoT Operations MQTT 中转站。

若要查找相机可以发送的事件，请使用以下命令查看代表相机的 DiscoveredAsset 自定义资源的说明。 列出受支持事件的已发现资产名称具有后缀 -device。

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

上一命令的输出包括类似于以下示例的 Spec: 节：

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

在公共预览期间，必须根据发现的资产中的信息手动添加资产定义。 若要手动创建一个表示之前发现的相机媒体功能的资产：

以下代码片段显示用于创建资产的 bicep 文件。 资产 -device 名称的后缀是一个必需约定，用于指示资产表示相机的设备功能：

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'
      }
    ]
  }
}

ONVIF 的连接器现在从相机接收运动检测事件的通知，并将其发布到 data/camera-device MQTT 消息代理中的主题。

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

管理和控制相机

若要与 ONVIF 相机交互，可以发布 ONVIF 连接器订阅的 MQTT 消息。 消息格式基于 ONVIF 网络接口规范。

Azure IoT 操作连接器用于 ONVIF PTZ 演示的示例应用程序显示如何使用 ONVIF 的连接器执行以下操作：

• 使用媒体资产定义从相机的媒体服务中检索一个配置文件令牌。
• 使用相机的 PTZ 功能控制其位置和方向时，请使用配置文件令牌。

示例应用程序使用 Azure IoT Operations MQTT 中转站发送命令，以便与 ONVIF 的连接器交互。 若要了解详细信息，请参阅 使用 MQTT 代理发布和订阅 MQTT 消息。

访问相机的视频流

若要手动创建允许访问兼容 ONVIF 相机的视频流的资产终结点和资产：

1. 在公共预览期间，首先使用工具查找相机的 RTSP 流地址。

2. 使用 RTSP 流 URL 创建资产终结点和资产。 若要了解详细信息，请参阅“配置媒体连接器”（预览版）。