lib-haystack 库参考

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

导读： Haystack HTTP API 连接器

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

---

目录（导读）

• lib
• meta
• docs
• tags
• funcs
• Overview
• Current Points
• Writable Points
• His Sync
  • def
• haystackCall(conn, op, req: null, checked: true)
  • supertypes
• haystackEval(conn, expr, opts: null)
• haystackHisRead(conn, id, range)
• haystackInvokeAction(conn, id, action, args: null)
• haystackLearn(conn, arg: null)
• haystackPing(conn)
• haystackRead(conn, filterExpr, checked: true)
• haystackReadAll(conn, filterExpr)
• haystackReadById(conn, id, checked: true)
• haystackReadByIds(conn, ids, checked: true)
• haystackSyncCur(points)
• haystackSyncHis(points, span: null)
  • usage
  • tags

---

概述（中译）

Haystack HTTP API 连接器

---

API 正文（英文）

docs

Overview • Current Points • Writable Points • His Sync

---

tags

haystackConn	Haystack connector to a Haystack REST API server
haystackConnRef	Used on a proxy point to reference its parent haystackConn
haystackCur	Used on a haystack proxy point to store the id of the entity in the remote system used to read and watch curVal
haystackHis	Used on a haystack proxy point object to store the id of the historized point in the remote system used to sync history data
haystackPoint	Point which synchronizes data via a Haystack connector
haystackPollFreq	Applied to haystackConn to tune the duration between watch polls
haystackWrite	Used on a haystack proxy point to store the id of the entity in the remote system used to write writeVal
haystackWriteLevel	Number between 1 and 16 used with haystackWrite to determine which priority level of the remote system is written to

---

funcs

haystackCall	Perform Haystack HTTP API call to given Str op name and with given request grid (can be anything acceptable toGrid())
haystackEval	Evaluate an Axon expression in a remote server over a haystack connector
haystackHisRead	Perform Haystack REST API "hisRead" call to read history data for the record identified by the id (must be Ref)
haystackInvokeAction	Invoke a remote action on the given Haystack connector and remote entity
haystackLearn	Deprecated - use connLearn()
haystackPing	Deprecated - use connPing()
haystackRead	Perform Haystack REST API call to read single entity with filter
haystackReadAll	Perform Haystack REST API call to read all entities with filter
haystackReadById	Perform Haystack HTTP API call to read a record by its unique identifier
haystackReadByIds	Perform Haystack HTTP API call to read a list of records by their identifiers
haystackSyncCur	Deprecated - use connSyncCur()
haystackSyncHis	Deprecated - use connSyncHis()

---

lib haystack

Overview

This library provides a client connector for the Haystack HTTP API This connector can be used to communicate with other Haxall and SkySpark systems which all implement the server side of the Haystack API protocol. It is also commonly used to communicate with Niagara via the nHaystack and nhaystackAx modules.

The haystack connector provides full support for the following connector features:

• Learn tree via the nav op
• Current value subscription using watches
• Writable point support using pointWrite op
• History sync using the hisRead op

Note the haystackCur, haystackWrite, and haystackHis addresses for this connector must all be strings (not refs). This prevents them from being confused as internal references.

Current Points

Haystack proxy points are configured with haystackCur tag. Subscription uses Haystack watches to subscribe to the remote points current value. Watches use a poll for change design; you can tune the poll frequency via the haystackPollFreq connector tag.

Writable Points

Haystack proxy points are configured to write to remote system points via the haystackWrite tag. The priority level to write to in the remote system must be configured via the haystackWriteLevel tag. The following point would write its computed writeVal to level 14 of "remote-point":

point
writable
haystackConnRef: @conn
haystackWrite: "remote-point"
haystackWriteLevel: 14

His Sync

Haystack proxy points are configured for history synchronization via the haystackHis tag. These points use the hisRead op to read history data from the remote system.

---

---

def

func:haystackCall

haystackCall(conn, op, req: null, checked: true)

Perform Haystack HTTP API call to given Str op name and with given request grid (can be anything acceptable toGrid()). If the checked flag is true and server returns an error grid, then raise CallErr, otherwise return the grid itself. Result is returned as Grid. Also see Client.call.

---

meta

admin	✓
def	func:haystackCall
is	func
lib	lib:haystack
name	haystackCall

---

supertypes

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

---

---

def

func:haystackEval

haystackEval(conn, expr, opts: null)

Evaluate an Axon expression in a remote server over a haystack connector. The remote server must be a SkySpark server which supports the "eval" REST op with an Axon expression. This function blocks while the network request is made. The result is always returned as a Grid using the same rules as Etc.toGrid.

