@8devices/restserver-api 中文文档教程

Question

restserver-api

示例程序 此示例显示了基本的 restserver-api 用法。

const restAPI = require('restserver-api');

const { Lwm2m } = restAPI;
const { RESOURCE_TYPE, encodeResource, decodeResource } = Lwm2m.TLV;

console.log('Initialize service and endpoint');
const service = new restAPI.Service();
const device = new restAPI.Device(service, 'urn:uuid:17200d69-ec9b-43b3-9051-73df2207907c');

console.log('Encode resource to TLV format');
const tlvBuffer = encodeResource({
  identifier: 3,
  type: RESOURCE_TYPE.INTEGER,
  value: 60
});

console.log('Start service');
service.start().then(() => {
  console.log('Service started');
  console.log('Writing into device\'s resource');
  device.write('/3/0/7', (status) => {
    console.log('Received response with status: ', status);
    console.log('Stopping service');
    service.stop().then(() => {
      console.log('Service stopped');
    });
  }, tlvBuffer);
});

Classes

Device

此类表示设备（端点）。

Service

此类表示 REST API 服务。

Constants

TYPE

表示 LwM2M 变量（标识符）类型（OBJECT_INSTANCE， 多个资源、资源实例、资源）。

RESOURCE_TYPE

表示资源类型（NONE、BOOLEAN、INTEGER、FLOAT、STRING、OPAQUE）。

Functions

getDictionaryByValue(dictionaryList, keyName, value) ⇒ Object | string | number

通过键和值的给定名称获取字典。

encodeResourceValue(resource) ⇒ object

对资源的值进行编码。

decodeResourceValue(buffer, resource) ⇒ Object | string | number | boolean

解码资源的价值。

encode(object) ⇒ object

编码 ant 类型的实例（对象实例、多个资源、资源实例、资源）。

encodeResourceInstance(resourceInstance) ⇒ object

将资源实例编码到 TLV 缓冲区。

encodeMultipleResourcesTLV(resources) ⇒ object

将多个资源值编码到 TLV 缓冲区。

encodeResource(resource) ⇒ object

将资源编码到 TLV 缓冲区。

encodeObjectInstance(objectInstance) ⇒ object

将 LwM2M 对象实例编码到 TLV 缓冲区。

encodeObject(object) ⇒ object

将 LwM2M 对象编码到 TLV 缓冲区。

decode(buffer) ⇒ object

解码任何 TLV 缓冲区。

decodeResourceInstance(buffer, resources) ⇒ object

解码资源实例。

decodeResourceInstanceValue(buffer, resourceInstance) ⇒ object

解码资源实例值

decodeResource(buffer, resource) ⇒ object

解码资源。

decodeObjectInstance(buffer, objectInstance) ⇒ object

从 TLV 缓冲区解码对象实例。

decodeObject(buffer, object) ⇒ object

将 LwM2M 对象解码到 TLV 缓冲区。

Device

这个类表示设备（端点）。

Kind：全局类

• Device
  • new Device(service, id)
  • .getObjects() ⇒ Promise
  • .read(path, callback) ⇒ Promise
  • .write(path, callback, payload, type) ⇒ Promise
  • .execute(path, callback, payload, type) ⇒ Promise
  • .observe(path, callback) ⇒ Promise
  • .cancelObserve(path) ⇒ Promise

new Device(service, id)

构造函数初始化给定的服务对象，设备的 id 并开始监听服务发出的事件（当设备 注册、更新、注销、发送数据），处理“异步 响应”并发出“注册”、“更新”、“取消注册”事件。

Param	Type	Description
service	object	Service object
id	string	Endpoint id

示例

const restAPI = require('restserver-api');

const service = new restAPI.Service(serviceOptions);
const device = new restAPI.Device(service, 'deviceId');

device.getObjects() ⇒ Promise

发送请求以获取所有设备的对象。

Kind：Device
的实例方法 返回：Promise - Promise 对象与设备的对象
示例

device.getObjects().then((resp) => {
  // resp = [ { uri: '/1/0' }, { uri: '/2/0' }, ... ]
}).catch((err) => {
  // err - exception message object or status code
});

device.read(path, callback) ⇒ Promise

发送读取设备资源数据的请求。

种类：Device
的实例方法 返回：Promise - Promise with async response id

Param	Type	Description
path	string	Resource path
callback	function	Callback which will be called when async response is received

Example

