HTTP 扩展数据协定HTTP extension data contract

在本文中,你将学习如何使用 HTTP 协议在实时视频分析模块与 AI 或 CV 模块之间发送消息。In this article, you will learn about using HTTP 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 below. 这可以更好地确保与其他组件的互操作性,以及与未来可能添加到实时视频分析模块的功能的互操作性。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.

备注

如果你的模块未生成任何结果,它应返回响应正文为空的 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.

数据协定 - 类层次结构Data contracts - class hierarchy

类层次结构

后续步骤Next steps

gRPC 数据协定gRPC data contract