`lib-obix` 库参考

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793914668/FIN+5.3.1+lib-obix 中文整理基于 FIN 5.3.1

导读： 本页为 lib-obix 的 API / 标签 / 函数参考文档。

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

目录（导读）

lib
meta
docs
tags
funcs
Overview
Server URIs
Server Rec to Obix Mapping
Server Watches
Obix Connectors
Obix Connector Points
- Obix Cur
- Obix Writes
- Obix His
- def
obixInvoke(conn, uri, arg)
- supertypes
obixPing(conn)
obixReadHis(conn, uri, span)
obixReadObj(conn, uri)
obixSyncCur(points)
obixSyncHis(points, span: null)
obixWriteObj(conn, uri, arg)
- usage
- tags

概述（中译）

oBIX 连接器

API 正文（英文）

docs

Overview • Server URIs • Server Rec to Obix Mapping • Server Watches • Obix Connectors • Obix Connector Points


obixConn	Connector to an oBIX HTTP server
obixConnRef	Used on a proxy point to reference its parent `obixConn`
obixCur	Used on a oBIX proxy point to store the URI of the entity in the remote system used to read and watch `curVal`
obixHis	URI of the `obix:History` to synchronized history data
obixLobby	The lobby URI is used to address an `obixConn` API endpoint
obixPoint	Point which synchronizes data via a oBIX connector
obixPollFreq	Duration between obixConn watch polls
obixWritable	Server export of a writable point as an `obix:Writable:Point`
obixWrite	URI of the `obix:WritablePoint` to write `writeVal`
obixWriteLevel	Number between 1 and 16 used with `obixWrite` to determine which priority level of the remote system is written to

funcs


obixInvoke	Invoke an `obix:op` operation as identified by given uri
obixPing	Deprecated - use `connPing()`
obixReadHis	Synchronously query a `obix::History` for its timestamp/value pairs
obixReadObj	Read one Uri from an obixConn
obixSyncCur	Deprecated - use `connSyncCur()`
obixSyncHis	Deprecated - use `connSyncHis()`
obixWriteObj	Write an object as identified by given uri

lib obix

Overview

The Obix protocol is a REST protocol which uses an XML encoding. The Obix connector implements both the client and server side of the protocol. The following features are supported:

Obix Server

reads of any record
history queries (any record tagged as his maps to obix:History)
writable points are supported (if annotated correctly)
batch operations are supported
watches on records are supported
alarming is not supported

Obix Client

Obix connectors
proxy real-time points and watches supported
proxy writable points supported
proxy histories and synchronization supported
reads, writes, invokes all supported
alarming is not supported

Server URIs

The following table summarizes the URIs of the Obix server API:

Uri                              Object
------------------------         -------------
{base}/obix/                     lobby
{base}/obix/about/               about
{base}/obix/batch/               batch op
{base}/obix/watchService/        watch service
{base}/obix/watch/{id}/          watch operations
{base}/obix/query/{filter}       query recs using filter
{base}/obix/rec/{id|name}/       record
{base}/obix/rec/{id|name}/{tag}  tag
{base}/obix/icon/{id}/{uri}      icon tunnelling

On Haxall nodes {base} will be /api and on SkySpark it will be /api/{proj}/ext.

Server Rec to Obix Mapping

The general rules are applied to map Folio records to Obix objects:

marker tags are mapped to the is contract as tag:{name}
tag name/value pairs are mapped as child objects of the appropriate scalar type
the dis tag is mapped to the displayName facet

Example:

// folio
{id:1331259c-95d44d6a, dis:"Bob", age:37, bday:1973-07-11,
 person, married, spouse:1331364b-eee35493}

// obix
<obj is="tag:person tag:married"
     displayName="Bob"
     href="/api/proj/ext/obix/rec/1331259c-95d44d6a/">
 <dis  name="dis"    href="dis"  val="Bob"/>
 <int  name="age"    href="age"  val="37"/>
 <date name="bday"   href="bday" val="1973-07-11"/>
 <ref  name="spouse" href="/api/proj/ext/obix/1331364b-eee35493/"/>
</obj>

The following tags map to Obix contracts:

point maps to obix:Point
obixWritable maps to obix:WritablePoint
his maps to obix:History
curVal maps to point object val attribute
curStatus maps to a point object status attribute

For example given this point record:

id: 1746a5e5-a5d285cb
point
his
dis: <Site-A RTU-2 Zone-Temp>
siteRef: <Site-A>
equipRef: <Site-A RTU-2>
zone
air
temp
sensor
curVal: 72°F
tz: New_York
kind: Number

Maps to this Obix representation

