Прямые методы службы "Видеоанализатор Azure"

edge icon
Кроме того, ознакомьтесь с разделами о создании видеоприложений в службе.


Примечание

Прекращается использование предварительной версии Видеоанализатора Azure. Рекомендуем вам перевести свои приложения с этой службы до 1 декабря 2022 г.

Прекращение использования не затронет Видеоанализатор Azure для медиа. Это решение переименовано в Индексатор видео Azure. См. дополнительные сведения.

Требуемое действие: чтобы выполнение ваших рабочих нагрузок не нарушалось, отключите свое приложение от Видеоанализатора согласно рекомендациям этого руководства не позднее 1 декабря 2022 г. После 1 декабря 2022 г. ваша учетная запись Видеоанализатора Azure перестанет работать. Начиная со 2 мая 2022 г. вы не сможете создавать новые учетные записи Видеоанализатора.

Модуль Edge "Видеоанализатор Azure" avaedge предоставляет несколько прямых методов, которые можно вызывать из Центра Интернета вещей. Прямые методы представляют собой взаимодействие типа "запрос — ответ" с устройством, подобное вызову HTTP тем, что об успешном завершении или сбое становится известно немедленно (после указанного пользователем времени ожидания). Этот подход полезен для сценариев, в которых предпринимаемые немедленно действия различаются в зависимости от того, удалось ли устройству ответить. Дополнительные сведения см. в статье Общие сведения о прямых методах и информация о вызове этих методов из Центра Интернета вещей.

В этой статье описаны такие методы, их схема и соглашения.

Соглашения

Прямые методы основываются на следующих соглашениях.

  1. У прямых методов номер версии указан в формате ОСНОВНОЙ.ДОПОЛНИТЕЛЬНЫЙ (как показано в следующем примере): В номере "@apiVersion" "1" — это ОСНОВНОЙ номер, а "0" — ДОПОЛНИТЕЛЬНЫЙ, как показано в этом примере:

    {
      "methodName": "pipelineTopologySet",
      "payload": {
          "@apiVersion": "1.1",
          "name": "{TopologyName}",
          "properties": {
              // Desired Topology properties
          }
      }
    }
    
  2. Данная версия модуля "Видеоанализатор" поддерживает все дополнительные версии вызова прямого метода вплоть до его текущей версии. Поддержка разных основных версий не гарантируется.

  3. Все прямые методы являются синхронными.

  4. Результаты ошибок основаны на схеме ошибок OData.

  5. Имена должны соответствовать следующим ограничениям:

    • Только буквенно-цифровые символы и тире, если имя не начинается и заканчивается тире
    • Нельзя использовать пробелы
    • Длина не должна превышать 32 символов

Пример ответа от прямого метода

-----------------------  Request: livePipelineList  --------------------------------------------------

{
  "@apiVersion": "1.1"
}

---------------  Response: livePipelineList - Status: 200  ---------------

{
  "value": []
}

--------------------------------------------------------------------------

Коды ошибок

Как показано в примере ниже, при получении сообщения об ошибке от прямого метода появляется код ошибки верхнего уровня, а дополнительные сведения предоставляются в разделе details.

{
  "status": 400,
  "payload": {
    "error": {
      "code": "BadRequest",
      "message": "The request is invalid",
      "details": [
        {
          "code": "ApiVersionNotSupported",
          "message": "The API version '1.4' is not supported. Supported version(s): 1.0, 1.1"
        }
      ]
    }
  }
}

Ниже приведены коды ошибок, используемые на верхнем уровне.

Состояние Код Сообщение
400 BadRequest Недопустимый запрос.
400 InvalidResource Недопустимый ресурс
400 InvalidVersion Недопустимая версия API
402 ConnectivityRequired Для правильной работы модуля Edge требуется подключение к облаку.
404 NotFound Ресурс не найден
409 Conflict Конфликт операций
500 InternalServerError Внутренняя ошибка сервера
503 ServerBusy Сервер занят

Ниже приведены коды ошибок, используемые на уровне детализации.

Состояние Подробный код Описание
400 PipelineValidationError Общие ошибки конвейера, такие как циклы или секционирование и т. д.
400 ModuleValidationError Ошибки проверки, специфичные для модуля.
409 PipelineTopologyInUse На топологию конвейера по-прежнему ссылается один или несколько динамических конвейеров.
409 OperationNotAllowedInState Невозможно выполнить требуемую операцию в текущем состоянии.
409 ResourceValidationError Ресурс, на который указывает ссылка (например, ресурс видео), находится в недопустимом состоянии.

Поддерживаемые прямые методы

Ниже приведены прямые методы, предоставляемые модулем IoT Edge "Видеоанализатор". Схема прямых методов доступна здесь.

pipelineTopologyList

Этот прямой метод перечисляет все созданные топологии конвейера.