The expression to evaluate in the remote server may capture variables from the local scope. If these variables are atomic types, then they are captured as defined by local scope and serialized to the remote server. Pass {debug} for opts to dump to stdout the actual expr with serialized scope.

Options:

• debug: dumps full expr with seralized scope to stdout
• evalTimeout: duration number to override remote project's default evalTimeout

Examples:

read(haystackConn).haystackEval(3 + 4)
read(haystackConn).haystackEval(readAll(site))
read(haystackConn).haystackEval(readAll(kw).hisRead(yesterday))

---

meta

admin	✓
def	func:haystackEval
is	func
lib	lib:haystack
name	haystackEval

---

supertypes

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

---

---

def

func:haystackHisRead

haystackHisRead(conn, id, range)

Perform Haystack REST API "hisRead" call to read history data for the record identified by the id (must be Ref). The range is any string encoding supported by the REST API or any value supported by toDateSpan(). Return results as grid with "ts" and "val" column.

---

meta

admin	✓
def	func:haystackHisRead
is	func
lib	lib:haystack
name	haystackHisRead

---

supertypes

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

---

---

def

func:haystackInvokeAction

haystackInvokeAction(conn, id, action, args: null)

Invoke a remote action on the given Haystack connector and remote entity. The id must be a Ref of the remote entity's identifier and action is a Str action name. If args are specified, then they should be a Dict keyed by parameter name.

---

meta

admin	✓
def	func:haystackInvokeAction
is	func
lib	lib:haystack
name	haystackInvokeAction

---

supertypes

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

---

---

def

func:haystackLearn

haystackLearn(conn, arg: null)

Deprecated - use connLearn()

---

meta

admin	✓
def	func:haystackLearn
deprecated	✓
is	func
lib	lib:haystack
name	haystackLearn

---

supertypes

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

---

---

def

func:haystackPing

haystackPing(conn)

Deprecated - use connPing()

---

meta

admin	✓
def	func:haystackPing
deprecated	✓
is	func
lib	lib:haystack
name	haystackPing

---

supertypes

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

---

---

def

func:haystackRead

haystackRead(conn, filterExpr, checked: true)

Perform Haystack REST API call to read single entity with filter. The filter is an expression like readAll(). Return result as dict. If the record is not found, then return null or raise UnknownRecErr based on checked flag. Also see Client.read.

---

meta

admin	✓
def	func:haystackRead
is	func
lib	lib:haystack
name	haystackRead

---

supertypes

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

---

---

def

func:haystackReadAll

haystackReadAll(conn, filterExpr)

Perform Haystack REST API call to read all entities with filter. The filter is an expression like readAll(). Return results as grid. Also see Client.readAll.

---

meta

admin	✓
def	func:haystackReadAll
is	func
lib	lib:haystack
name	haystackReadAll

---

supertypes

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

---

---

def

func:haystackReadById

haystackReadById(conn, id, checked: true)

Perform Haystack HTTP API call to read a record by its unique identifier. Return result as dict. If the record is not found, then return null or raise UnknownRecErr based on checked flag. Also see Client.readById.

---

meta

admin	✓
def	func:haystackReadById
is	func
lib	lib:haystack
name	haystackReadById

---

supertypes

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

---

---

def

func:haystackReadByIds

haystackReadByIds(conn, ids, checked: true)

Perform Haystack HTTP API call to read a list of records by their identifiers. Return a grid where each row of the grid maps to the respective id list (indexes line up). If checked is true and any one of the ids cannot be resolved then raise UnknownRecErr for first id not resolved. If checked is false, then each id not found has a row where every cell is null. Also see Client.readByIds.

---

meta

admin	✓
def	func:haystackReadByIds
is	func
lib	lib:haystack
name	haystackReadByIds

---

supertypes

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

---

---

def

func:haystackSyncCur

haystackSyncCur(points)

Deprecated - use connSyncCur()

---

meta

admin	✓
def	func:haystackSyncCur
deprecated	✓
is	func
lib	lib:haystack
name	haystackSyncCur

---

supertypes

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

---

---

def

func:haystackSyncHis

haystackSyncHis(points, span: null)

Deprecated - use connSyncHis()

---

meta

admin	✓
def	func:haystackSyncHis
deprecated	✓
is	func
lib	lib:haystack
name	haystackSyncHis

---

supertypes

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

---

---

def

haystackConn

Haystack connector to a Haystack REST API server.

---

meta

connFeatures
def	haystackConn
icon	haystack
is	conn
lib	lib:haystack

---

usage

haystackConn  conn

---

supertypes

marker	Marker labels a dict with typing information
entity	Top-level dicts with a unique identifier
conn	Connector for communication to a remote system