device.read(path, (status, payload) => {
  // status = 200
  // payload = 4RbaAA==
}).then((asyncResponseId) => {
  // asyncResponseId = 1533889157#42f26784-1a8d-4861-36aa-d88f
}).catch((err) => {
  // err - exception object or status code
});

device.write(path, callback, payload, type) ⇒ Promise

发送写入请求价值转化为设备的资源。

种类：Device
的实例方法 返回：Promise - 具有异步响应 ID

Param	Type	Default	Description
path	string		Resource path
callback	function		Callback which will be called when async response is received
payload	buffer		Data (optional)
type	string	"application/vnd.oma.lwm2m+tlv"	Content type (optional)

Example

device.write(path, (status) => {
  // status = 202
}, payload).then((asyncResponseId) => {
  // asyncResponseId = 1533889926#870a3f17-3e21-b6ad-f63d-5cfe
}).catch((err) => {
  // err - exception object or status code
});

device.execute(path, callback, payload, type) ⇒ Promise

发送请求以执行设备的 Promise资源。

种类：Device
的实例方法 返回：Promise - 具有异步响应 id

Param	Type	Default	Description
path	string		Resource path
callback	function		Callback which will be called when async response is received
payload	buffer		Data (optional)
type	string	"text/plain"	Content type (optional)

Example

device.execute(path, (status) => {
  // status = 202
}).then((asyncResponseId) => {
  // asyncResponseId = 1533889926#870a3f17-3e21-b6ad-f63d-5cfe
}).catch((err) => {
  // err - exception object or status code
});

device.observe(path, callback) ⇒ Promise

发送订阅请求资源。

种类：Device
的实例方法 返回：Promise - 带有异步响应id的Promise

Param	Type	Description
path	string	Resource path
callback	function	Callback which will be called when async response is received

Example

device.observe(path, (status, payload) => {
  // status = 200
  // payload = 4RbaAA==
}).then((asyncResponseId) => {
  // asyncResponseId = 1533889157#42f26784-1a8d-4861-36aa-d88f
}).catch((err) => {
  // err - exception object or status code
});

device.cancelObserve(path) ⇒ Promise

发送取消订阅的请求.

种类：Device
的实例方法 返回：Promise - 带有 HTTP 状态代码的 Promise

Param	Type	Description
path	string	Resource path

Example

device.cancelObserve(path).then((status) => {
  // status - status code
}).catch((err) => {
  // err - exception object
});

Service

此类表示 REST API 服务。

种类：全局类

• Service
  • new Service(opts)
  • .start(opts) ⇒ Promise
  • .stop() ⇒ Promise
  • .authenticate() ⇒ Promise
  • .registerNotificationCallback() ⇒ Promise
  • .deleteNotificationCallback() ⇒ Promise
  • .checkNotificationCallback() ⇒ Promise
  • .pullNotification() ⇒ Promise
  • .getDevices() ⇒ Promise
  • .getVersion() ⇒ Promise
  • .get(path) ⇒ Promise
  • .put(path, argument, type) ⇒ Promise
  • .delete(path) ⇒ Promise
  • .post(path, argument, type) ⇒ Promise

new Service(opts)

初始化默认配置。 使用给定的选项重新配置。

Param	Type	Description
opts	object	Options object (optional)

示例

const options = {
  // REST server's address
  host: 'http://localhost:8888',
  // CA certificate
  ca: '',
  // authentication (true or false)
  authentication: false,
  username: '',
  password: '',
  // notification polling (true or false)
  polling: false,
  // time between each poll in miliseconds
  interval: 1234,
  // port for socket listener (not relevant if polling is enabled)
  port: 5728,
};
new Service(options);

service.start(opts) ⇒ Promise

(Re)starts authentication, 套接字监听器创建和通知回调注册 或通知轮询过程。

Kind：Service
的实例方法 返回：Promise - 在服务启动时实现的Promise

Param	Type	Description
opts	object	Options object (optional)

Example

service.start().then(() => {
  // started service
}).catch((err) => {
  // err - exception object
});

Example （传递选项对象）< /em>

const options = {
  // REST server's address
  host: 'http://localhost:8888',
  // CA certificate
  ca: '',
  // authentication (true or false)
  authentication: false,
  username: '',
  password: '',
  // notification polling (true or false)
  polling: false,
  // time between each poll in miliseconds
  interval: 1234,
  // port for socket listener (not relevant if polling is enabled)
  port: 5728,
};
service.start(options);