Запрос

{
  "@apiVersion": "1.1"
}

Ответ

{
  "status": 200,
  "value": [
    {
      "systemData": {
        "createdAt": "2021-05-05T14:19:22.16Z",
        "lastModifiedAt": "2021-05-05T16:20:41.505Z"
      },
      
      // first pipeline topology payload
      
    },
      "systemData": {
        "createdAt": "2021-05-06T14:19:22.16Z",
        "lastModifiedAt": "2021-05-06T16:20:41.505Z"
      },
      
      // next pipeline topology payload
      
    }    
  ]
}

Коды состояния

Условие Код состояния
Найдена сущность 200
Общие ошибки пользователя Ошибки диапазона 400
Сущность не найдена 404
Общие ошибки сервера Ошибки диапазона 500

pipelineTopologySet

Создает топологию конвейера с заданным именем, если такая топология не существует, или обновляет существующую топологию с этим именем.

Ключевые аспекты:

  • Топологию конвейера можно свободно обновлять, если на нее не ссылаются динамические конвейеры.

  • Топологию можно свободно обновлять, если все ссылающиеся динамические конвейеры деактивированы, при условии, что:

    • Новые параметры содержат значения по умолчанию
    • На удаленные параметры не ссылаются никакие конвейеры.
  • Пока активен динамический конвейер, разрешены только некоторые обновления топологии конвейера.

Запрос

  {
    "methodName": "pipelineTopologySet",
    "payload": {
        "@apiVersion": "1.1",
        "name": "{TopologyName}",
        "properties": {
            // Desired pipeline topology properties
        }
    }
  }

Ответ

  {
    "status": 201,
    "payload": {
        "systemData": {
           "createdAt": "2021-05-11T18:16:46.491Z",
           "lastModifiedAt": "2021-05-11T18:16:46.491Z"
        },
        "name": "{TopologyName}",
        "properties": {
            // Complete pipeline topology
        }
    }
  }

Коды состояния

Условие Код состояния Подробный код ошибки
Существующая сущность обновлена 200 Недоступно
Новая сущность создана 201 Недоступно
Общие ошибки пользователя Ошибки диапазона 400
Ошибки проверки конвейера 400 PipelineValidationError
Ошибки проверки модуля 400 ModuleValidationError
Общие ошибки сервера Ошибки диапазона 500

pipelineTopologyGet

Получает топологию конвейера с указанным именем, если он существует.

Запрос

  {
        "@apiVersion": "1.1",
        "name": "{TopologyName}"       
  }

Ответ

{
  "status": 200,
  "payload": {
    "value": [
      {
        "systemData": {
          "createdAt": "2021-05-06T10:28:04.560Z",
          "lastModifiedAt": "2021-05-06T10:28:04.560Z"
        },
        "name": "{TopologyName}",
        // Complete pipeline topology
      }
    ]
  }
}

Коды состояния

Условие Код состояния
Успешно 200
Общие ошибки пользователя Ошибки диапазона 400
Общие ошибки сервера Ошибки диапазона 500

pipelineTopologyDelete

Удаляет топологию конвейера.

Запрос

  {
    "methodName": "pipelineTopologyDelete",
    "payload": {
        "@apiVersion": "1.1",
        "name": "{TopologyName}"
    }
  }

Ответ

{
    "status": 200,
    "payload": null
}

Коды состояния

Условие Код состояния Подробный код ошибки
Сущность удалена 200 Недоступно
Сущность не найдена 204 Недоступно
Общие ошибки пользователя Ошибки диапазона 400
На топологию конвейера ссылается один или несколько конвейеров. 409 PipelineTopologyInUse
Общие ошибки сервера Ошибки диапазона 500

livePipelineList

Выводит список всех динамических конвейеров.

Запрос

  {
        "@apiVersion": "1.1"
  }

Ответ

{
  "status": 200,
  "value": [
    {
      "systemData": {
        "createdAt": "2021-05-05T14:19:22.16Z",
        "lastModifiedAt": "2021-05-05T16:20:41.505Z"
      },      
      // first live pipeline payload  
    },
      "systemData": {
        "createdAt": "2021-05-06T14:19:22.16Z",
        "lastModifiedAt": "2021-05-06T16:20:41.505Z"
      },
      // next live pipeline payload
    }    
  ]
}

Коды состояния

Условие Код состояния
Найдена сущность 200
Общие ошибки пользователя Ошибки диапазона 400
Сущность не найдена 404
Общие ошибки сервера Ошибки диапазона 500

livePipelineSet

Создает динамический конвейер с заданным именем, если такой конвейер не существует, или обновляет существующий динамический конвейер с таким именем.

Ключевые аспекты:

  • Динамический конвейер можно свободно обновлять в деактивированном состоянии. В других состояниях разрешены только некоторые обновления.
  • Динамический конвейер повторно проверяется при каждом обновлении.

