TOC

  1. Intro
  2. TagModel
  3. Structure
  4. TimeZones
  5. Units
  6. Grids
  7. Filters
  8. Zinc
  9. Json
  10. Trio
  11. Csv
  12. Rest
    1. 概述
    2. 认证
    3. URI命名空间
    4. 请求
      1. GET 请求
      2. POST 请求
    5. 响应
    6. 错误处理
    7. 内容协商
    8. Watches
  13. Ops
  14. Auth
  15. VFDs
  16. Networks
  17. Energy
  18. Zones
  19. AHUs
  20. VAVs
  21. UnitaryEquips
  22. Chillers
  23. Boilers
  24. Tanks
  25. ElecPanels
  26. Lighting
  27. Builds
  28. Bacnet
  29. ChangeLog
  30. License
Csv Ops

Rest

概述

Haystack REST API定义了一种通过HTTP交换haystack标签数据的简单机制。

haystack REST服务器实现一组 opsoperations 。操作是接收请求并返回响应的URI。定义标准 操作 以查询数据库,设置订阅或读/写历史时间序列数据。操作是可插拔的,以便供应商可以通过自己定制的额外功能增强其REST界面。

请求和响应都被建模为网格 grids。网格使用一种用于网格序列化的标准MIME类型进行编码,或者可以使用HTTP内容协商进行查询或者修改。

从技术上讲,Haystack REST API从纯粹主义的角度来看并不是所有的“RESTful” - ops设计更像RPC模型。但是我们使用术语REST将设计与使用XML,SOAP等的传统WS- * Web服务进行区分(尽管这种设计可以轻松地通过该技术)。

认证

大家都抱怨HTTP实施都必须实现在指定的认证协议在验证,在 Auth 章节可以了解到。

URI命名空间

haystack server将HTTP URI定义为其基址。然后操作将映射为该地址下的路径名。例如:

http://server/haystack/           // 基本Uri
http://server/haystack/{op}       // 操作URI模式
http://server/haystack/about      // about op
http://server/haystack/read       // read op

必须假设基本URI以尾部斜杠结尾,即使不总是以这种方式表示。

请求

客户端通过发送单个网格请求和服务器交互,并且服务器响应数据。通常使用 Zinc 编码网格,但使用的实际编码可以使用 内容协商 进行插入。

GET 请求

许多操作不需要网格参数或者单行的网格。在这种情况下,可以使用HTTP GET请求来执行请求。请求网格编码在HTTP查询字符串中,其中每个查询参数映射到单个行中的标记。标签值必须是Zinc编码的,否则服务器会假定它是Str类型。

空网格请求示例:

// 请求 URI
/haystack/about

// 用Zinc编码格式请求
ver:"3.0"
empty

使用单个Str标签的请求示例:

// 请求地址
/haystack/read?filter=site

// 用Zinc编码格式请求
ver:"3.0"
filter
"site"

使用多个标签编码为Zinc的请求示例:

// 请求地址
/haystack/hisRead?id=@hisId&range=yesterday

// 用Zinc编码格式请求
ver:"3.0"
id,range
@hisId,"yesterday"

POST 请求

如果请求网格不是单行名称/值对,而必须使用HTTP POST发送。客户端必须使用服务器支持的MIME类型对网格进行编码。客户端可以使用格式 formats op 来查询支持的MIME类型。以下是使用Zinc发送到hisRead op的示例:

POST /haystack/hisRead HTTP/1.1
Content-Type: text/zinc; charset=utf-8
Content-Length: 39

ver:"3.0"
id,range
@outsideAirTemp,"yesterday"

响应

如果请求网格由服务器成功读取,则处理该操作并返回HTTP状态代码200,并将响应结果序列化为MIME编码网格

错误处理

当客户端向服务器发出请求时,可能会出现三种类型的错误:

当客户端无法成功连接到服务器的TCP连接时,会发生网络错误。这可能包括无效的主机名,端口号或网络中断。通常,这些错误由客户机运行时的I / O异常引起。

TCP连接可以成功建立,但服务器无法在HTTP层成功处理URI或请求网格时发生HTTP错误。在这些情况下必须使用以下HTTP状态代码:

服务器成功读取请求网格后发生请求错误。如果服务器由于任何原因无法满足请求,那么它必须返回200的HTTP响应代码,并以 error grid 作为主体。只有当请求网格本身无法读取时,才能使用HTTP错误代码。请求错误包括但不限于:

Grid 错误[#errorGrid]

如果服务器成功读取请求grid后操作失败,则服务器返回grid错误。错误网格由 err 网格元数据中的标记标记的存在指示。所有错误网格必须包含一个'dis'字段,并具包含一个人类可读的问题描述。如果服务器运行时支持堆栈跟踪,则应通过 errTrace 标签中获得多行字符串报告。

以Zinc编码的错误网格为例:

ver:"3.0" err dis:"Cannot resolve id: badId" errTrace:"UnknownRecErr: badId\n  ...."
empty

客户必须始终检查err网格标记标签的现在,以确定响应是错误还是有效的结果。

内容协商

所有REST操作的默认值是将结果返回为使用Zinc格式化的MIME类型 "text/plain"的格式。您可以通过在HTTP请求中指定"Accept"标头来请求以替代要接收的结果格式。

以下"Accept"标头的MIME类型是标准化的:

如果将不支持的MIME类型作为了"Accept"标头,则返回406不可接受的错误代码。

以CSV格式读取所有网站实体的示例:

GET /haystack/read?filter=site
Content-Type: text/plain; charset=utf-8
Accept: text/csv

响应:

HTTP/1.1 200 OK
Content-Type: text/csv; charset=utf-8

dis,area,geoAddr
Site A,2000ft²,"1000 Main St,Richmond,VA"
Site B,3000ft²,"2000 Cary St,Richmond,VA"

所有"text/"类型必须使用UTF-8对进行编码。

Watches

Haystack采用oBIX的watch设计来处理实时订阅。Watches是一种有状态的轮询机制,旨在通过HTTP高效工作。

watch的生命周期如下

  1. 客户端使用 watchSub 创建新的watch
  2. 客户端使用 watchPoll 操作轮询已更改的实体
  3. 客户端使用 watchUnsub显式关闭watch,或者如果客户端在租赁期后未能轮询,服务器可能会自动关闭watch

在watch的使用期限内,客户可以选择:

  1. 使用 watchSub 向watch添加新实体
  2. 使用 watchUnsub 从watch中移除实体 3.执行轮询刷新以使用 watchPoll重新读取所有观看的实体
Csv Ops