---

tags

actorTimeout	Timeout for messages send to the connector's actor thread
connErr	Error message associated when connStatus indicates an error condition
connLinger	Linger timeout used to keep a connector open
connOpenRetryFreq	Duration used for connector open retries
connPingFreq	Duration used to configure the auto-ping feature on a given connector
connState	Current connection state of a connector as one of the predefined strings
connStatus	Current status of a connector as one of the predefined strings See Connectors
connTuningRef	Reference to a tuning configuration defined by a connTuning rec
dis	Display name for an entity
disabled	Indicates the entity is in a disabled state
haystackPollFreq	Applied to haystackConn to tune the duration between watch polls
id	Defines the unique identifier of an entity in system using a ref value type
password	Manages password which is hashed/stored to the password store
tz	Timezone identifier from standard timezone database
uri	Universal resource identifier
username	Username for an authentication account

---

---

def

haystackConnRef

Used on a proxy point to reference its parent haystackConn

---

meta

def	haystackConnRef
is	ref
lib	lib:haystack
of	haystackConn
tagOn	haystackPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
ref	Reference to an entity

---

---

def

haystackCur

Used on a haystack proxy point to store the id of the entity in the remote system used to read and watch curVal.

---

meta

def	haystackCur
is	str
lib	lib:haystack
tagOn	haystackPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

haystackHis

Used on a haystack proxy point object to store the id of the historized point in the remote system used to sync history data.

---

meta

def	haystackHis
is	str
lib	lib:haystack
tagOn	haystackPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

haystackPoint

Point which synchronizes data via a Haystack connector.

---

meta

def	haystackPoint
is	connPoint
lib	lib:haystack

---

usage

haystackPoint  point

---

supertypes

marker	Marker labels a dict with typing information
entity	Top-level dicts with a unique identifier
point	Data point such as a sensor or actuator
connPoint	Point associated with a connector for data synchronization with a remote system

---

tags

connTuningRef	Reference to a tuning configuration defined by a connTuning rec
cur	Supports current value
curCalibration	Calibration value to apply to adjust the value read from the connector before updating curVal
curConvert	Conversion to apply when reading curVal from connector
dis	Display name for an entity
disMacro	Display name using macro syntax
disabled	Indicates the entity is in a disabled state
enum	Defines an eumeration of string key names
equipRef	Reference to equip which contains this entity
ghgFactorHis	Identifies point record with interval emission factor data that the Greenhouse Gas Emission Engine uses to calculate emissions
haystackConnRef	Used on a proxy point to reference its parent haystackConn
haystackCur	Used on a haystack proxy point to store the id of the entity in the remote system used to read and watch curVal
haystackHis	Used on a haystack proxy point object to store the id of the historized point in the remote system used to sync history data
haystackWrite	Used on a haystack proxy point to store the id of the entity in the remote system used to write writeVal
haystackWriteLevel	Number between 1 and 16 used with haystackWrite to determine which priority level of the remote system is written to
his	Supports historization of data
hisConvert	Conversion to apply when reading history data from connector
id	Defines the unique identifier of an entity in system using a ref value type
kind	Kind name used to identity a value data type
maxVal	Inclusive maximum for a numeric value
minVal	Inclusive minimum for a numeric value
navName	Navigation name commonly used with disMacro to create computed display strings
pointFunction	Classifies the point as a sensor, command, or setpoint
pointQuantity	Quantity the point senses or controls
pointSubject	What the point senses or controls
siteRef	Reference to site which contains the entity
spaceRef	Reference to space which contains this entity
systemRef	Reference to system
tz	Timezone identifier from standard timezone database
unit	Unit identifier from standard unit database
writable	Supports writing data
writeConvert	Conversion to apply when writing writeVal to the connector

---

---

def

haystackPollFreq

Applied to haystackConn to tune the duration between watch polls. If not configured it defaults to 1sec.

---

meta

def	haystackPollFreq
is	duration
lib	lib:haystack
tagOn	haystackConn
val	1sec

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
number	Integer or floating point numbers annotated with an optional unit
duration	Number with a unit of time

---

---

def

haystackWrite

Used on a haystack proxy point to store the id of the entity in the remote system used to write writeVal.

---

meta

def	haystackWrite
is	str
lib	lib:haystack
tagOn	haystackPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

haystackWriteLevel

Number between 1 and 16 used with haystackWrite to determine which priority level of the remote system is written to.

---

meta

def	haystackWriteLevel
defVal	16
is	int
lib	lib:haystack
maxVal	16
minVal	1
tagOn	haystackPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
number	Integer or floating point numbers annotated with an optional unit
int	Unitless integer number