Запрос

  {
        "@apiVersion": "1.1",
        "name": "{livePipelineName}",
        "properties": {
            // Desired live pipeline properties
        }
  }

Ответ

  {
    "status": 201,
    "payload": {
        "systemData": {
           "createdAt": "2021-05-11T18:16:46.491Z",
           "lastModifiedAt": "2021-05-11T18:16:46.491Z"
        },
        "name": "{livePipelineName}",
        "properties": {
            // Complete live pipeline
        }
    }
  }

Коды состояния

Условие Код состояния Подробный код ошибки
Существующая сущность обновлена 200 Недоступно
Новая сущность создана 201 Недоступно
Общие ошибки пользователя Ошибки диапазона 400 Н/Д
Ошибки проверки динамического конвейера 400 PipelineValidationError
Ошибки проверки модуля 400 ModuleValidationError
Ошибки проверки ресурсов 409 ResourceValidationError
Общие ошибки сервера Ошибки диапазона 500 Н/Д

livePipelineDelete

Удаляет один динамический конвейер.

Ключевые аспекты:

  • Удалять можно только деактивированные динамические конвейеры.

Запрос

  {
        "@apiVersion": "1.1",
        "name": "{livePipelineName}"
  }

Ответ

  {
    "status": 200,
    "payload": null
  }

Коды состояния

Условие Код состояния Подробный код ошибки
Динамический конвейер успешно удален 200 Недоступно
Динамический конвейер не найден. 204 Недоступно
Общие ошибки пользователя Ошибки диапазона 400
Конвейер не находится в деактивированном состоянии. 409 OperationNotAllowedInState
Общие ошибки сервера Ошибки диапазона 500

livePipelineGet

Аналогично livePipelineTopologyGet. Получает динамический конвейер с указанным именем, если он существует.

Запрос

  {
        "@apiVersion": "1.1",
        "name": "{livePipelineName}"       
  }

Ответ

{
  "status": 200,
  "payload": {
    "value": [
      {
        "systemData": {
          "createdAt": "2021-05-06T10:28:04.560Z",
          "lastModifiedAt": "2021-05-06T10:28:04.560Z"
        },
        "name": "{livePipelineName}",
        // Complete live pipeline
      }
    ]
  }
}

Коды состояния

Условие Код состояния
Успешно 200
Общие ошибки пользователя Ошибки диапазона 400
Общие ошибки сервера Ошибки диапазона 500

livePipelineActivate

Активирует динамический конвейер.

Ключевые аспекты

  • Метод возвращает состояние динамического конвейера — "Активация" или "Активирован".
  • Операция перечисления/присвоения, примененная к динамическому конвейеру, вернет текущее состояние.
  • Этот метод можно вызвать, если динамический конвейер не находится во (временном) состоянии "Деактивация".
  • Идемпотентность:
    • Вызов livePipelineActivate для динамического конвейера, который уже находится в состоянии "Активация", будет действовать так же, как если бы динамический конвейер был деактивирован.
    • Активация конвейера, находящегося в состоянии "Активный", немедленно возвращает код успешного выполнения.

Запрос

  {
        "@apiVersion": "1.1",
        "name": "{livePipelineName}"
  }

Ответ

{
    "status": 200,
    "payload": null
}

Коды состояния

Условие Код состояния Подробный код ошибки
Конвейер успешно активирован. 200 Недоступно
Новая сущность создана 201 Недоступно
Общие ошибки пользователя Ошибки диапазона 400
Ошибки проверки модуля 400 ModuleValidationError
Ошибки проверки ресурсов 409 ResourceValidationError
Динамический конвейер находится в состоянии деактивации. 409 OperationNotAllowedInState
Общие ошибки сервера Ошибки диапазона 500

livePipelineDeactivate

Деактивирует динамический конвейер. Деактивация конвейера корректно деактивирует обработку видео и гарантирует, что все события и видео, кэшированные на пограничном устройстве, фиксируются в облаке, когда это применимо.

Ключевые аспекты:

  • Метод возвращается, только когда динамический конвейер деактивирован.
  • Этот метод можно вызвать, если динамический конвейер не находится во (временном) состоянии "Активация".
  • При деактивации конвейер принимает состояние "Деактивация".
    • Операция перечисления/присвоения, примененная к динамическому конвейеру, вернет текущее состояние.
    • Деактивация завершается, когда все данные мультимедиа переданы в облако (если конвейер имеет узел приемника видео).
  • Идемпотентность:
    • Вызов livePipelineDeactivate для динамического конвейера, который уже находится в состоянии "Деактивация", будет действовать так же, как если бы динамический конвейер находился в состоянии "Активный".
    • Деактивация конвейера, находящегося в состоянии "Неактивный", немедленно возвращает код успешного выполнения.