service.stop() ⇒ Promise

停止接收和处理事件 停止此服务及其所有子服务 在 start() 中启动的。 清理资源

Kind：Service
的实例方法 返回：Promise - 在服务停止时实现的Promise
示例

service.stop().then(() => {
  // stopped service
});

service.authenticate() ⇒ Promise

发送请求以验证用户。

Kind：Service
的实例方法 返回：Promise - 带有身份验证数据的 Promise（令牌及其过期时间）
示例

service.authenticate().then((resp) => {
  // resp = { access_token: 'token-value', expires_in: 3600 }
}).catch((err) => {
  // err - exception message object or status code
});

service.registerNotificationCallback() ⇒ Promise

发送注册通知回调的请求。

Kind：Service
的实例方法 返回：Promise - 在注册通知回调时实现的Promise
示例

service.registerNotificationCallback().then(() => {
  // notification callback has been registered
}).catch((err) => {
  // err - exception object or status code
});

service.deleteNotificationCallback() ⇒ Promise

发送请求以删除通知回调。

Kind：Service
的实例方法 返回：Promise - 带有 HTTP 状态代码的 Promise
示例

service.deleteNotificationCallback().then((status) => {
  // status - status code
}).catch((err) => {
  // err - exception object
});

service.checkNotificationCallback() ⇒ Promise

发送请求以检查是否注册了通知回调。

Kind：Service
的实例方法 返回：Promise - 带有通知回调数据的Promise
示例

service.checkNotificationCallback().then((resp) => {
  // resp = { url: 'http://localhost:5728/notification', headers: {} }
}).catch((err) => {
  // err - exception message object or status code
});

service.pullNotification() ⇒ Promise

发送请求以获取挂起/排队的通知。

Kind：Service
的实例方法 返回：Promise - Promise 与通知数据（注册， 注销、更新、异步响应）
示例

service.pullNotification().then((resp) => {
  // resp = { registrations: [...], 'reg-updates': [...], ... }
}).catch((err) => {
  // err - exception object
});

service.getDevices() ⇒ Promise

发送请求以获取所有已注册的端点。

Kind：Service
的实例方法 返回：Promise - 带有端点列表的Promise
示例

service.getDevices().then((resp) => {
  // resp = [ { name: 'uuid-4567', type: '8dev_3700', ... }, ... ]
}).catch((err) => {
  // err - exception message object or status code
});

service.getVersion() ⇒ Promise

发送请求以获取 REST 服务器版本。

Kind：Service
的实例方法 返回：Promise - 使用 REST 服务器版本的 Promise
示例

service.getVersion().then((resp) => {
  // resp = '1.0.0'
}).catch((err) => {
  // err - exception object
});

service.get(path) ⇒ Promise

使用给定路径执行 GET 请求。

Kind：Service
的实例方法 返回：Promise - Promise with data and response object

Param	Type	Description
path	string	Request path

Example

service.get(path).then((dataAndResponse) => {
  // dataAndResponse.data - data object
  // dataAndResponse.resp - response object
}).catch((err) => {
  // err - exception object
});

service.put(path, argument, type) ⇒ Promise

Performs PUT requests with给定路径、数据和数据类型。

Kind：Service
的实例方法 返回：Promise - Promise 数据和响应对象

Param	Type	Default	Description
path	string		Request path
argument	object		Data which will be sent (optional)
type	string	"application/vnd.oma.lwm2m+tlv"	Data type (optional)

service.delete(path) ⇒ Promise

使用给定路径执行 DELETE 请求。

Kind：Service
的实例方法 返回：Promise - Promise with data and response object

Param	Type	Description
path	string	Request path

service.post(path, argument, type) ⇒ Promise

使用给定的路径、数据和数据类型执行 POST 请求。

Kind：Service
的实例方法 返回：Promise - Promise with data and response object

Param	Type	Default	Description
path	string		Request path
argument	object		Data which will be sent (optional)
type	string	"application/vnd.oma.lwm2m+tlv"	Data type (optional)

TYPE

表示 LwM2M 变量（标识符）类型（OBJECTINSTANCE， 多个资源、RESOURCE_INSTANCE、RESOURCE）。

种类：全局常量

RESOURCE_TYPE

表示资源类型（NONE、BOOLEAN、INTEGER、FLOAT、STRING、OPAQUE）。

种类：全局常量

