HTTP 扩展协议HTTP extension protocol

使用 IoT Edge 上的实时视频分析,可以通过图形扩展节点扩展媒体图处理功能。Live Video Analytics on IoT Edge allows you to extend the media graph processing capabilities through a graph extension node. 如果使用 HTTP 扩展处理器作为扩展节点,则实时视频分析模块与 AI 或 CV 模块之间的通信是通过 HTTP 进行的If you use the HTTP extension processor as the extension node, then the communication between Live Video Analytics module and your AI or CV module is over HTTP

在本文中,你将学习如何使用 HTTP 扩展协议在实时视频分析模块与 AI 或 CV 模块之间发送消息。In this article, you will learn about using HTTP extension protocol to send messages between Live Video Analytics module and your AI or CV module.

HTTP 协定在以下两个组件之间定义:The HTTP contract is defined between the following two components:

  • HTTP 服务器HTTP server
  • IoT Edge 上的实时视频分析模块(充当 HTTP 客户端)Live Video Analytics on IoT Edge module acts as the HTTP client

请求Request

从实时视频分析模块到 HTTP 服务器的请求如下所示:Requests from Live Video Analytics module to your HTTP server would be as follows:

密钥Key Value
POSTPOST https://hostname/optional-path?optional-query
AcceptAccept application/json, /application/json, /
授权Authorization 基本、摘要式和持有者(通过自定义标头支持)Basic, Digest, Bearer (through custom header support)
Content-TypeContent-Type image/jpegimage/jpeg
image/pngimage/png
image/bmpimage/bmp
image/x-rawimage/x-raw
Content-Length 正文长度(以字节为单位)Content-Length Body length, in bytes
User-AgentUser-Agent Azure 媒体服务Azure Media Services
正文Body 图像字节数,二进制编码为某个受支持的内容类型。Image bytes, binary encoded in one of the supported content types.

示例Example

POST http://localhost:8080/inference HTTP/1.1
Host: localhost:8080
x-ms-client-request-id: d6050cd4-c9f2-42d3-9adc-53ba7e440f17
Content-Type: image/bmp
Content-Length: 519222

(Image Binary Content)

响应Response

你的模块对实时视频分析模块的响应如下所示:Responses from your module to Live Video Analytics module should be as follows:

密钥Key Value
状态代码Status Codes 200 正常 - 找到了推理结果200 OK - Inference results found
204 无内容 - AI 未找到内容204 No Content - No content found by the AI
400 错误的请求 - 非预期400 Bad Request - Not expected
500 内部服务器错误 - 非预期500 Internal Server Error - Not expected
503 服务器繁忙 - AMS 将基于“Retry-After”标头(如果未预设标头,则基于默认时间量)回退。503 Server Busy - AMS will back-off based on "Retry-After" header or based on a default amount of time in case header not preset.
Content-TypeContent-Type application/jsonapplication/json
Content-LengthContent-Length 以字节为单位的正文长度。Body length, in bytes
正文Body 具有单个“inferences”属性的 JSON 对象。JSON object with single "inferences" property.

示例Example

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 468
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 17 Apr 2020 04:44:01 GMT

{
  "inferences": [
    {
      "type": "entity",
      "entity": {
        "tag": { "value": "car", "confidence": 0.9048132 },
        "box": { "l": 0.42681578, "t": 0.47660735, "w": 0.019501392, "h": 0.020954132 }
      }
    },
    {
      "type": "entity",
      "entity": {
        "tag": { "value": "car", "confidence": 0.8953932 },
        "box": { "l": 0.55083525, "t": 0.4843858, "w": 0.046550274, "h": 0.046502113 }
      }
    }    
  ]
}

强烈建议使用有效的 JSON 文档返回响应,并采用按照推理元数据架构对象模型定义的预建立架构。It is highly recommended that responses are returned using valid JSON documents following the pre-established schema defined as per the inference metadata schema object model. 这可以更好地确保与其他组件的互操作性,以及与未来可能添加到实时视频分析模块的功能的互操作性。This will better ensure interoperability with other components and possible future capabilities added to the Live Video Analytics module.

如果你的模块返回的响应的内容类型不是“application/json”,则实时视频分析会将消息编码为 base 64 内容,并将其序列化为不透明的 JSON 有效负载。If your module returns a response where the content type is not “application/json”, Live Video Analytics will encode the message as a base 64 content and serialize it as an opaque JSON payload.

如果模块返回的响应的内容类型是“application/json”,但 JSON 架构不遵循下面所述的推理元数据架构,则会通过管道转发消息有效负载,但互操作性会降低。If your module returns a response with content type as "application/json" but the JSON schema doesn't follow the inference metadata schema outlined below, the message payload will be forwarded through the pipeline, but interoperability will be reduced. 有关推理元数据架构的详细信息和最新信息,请参阅此处Please refer here for detailed and up to date infromation regarding the Inference metadata schema.

备注

如果你的模块未生成任何结果,它应返回响应正文为空的 HTTP 204 状态代码(无内容)。If your module doesn't produce any result, it should return HTTP 204 Status Code (No Content) with an empty response body. 实时视频分析将此理解为空结果,不会在整个管道中转发该事件。Live Video Analytics will understand this as an empty result and won't forward the event throughout the pipeline.

后续步骤Next steps

gRPC 扩展协议gRPC extension protocol