<real href="/api/proj/ext/obix/rec/1746a5e5-a5d285cb/"
     is="obix:Point obix:History tag:air tag:his tag:point tag:sensor tag:temp tag:zone"
     displayName="Site-A RTU-2 Zone-Temp"
     val="72" status="ok">
  <str name="tz" val="America/New_York"/>
  <op name="query" href="query" in="obix:HistoryFilter" out="obix:HistoryQueryOut"/>
  <str name="dis" href="dis" val="Site-A RTU-2 ZoneTemp"/>
  <ref name="equipRef" href="/api/proj/ext/obix/rec/1746a5e5-920b2573/" display="Site-A RTU-2"/>
  <strname="kind" href="kind" val="Number"/>
  <ref name="siteRef" href="/api/proj/ext/obix/rec/1746a5e5-7f296626/" display="Site-A"/>
</real>

Server Watches

The Obix server allows watches at the record level. Watch URIs must be formatted exactly as follows:

{base}/obix/rec/{id}/

Any attempt to use a URI which doesn't match that format exactly or is missing a trailing slash will result in a BadUriErr for the subscription. Obix server watches map directly to a HxWatch.

On the initial poll, reference tags of type Ref will have their display attribute available for the record reference. But all polls will omit the display attribute for performance.

Obix Connectors

Client functionality is based on Obix Connectors which are created using the obixConn tag. Connectors are used to configure client settings to communicate with a remote Obix server using these tags:

conn: required marker tag
obixConn: required marker tag
obixLobby: the absolute URI of the server's lobby (should end in a trailing slash)
username: user name for authentication
password: must have password stored in password db for connector's record id

Obix connectors are built with the connector framework and follow all the standard conventions.

Obix connectors will use Haystack authentication to connect to the remote system. You can force HTTP basic authentication by adding the marker tag obixBasicAuth to your connector record.

After the first read operation with the connector (see obixPing()) the following tags are available on the connector:

vendorName: from about object
productName: from about object
productVersion: from about object
tz: timezone name of remote obix server

Some older versions of Obix may not be able to derive the tz tag from the ping, in which case you should manually configure the tag to ensure that its available for history functions.

Obix Connector Points

Obix proxy points are configured under a given connector using the following tags:

obixConnRef: references the Obix connector
obixCur: URI to use for current value watches
obixWrite: URI to for writable points
obixHis: URI to use for obix:History for history synchronization

Obix Cur

When an point with the obixCur tag is put into watch, it subscribes to a watch on the Obix server. This subscription is used to maintain the current point value via the curVal. Watches are polled with a default frequency of 1sec; you can tune this frequency with the obixPollFreq tag.

Also see point.

Obix Writes

The obixWrite URI is used to configure the writePoint operation of an obix:WritablePoint. Note the URI must reference the operation inside the point object. Changes to the local writable point are written to the remote oBIX point.

Also see point.

Obix His

A proxy point with the obixHis tag is used to pull historical data from an Obix connector into the local historian. The Axon function connSyncHis() is used pull the latest history data over the Obix connector into the local historian. You can use these functions to write your own customized synchronization scripts. The general convention is to schedule history sync via tasks.

Also see point.


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function

lib-obix 库参考 ​

目录（导读） ​

概述（中译） ​

API 正文（英文） ​

docs ​

funcs ​

lib obix ​

Overview ​

Server URIs ​

Server Rec to Obix Mapping ​

Server Watches ​

Obix Connectors ​

Obix Connector Points ​

Obix Cur ​

Obix Writes ​

Obix His ​

func:obixInvoke ​

obixInvoke(conn, uri, arg) ​

func:obixPing ​

obixPing(conn) ​

func:obixReadHis ​

obixReadHis(conn, uri, span) ​

func:obixReadObj ​

obixReadObj(conn, uri) ​

func:obixSyncCur ​

obixSyncCur(points) ​

func:obixSyncHis ​

obixSyncHis(points, span: null) ​

func:obixWriteObj ​

obixWriteObj(conn, uri, arg) ​

obixConn ​

obixConnRef ​

obixCur ​

obixHis ​

obixLobby ​

obixPoint ​

obixPollFreq ​

obixWritable ​

obixWrite ​

obixWriteLevel ​

`lib-obix` 库参考

目录（导读）

概述（中译）

API 正文（英文）

docs

funcs

lib obix

Overview

Server URIs

Server Rec to Obix Mapping

Server Watches

Obix Connectors

Obix Connector Points

Obix Cur

Obix Writes

Obix His

func:obixInvoke

obixInvoke(conn, uri, arg)

func:obixPing

obixPing(conn)

func:obixReadHis

obixReadHis(conn, uri, span)

func:obixReadObj

obixReadObj(conn, uri)

func:obixSyncCur

obixSyncCur(points)

func:obixSyncHis

obixSyncHis(points, span: null)

func:obixWriteObj

obixWriteObj(conn, uri, arg)

obixConn

obixConnRef

obixCur

obixHis

obixLobby

obixPoint

obixPollFreq

obixWritable

obixWrite

obixWriteLevel