getDictionaryByValue(dictionaryList, keyName, value) ⇒ Object | string | number

通过键和值的给定名称获取字典。

种类：全局函数
返回：对象 | <代码>字符串 | number - 字典

Param	Type	Description
dictionaryList	object	Dictionary list.
keyName	Object | string	Name of the key
value	Object | string | number	Value

encodeResourceValue(resource) ⇒ object

对资源值进行编码。

种类：全局函数
返回：object - buffer - 编码值的缓冲区。

Param	Type	Description
resource	object	Object which stores resource value and value's type.

示例

const resource = {
 type: TLV.RESOURCE_TYPE.INTEGER,
 value: 1
};

const encodedValue = encodeResourceValue(resource);
// encodedValue = <Buffer 01>

decodeResourceValue(buffer, resource) ⇒ Object | string | number | boolean

解码资源的值。

种类：全局函数
返回：对象 | <代码>字符串 | <代码>编号 | boolean - value - 指定类型的解码值

Param	Type	Description
buffer	object	Buffer which will be decoded.
resource	object	Object which stores resource value's type.

Example

const buffer = Buffer.from([0x01]);
const resource = {
  type: TLV.RESOURCE_TYPE.INTEGER,
};

const decodedValue = decodeResourceValue(buffer, resource);
// decodedValue = 1

encode(object) ⇒ object

编码 ant 类型的实例（对象实例，多个资源，资源实例, 资源）。

种类：全局函数
返回：object - 缓冲区 - 编码的 TLV 缓冲区。

Param	Type	Description
object	object	object which stores type, identifier and value.

示例

const resource = {
  identifier: 5850,
  type: TLV.RESOURCE_TYPE.BOOLEAN,
  value: true
};

const encoded = encode({
  type: TYPE.RESOURCE,
  identifier: resource.identifier,
  value: encodeResourceValue(resource),
});
// encoded = <Buffer e1 16 da 01>

encodeResourceInstance(resourceInstance) ⇒ object

将资源实例编码到 TLV 缓冲区。

种类：全局函数
返回：object - buffer - TLV 格式的缓冲区

Param	Type	Description
resourceInstance	object	Object which stores resource identifier, value and it's type.

Example

const resourceInstance = {
  identifier: 5850,
  type: TLV.RESOURCE_TYPE.BOOLEAN,
  value: true
};

const encoded = encodeResourceInstance(resourceInstance);
// encoded = <Buffer e1 16 da 01>

encodeMultipleResourcesTLV(resources) ⇒ object

将多个资源值编码为 TLV缓冲。

种类：全局函数
返回：对象 - 缓冲区 - TLV 缓冲区。

Param	Type	Description
resources	object	Object which stores identifier, resource type, and multiple values.

示例

const resources = {
  identifier: 5850,
  type: TLV.RESOURCE_TYPE.BOOLEAN,
  value: [true, false]
};

const encoded = encodeMultipleResources(resources);
// encoded = <Buffer a6 16 da 41 00 01 41 01 00>

encodeResource(resource) ⇒ object

将资源编码到 TLV 缓冲区。

种类：全局函数
返回：对象 - 缓冲区 - TLV 缓冲区。

Param	Type	Description
resource	object	Object which stores resource identifier, type and value.

示例

const resource = {
  identifier: 5850,
  type: TLV.RESOURCE_TYPE.BOOLEAN,
  value: true
};

const encoded = encodeResourcez(resource);
// encoded = <Buffer e1 16 da 01>

encodeObjectInstance(objectInstance) ⇒ object

将 LwM2M 对象实例编码到 TLV 缓冲区。

种类：全局函数
返回：对象 - 缓冲区 - TLV 缓冲区。

Param	Type	Description
objectInstance	object	LwM2M object.

示例

const objectInstance = {
  identifier: 0,
  resources: [
    {
      identifier: 5815,
      type: TLV.RESOURCE_TYPE.FLOAT,
      value: 999.99
    }
  ]
};

const encoded = encodeObjectInstanceTLV(objectInstance);
// encoded = <Buffer 07 00 e4 16 b7 44 79 ff 5c>

encodeObject(object) ⇒ object

将 LwM2M 对象编码到 TLV 缓冲区。

种类：全局函数
返回：对象 - 缓冲区 - TLV 缓冲区。

Param	Type	Description
object	object	LwM2M object.

示例