Запрос

  {
    "@apiVersion": "1.1",
    "name": "{livePipelineName}"
  }

Ответ

{
 "status": 200,
 "payload": null
}
Условие Код состояния Подробный код ошибки
Конвейер успешно активирован. 200 Недоступно
Новая сущность создана 201 Недоступно
Общие ошибки пользователя Ошибки диапазона 400
Конвейер находится в состоянии активации. 409 OperationNotAllowedInState
Общие ошибки сервера Ошибки диапазона 500

remoteDeviceAdapterList

Выводит список всех адаптеров удаленных устройств. Модуль Edge "Видеоанализатор Azure" может выступать в качестве прозрачного шлюза для видео, позволяя находящимся за брандмауэром устройствам Интернета вещей передавать видео в облако. Для каждого такого устройства Интернета вещей необходимо создать адаптер удаленного устройства. В этом случае связь между облаком и устройством Интернета вещей будет обеспечиваться через модуль Edge "Видеоанализатор Azure".

Запрос

  {
        "@apiVersion": "1.1"
  }

Ответ

{
  "status": 200,
  "value": [
    {
      "systemData": {
        "createdAt": "2021-10-05T14:19:22.16Z",
        "lastModifiedAt": "2021-10-05T16:20:41.505Z"
      },      
      // first remote device adapter payload
    },
      "systemData": {
        "createdAt": "2021-10-06T14:19:22.16Z",
        "lastModifiedAt": "2021-10-06T16:20:41.505Z"
      },
      // next remote device adapter  payload
    }    
  ]
}

Коды состояния

Условие Код состояния
Найдена сущность 200
Общие ошибки пользователя Ошибки диапазона 400
Сущность не найдена 404
Общие ошибки сервера Ошибки диапазона 500

remoteDeviceAdapterSet

Создает адаптер удаленного устройства с заданным именем (если такой адаптер не существует) или обновляет существующий адаптер с указанным именем. В полезных данных ответа, а также в remoteDeviceAdapterList вызовах или remoteDeviceAdapterGet, пропускаются любые учетные данные или секреты.

Запрос

  {
        "@apiVersion": "1.1",
        "name": "{remoteDeviceAdapterName}",
        "properties": {
            // Desired remote device adapter properties
        }
  }

Ответ

  {
    "status": 201,
    "payload": {
        "systemData": {
           "createdAt": "2021-10-11T18:16:46.491Z",
           "lastModifiedAt": "2021-10-11T18:16:46.491Z"
        },
        "name": "{remoteDeviceAdapterName}",
        "properties": {
            // Remote device adapter properties, except the credentials
        }
    }
  }

Коды состояния

Условие Код состояния Подробный код ошибки
Существующая сущность обновлена 200 Недоступно
Новая сущность создана 201 Недоступно
Общие ошибки пользователя Ошибки диапазона 400 Н/Д
Ошибки проверки адаптера удаленного устройства 400 RemoteDeviceAdapterValidationError
Ошибки проверки модуля 400 ModuleValidationError
Ошибки проверки ресурсов 409 ResourceValidationError
Общие ошибки сервера Ошибки диапазона 500 Н/Д

remoteDeviceAdapterGet

Это аналогично livePipelineTopologyGet. Получает адаптер удаленного устройства с указанным именем, если он существует (любые учетные данные или секреты пропускаются).

Запрос

  {
        "@apiVersion": "1.1",
        "name": "{remoteDeviceAdapterName}"       
  }

Ответ

{
  "status": 200,
  "payload": {
    "value": [
      {
        "systemData": {
          "createdAt": "2021-10-06T10:28:04.560Z",
          "lastModifiedAt": "2021-10-06T10:28:04.560Z"
        },
        "name": "{remoteDeviceAdapterName}",
        // Remote device adapter properties, except the credentials
      }
    ]
  }
}

Коды состояния

Условие Код состояния
Успешно 200
Общие ошибки пользователя Ошибки диапазона 400
Общие ошибки сервера Ошибки диапазона 500

remoteDeviceAdapterDelete

Удаляет один адаптер удаленного устройства, если он существует.

Запрос

  {
        "@apiVersion": "1.1",
        "name": "{remoteDeviceAdapterName}"
  }

Ответ

  {
    "status": 200,
    "payload": null
  }

Коды состояния

Условие Код состояния Подробный код ошибки
Адаптер удаленного устройства успешно удален 200 Недоступно
Не удалось найти адаптер удаленного устройства 204 Недоступно
Общие ошибки пользователя Ошибки диапазона 400
Общие ошибки сервера Ошибки диапазона 500

onvifDeviceDiscover и onvifDeviceGet

Подробные сведения об этих вызовах приведены в статье Обнаружение устройств с поддержкой ONVIF.

Дальнейшие действия

Схема конфигурации двойника модуля