const object = {
  identifier: 3305,
  objectInstances: [{
    identifier: 0,
    resources: [
      {
        identifier: 5815,
        type: TLV.RESOURCE_TYPE.FLOAT,
        value: 999.99
      }
    ]
  }]
};

const encoded = encodeObject(object);
// encoded = <Buffer 07 00 e4 16 b7 44 79 ff 5c>

decode(buffer) ⇒ object

解码任何 TLV 缓冲区。

种类：全局函数
返回：object - object - 解码后的对象。

Param	Type	Description
buffer	object	encoded TLV buffer.

示例

const buffer = Buffer.from([0xe1, 0x16, 0xda, 0x01]);

const decoded = TLV.decode(buffer);
// decoded = { type: 3, identifier: 5850, value: <Buffer 01>, tlvSize: 4 }

decodeResourceInstance(buffer, resources) ⇒ object

解码资源实例。

种类：全局函数
返回：object - decodedResource - 存储资源标识符的对象， tlvSize 资源类型和值。

Param	Type	Description
buffer	object	Resource instance TLV buffer.
resources	object	Object which stores resource identifier and resource type.

示例

const buffer = Buffer.from([0x61, 0x16, 0xda, 0x01]);
const resources = {
  identifier: 5850,
  type: TLV.RESOURCE_TYPE.BOOLEAN,
};

const decoded = decodeResourceInstance(buffer, resources);
// decoded = { identifier: 5850, tlvSize: 4, type: TLV.RESOURCE_TYPE.BOOLEAN, value: true }

decodeResourceInstanceValue(buffer, resourceInstance) ⇒ object

解码资源实例值

种类：全局函数
返回：object - decodedResourceValue - 解码后的资源值

Param	Type	Description
buffer	object	Resource instance value TLV buffer
resourceInstance	object	Object which stores resource type

Example

const buffer = Buffer.from([0x01]);
const resourceInstance = {
  type: TLV.RESOURCE_TYPE.INTEGER,
};

const decoded = decodeResourceInstance(buffer, resources);
// decoded = 1

decodeResource(buffer, resource) ⇒ object

解码资源。

种类：全局函数
返回：object - 缓冲区 - 解码后的资源。

Param	Type	Description
buffer	object	Resource TLV buffer
resource	object	Object which stores identifier and resource type.

示例

const buffer = Buffer.from([0xe1, 0x16, 0xda, 0x01]);
const resource = {
  identifier: 5850,
  type: TLV.RESOURCE_TYPE.BOOLEAN,
};

const decoded = decodeResource(buffer, resource);
// decoded = { identifier: 5850, type: 1, value: true, tlvSize: 4 }

decodeObjectInstance(buffer, objectInstance) ⇒ object

从 TLV 缓冲区解码对象实例。

种类：全局函数
返回：object - object - 解码后的对象实例。

Param	Type	Description
buffer	object	TLV buffer.
objectInstance	object	Object which stores object instance identifier and resources.

示例

const buffer = Buffer.from([0x07, 0x00, 0xe4, 0x16, 0xb7, 0x44, 0x79, 0xff, 0x5c]);
const objectInstance: {
  identifier: 0,
  resources: [
    {
      identifier: 5815,
      type: TLV.RESOURCE_TYPE.FLOAT,
    },
  ]
};

const decoded = decodeObjectInstance(buffer, objectInstance);
// decoded = { identifier: 0, resources: [ { identifier: 5815, type: 3 } ] }

decodeObject(buffer, object) ⇒ object

将 LwM2M 对象解码到 TLV 缓冲区。

种类：全局函数
返回：object - object - 解码后的对象。

Param	Type	Description
buffer	object	TLV buffer.
object	object	Object which stores object instances with their resources.

例子

const buffer = Buffer.from([0x07, 0x00, 0xe4, 0x16, 0xb7, 0x44, 0x79, 0xff, 0x5c]);
const object = {
  identifier: 3305,
  objectInstances: [{
    identifier: 0,
    resources: [
      {
        identifier: 5815,
        type: TLV.RESOURCE_TYPE.FLOAT,
      },
    ]
  }]
};

const decoded = decodeObject(buffer, object);
/*
decoded = {
  identifier: 3305,
  objectInstances: [
    {
      identifier: 0,
      resources: [
        {
          identifier: 5815,
          type: 3,
          value: 999.989990234375,
          tlvSize: 7
        }
      ]
    }
  ]
}
*/