Web of Things（WoT）脚本 API

摘要

万维物联网由实体（物）组成，这些实体可以在机器可解释的物描述（TD）中描述其能力，并通过 WoT 接口公开这些能力，也就是建模为属性（用于读取和写入值）、动作（用于执行带有或不带返回值的远程过程）和事件（用于发出通知信号）的网络交互。

主要的万维物联网（WoT）概念在 Web of Things（WoT）架构 1.1 规范中描述。

脚本编写是 WoT 中一个可选的构建块，它通常用于能够运行 WoT 运行时和脚本管理的网关或浏览器中，提供一种便捷方式来将 WoT 支持扩展到新类型的端点，并实现诸如 TD 目录之类的 WoT 应用。

本规范描述一个应用程序编程接口（API），该接口表示 WoT 接口，允许脚本发现、操作物，并公开由脚本指定的物，这些本地定义的物以 WoT 交互为特征。

本文档中定义的 API 有意紧密遵循 Web of Things（WoT）物描述 1.1 规范。可以在它们之上实现更抽象的 API，或直接实现面向 WoT 网络的接口（即 WoT 接口）。

编辑注

本规范至少已由 Eclipse Thingweb 项目实现，该项目也称为 node-wot，目前被视为参考开源实现。请查看其源代码，包括示例。

将 WoT API 对象定义为单例，并包含按一致性类别分组的 API 方法。

WebIDL[SecureContext, Exposed=(Window,Worker)]
namespace WOT {
  // methods defined in UA conformance classes
};

WebIDLpartial namespace WOT {
  Promise<ConsumedThing> consume(ThingDescription td);
};

属于 WoT Consumer 一致性类别。期望一个 td 实参，并返回一个


        Promise

，该 Promise 会以一个 ConsumedThing 对象兑现，该对象表示用于操作物的客户端接口。该方法 MUST 运行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise，并停止。
令 thing 为一个从 td 构造的新 ConsumedThing 对象。
基于对 td 的内省，按照 [WOT-TD] 和 [WOT-PROTOCOL-BINDINGS] 中的说明设置 WoT 交互。向底层平台发出请求，以初始化协议绑定。

编辑注

实现会封装如何使用协议绑定来实现 WoT 交互的复杂性。未来，其中一些元素可以被标准化。
用 thing 兑现 promise。

编辑注

请注意构造 ConsumedThing 与使用 consume() 方法之间的区别：后者还会初始化协议绑定，而简单构造的对象在其被调用之前，不会初始化 WoT 交互。

WebIDLtypedef object ExposedThingInit;

partial namespace WOT {
  Promise<ExposedThing> produce(ExposedThingInit init);
};

属于 WoT Producer 一致性类别。期望一个 init 实参，并返回一个


        Promise

，该 Promise 会以一个 ExposedThing 对象兑现，该对象通过服务器接口扩展 ConsumedThing，即定义请求处理器的能力。init 对象是 ExposedThingInit 类型的一个实例。具体而言，一个 ExposedThingInit 值是用于初始化 ExposedThing 的字典，并且它表示一个 [WOT-ARCHITECTURE] 中描述的 Partial TD。因此，它具有与物描述相同的结构，但可以省略一些信息。该方法 MUST 运行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise，并停止。
令 thing 为一个使用 init 构造的新 ExposedThing 对象。
用 thing 兑现 promise。

要在给定 init 并以有效的 td 作为结果的情况下展开 ExposedThingInit，运行以下步骤：

在 init 上运行 validate an ExposedThingInit。如果失败，则抛出 SyntaxError 并停止。
令 td 为给定 init 运行 clone 的结果。
对于 td.["securityDefinitions"] 中的每个 scheme，向底层平台发出请求，检查它是否至少受一个协议绑定支持。如果不支持，则从 td 中移除 scheme。
如果 td.["security"] 在 td.["securityDefinitions"] 中不存在，则从 td 中移除 security。
对于 td.properties、td.actions 和 td.events 中的每个 affordance，运行以下子步骤：
1. 对于 affordance.forms 中的每个 form：
  1. 如果运行时未将 form.contentType 识别为有效，则从 form 中移除 contentType。
  2. 如果 form.href 具有未知 scheme，则从 form 中移除 href。
  3. 如果 form.href 是绝对的，并且运行时未将其 authority 识别为有效，则从 form 中移除 href。
  4. 如果 form.href 已被其他 ExposedThings 使用，则从 form 中移除 href。
按照 TD JSON Schema 在 td 中搜索缺失的必需属性。

编辑注

编辑认为此步骤含糊。它将在下一次迭代中得到改进或移除。
对于每个 missing 属性，运行这些子步骤：
1. 如果 missing 是 title，生成一个运行时唯一名称并赋给 title。
2. 如果 missing 是 @context，分配最新受支持的 Thing Description 上下文 URI。
3. 如果 missing 是 instance，分配字符串 1.0.0。
4. 如果 missing 是 forms，使用可用的协议绑定和内容类型编码器生成一个 Forms 列表。然后将所得列表赋给 forms。
5. 如果 missing 是 security，分配 securityDefinitions 字段中第一个受支持的 SecurityScheme 的标签。如果未找到 SecurityScheme，则生成一个名为 nosec 的 NoSecurityScheme，并将字符串 nosec 赋给 security。
  
  Issue 1
  
  关于如何适当地为 security 生成值的讨论仍处于开放状态。参见 issue #299
6. 如果 missing 是 href，则将 formStub 定义为不具有 href 的部分 Form。使用第一个满足 formStub 要求的协议绑定生成一个有效的 url。将 url 赋给 href。如果找不到协议绑定，则从 td 中移除 formStub。
7. 将 missing 添加到 td，并以 value 作为值
在 td 上运行 validate a TD。如果失败，则重新抛出该错误并停止
返回 td

要在给定 init 的情况下验证 ExposedThingInit，运行以下步骤：

解析 TD JSON Schema，并将其加载到名为 exposedThingInitSchema 的对象中
令 optional 为一个列表，其中包含以下字符串：title、 @context、instance、 forms、security 和 href。
对于 exposedThingInitSchema 中等于 required 的每个属性和子属性 key，执行以下步骤：
1. 如果 key 的 value 是一个 Array，则移除其中所有等于 optional 中元素的元素
2. 如果 key 的 value 是一个 string，则如果 value 等于 optional 中的某个元素，则从 exposedThingInitSchema 中移除 key
返回给定 init 和 exposedThingInitSchema 运行 validating an object with JSON Schema 的结果。

编辑注

validating an object with JSON Schema 步骤仍在讨论中。目前，本规范引用 JSONSchema 的验证过程。在用 exposedThingInitSchema 验证 init 时，请遵循此文档。请注意，工作组正在评估另一种形式化方法。

WebIDLpartial namespace WOT {
  Promise<ThingDiscoveryProcess> discover(optional ThingFilter filter = {});
};

属于 WoT Discovery 一致性类别。启动发现过程，该过程将提供与类型为 ThingFilter 的可选 filter 实参匹配的物描述的 ThingDescription 对象。该方法 MUST 运行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise，并停止。
如果实现不支持发现，则用 NotSupportedError 拒绝 promise，并停止。
令 discovery 为一个新的 ThingDiscoveryProcess 对象。
将 discovery.[[filter]] 设置为 filter。
将 discovery.[[url]] 设置为 undefined。
如果实现通常不支持过滤器，并且 filter 不是 undefined 或 null，则用 NotSupportedError 拒绝 promise，并停止。
如果底层平台无法启动发现，则用 OperationError 拒绝 promise，并停止。
请求底层平台通过 WoT 运行时中任何受支持并已预配、且脚本有权访问的方式来启动发现过程，并将 discovery 传递给它。
用 discovery 兑现 promise。

WebIDLpartial namespace WOT {
  Promise<ThingDiscoveryProcess> exploreDirectory(USVString url,
      optional ThingFilter filter = {});
};

属于 WoT Discovery 一致性类别。启动发现过程，该过程在给定 TD 目录 URL 时，将提供与类型为 ThingFilter 的可选 filter 实参匹配的物描述的 ThingDescription 对象。该方法 MUST 运行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise，并停止。
如果实现不支持目录发现，则用 NotSupportedError 拒绝 promise，并停止。
令 discovery 为一个新的 ThingDiscoveryProcess 对象。
将 discovery.[[url]] 设置为 url。
将 discovery.[[filter]] 设置为 filter。
请求底层平台启动目录发现过程。

注

这是发现算法中更多细节的占位符。实现应遵循 [WOT-DISCOVERY] 和 [WOT-PROTOCOL-BINDINGS] 规范中描述的过程。下面指出了一些规范性步骤。
1. 如果 url 不是一个 TD 目录，或底层实现无法支持 url 指示的协议绑定，则用 NotSupportedError 拒绝 promise，并终止这些步骤。
2. 如果实现通常不支持过滤器，并且 filter 不是 undefined 或 null，则用 NotSupportedError 拒绝 promise，并停止。
3. 给定 discovery，运行发现过程。
  
  注
  
  从此时起，错误只记录在 error 上，但不再影响 promise。
用 discovery 兑现 promise。

WebIDLpartial namespace WOT {
  Promise<ThingDescription> requestThingDescription(USVString url);
};

属于 WoT Discovery 一致性类别。从给定 URL 请求一个物描述。该方法 MUST 运行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise，并停止。
如果实现不支持获取物描述，则用 NotSupportedError 拒绝 promise，并停止。
令 td 为向底层平台发出请求，使用 url 指定的协议绑定检索物描述的结果。如果检索 td 失败，则用 NotFoundError 拒绝 promise，并停止。
用 td 兑现 promise。

如 Web of Things（WoT）物描述 1.1 规范所指定，WoT 交互扩展 DataSchema，并包含若干可能的表单，其中一个会被选作该交互使用。表单包含一个 contentType，用于描述数据。对于某些内容类型，会定义一个基于 JSON Schema 的 DataSchema，从而可以将这些内容表示为 JavaScript 类型，并最终在数据上设置范围约束。

WebIDLtypedef any DataSchemaValue;
typedef (ReadableStream or DataSchemaValue) InteractionInput;

属于 WoT Consumer 一致性类别，并表示由应用脚本提供给 UA 的 WoT 交互数据。

DataSchemaValue 是一个 ECMAScript 值，可被 [WoT-TD] 中定义的 DataSchema接受。可能的值 MUST 属于 null、 boolean、 number、 string、array 或 object 类型。

ReadableStream 旨在用于那些在物描述中没有 DataSchema，而只有可以由流表示的Form 的 contentType 的 WoT 交互。

实践中，任何 ECMAScript 值都可用于那些在物描述中定义了 DataSchema 的 WoT 交互，或用于那些可由实现映射到物描述中定义的 Form 的 contentType 的交互。

本文档中的算法指定了输入数据在 WoT 交互中到底如何使用。

属于 WoT Consumer 一致性类别。InteractionOutput 对象始终由实现创建，并将从 WoT 交互返回的数据公开给应用脚本。

此接口公开一个便利函数，该函数应覆盖绝大多数 IoT 用例：value() 函数。其实现会检查数据；如果数据符合 DataSchema，则解析它；否则会尽早失败，让底层流保持未受扰动，以便应用脚本可以尝试自行读取该流，或将数据作为 ArrayBuffer 处理。

WebIDL[SecureContext, Exposed=(Window,Worker)]
interface InteractionOutput {
  readonly attribute ReadableStream? data;
  readonly attribute boolean dataUsed;
  readonly attribute Form? form;
  readonly attribute DataSchema? schema;
  Promise<ArrayBuffer> arrayBuffer();
  Promise<DataSchemaValue> value();
};

data 属性表示 WoT 交互中的原始载荷，其形式为 ReadableStream，初始为 null。

dataUsed 属性说明数据流是否已被扰动。初始为 false。

form 属性表示从物描述中为此 WoT 交互选择的表单，初始为 null。

schema 属性表示载荷的 DataSchema（定义于 [WoT-TD]），其形式为一个 JSON 对象，初始为 null。

[[value]] 内部槽表示 WoT 交互的已解析值，初始为 undefined（注意 null 是有效值）。

解析由 WoT 交互返回的数据，并返回一个具有交互 DataSchema（如果存在）所描述类型的值，或具有交互表单的 contentType 所描述类型的值。该方法 MUST 运行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果 this.[[value]] 不是 undefined，则以该值兑现 promise 并停止。
如果 this.data 不是 ReadableStream，或 dataUsed 为 true，或 form 不是 object，或 schema 或其 type 为 null 或 undefined，则用 NotReadableError 拒绝 promise 并停止。
如果 form.contentType 不是 application/json，并且协议绑定中没有可用的映射可将 form.contentType 映射到 [JSON-SCHEMA]，则用 NotSupportedError 拒绝 promise 并停止。
令 reader 为从 data 获取 reader的结果。如果这抛出异常，则用该异常拒绝 promise 并停止。
令 bytes 为使用 reader 从 data 读取所有字节的结果。
将 dataUsed 设置为 true。
如果 form.contentType 不是 application/json，并且协议绑定中存在可用映射，可将 form.contentType 映射到 [JSON-SCHEMA]，则使用该映射转换 bytes。
令 json 为在 bytes 上运行 parse JSON from bytes 的结果。如果这抛出异常，则用该异常拒绝 promise 并停止。
将 [[value]] 设置为在 json 和 schema 上运行 check data schema 的结果。如果这抛出异常，则用该异常拒绝 promise 并停止。
用 [[value]] 兑现 promise。

调用时，MUST 运行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果 data 不是 ReadableStream，或 dataUsed 为 true，则用 NotReadableError 拒绝 promise 并停止。
令 reader 为从 data 获取 reader的结果。如果这抛出异常，则用该异常拒绝 promise 并停止。
令 bytes 为使用 reader 从 data 读取所有字节的结果。
将 dataUsed 设置为 true。
令 arrayBuffer 为一个新的 ArrayBuffer，其内容为 bytes。如果这抛出异常，则用该异常拒绝 promise 并停止。
用 arrayBuffer 兑现 promise。

要在 payload 和 schema 上运行 check data schema 步骤，

令 type 为 schema.type。
如果 type 为 "null"，并且 payload 不是 null，则抛出 TypeError 并停止；否则返回 null。
如果 type 为 "boolean"，且 payload 是 falsy 值或其字节长度为 0，则返回 false；否则返回 true。
如果 type 为 "integer" 或 "number"，
1. 如果 payload 不是数字，则抛出 TypeError 并停止。
2. 如果 form.minimum 已定义且 payload 更小，或 form.maximum 已定义且 payload 更大，则抛出 RangeError 并停止。
如果 type 为 "string"，则返回 payload。
如果 type 为 "array"，则运行这些子步骤：
1. 如果 payload 不是数组，则抛出 TypeError 并停止。
2. 如果 form.minItems 已定义且 payload.length 小于该值，或 form.maxItems 已定义且 payload.length 大于该值，则抛出 RangeError 并停止。
3. 令 payload 为一个由以下方式获得的项数组：对 payload 的每个元素 item 和 schema.items 运行 check data schema 步骤。如果这在任何阶段抛出异常，则重新抛出该异常并停止。
如果 type 为 "object"，则运行这些子步骤：
1. 如果 payload 或 schema.properties 不是 object，则抛出 TypeError 并停止。
2. 对于 payload 中的每个 key：
  1. 令 prop 为 payload[key]。
  2. 令 propSchema 为 interaction.properties[key]。
  3. 令 prop 为在 prop 和 propSchema 上运行 check data schema 步骤的结果。如果这抛出异常，则重新抛出该异常并停止。
3. 如果 schema.required 是数组，则令 required 为该数组；否则令其为空数组。
4. 对于 required 中的每个 key，如果 key 未出现在 payload 中，则抛出 SyntaxError 并停止。
返回 payload。

对于给定的 ConsumedThing 对象 thing，为在给定 source、form 和 schema 的情况下创建交互请求，运行这些步骤：

令 idata 为一个新的 InteractionOutput 对象。
将 idata.form 设置为 form，将 idata.schema 设置为 schema，将 |idata.data 设置为 null，并将 idata.[[value]] 设置为 undefined。
如果 source 是一个 ReadableStream 对象，则令 idata.data 为 source，返回 idata 并停止。
如果 schema 及其 type 已定义且不为 null，则运行这些子步骤：
1. 如果 type 为 "null"，并且 source 不是 "null"，则抛出 TypeError 并停止。
2. 如果 type 为 "boolean"，并且 source 是 falsy 值，则将 idata.[[value]] 设置为 false；否则将其设置为 true。
3. 如果 type 为 "integer" 或 "number"，且 source 不是数字，或 form.minimum 已定义且 source 更小，或 form.maximum 已定义且 source 更大，则抛出 RangeError 并停止。
4. 如果 type 为 "string"，且 source 不是字符串，则令 idata.[[value]] 为给定 source 运行 serialize JSON to bytes 的结果。如果该结果为 failure，则抛出 SyntaxError 并停止。
5. 如果 type 为 "array"，则运行这些子步骤：
  1. 如果 source 不是数组，则抛出一个 TypeError 并停止。
  2. 令 length 为 source 的长度。
  3. 如果 form.minItems 已定义且 length 小于该值，或 form.maxItems 已定义且 length 大于该值，则抛出 RangeError 并停止。
  4. 对于 source 中的每个 item，令 itemschema 为 schema.items，并令 item 为给定 item、form 和 itemschema 运行 create interaction request 步骤的结果。如果这抛出异常，则重新抛出该异常并停止。
  5. 将 data.[[value]] 设置为 source。
6. 如果 type 为 "object"，则运行这些子步骤：
  1. 如果 source 不是对象，则抛出 TypeError 并停止。
  2. 如果 schema.properties 不是对象，则抛出 TypeError 并停止。
  3. 对于 source 中的每个 key，
    1. 令 value 为 source[key]。
    2. 令 propschema 为 properties.interactions[key]。
    3. 令 value 为在 value、form 和 propschema 上运行 create interaction request 步骤的结果。如果这抛出异常，则重新抛出该异常并停止。
  4. 如果 schema.required 是数组，则对于 required 中的每个 item，检查 item 是否是 source 中的属性名。如果在 source 中未找到某个 item，则抛出 SyntaxError 并停止。
  5. 将 data.[[value]] 设置为 source。
将 idata.data 设置为一个新的 ReadableStream，该流由 idata.[[value]] 内部槽创建，并将其作为该流的底层源。
返回 idata。

对于给定的 ConsumedThing 对象 thing，为在给定 response、 form 和 schema 的情况下解析交互响应，运行这些步骤：

令 result 为一个新的 InteractionOutput 对象。
令 result.schema 为 schema。
令 result.form 为 form。
令 result.data 为一个新的 ReadableStream，其中 response 的载荷数据作为其底层源。
令 result.dataUsed 为 false。
返回 result。

如下图所示，每当实现向脚本提供数据时，都会使用 InteractionOutput 接口；而当脚本向实现传递数据时，使用 InteractionInput。

当 ConsumedThing 读取数据时，它会从实现接收一个 InteractionOutput 对象。

ExposedThing 读取处理器以 InteractionInput 的形式向实现提供读取数据。

当 ConsumedThing 写入数据时，它会以 InteractionInput 的形式将数据提供给实现。

ExposedThing 写入处理器会从实现接收一个 InteractionOutput 对象作为数据。

当 ConsumedThing 调用一个动作时，它会以 InteractionInput 的形式提供参数，并以 InteractionOutput 对象的形式接收该动作的输出。

ExposedThing 动作处理器以 InteractionOutput 对象的形式从实现接收实参，并以 InteractionInput 的形式向实现提供动作输出。

此 API 中的算法定义了要报告给应用脚本的错误。

报告给另一通信端的错误由协议绑定进行映射和封装。

编辑注

此主题仍在 Issue #200 中讨论。为了确保将脚本错误映射到协议错误以及反向映射的一致性，需要一个标准化的错误映射。尤其是，当算法提到“从协议绑定收到的错误”时，这将被分解为一个显式的错误映射算法。目前，它由实现封装。

表示用于操作一个物的客户端 API。属于 WoT Consumer 一致性类别。

WebIDL[SecureContext, Exposed=(Window,Worker)]
interface ConsumedThing {
  constructor(ThingDescription td);
  Promise<InteractionOutput> readProperty(DOMString propertyName,
                              optional InteractionOptions options = {});
  Promise<PropertyReadMap> readAllProperties(
                              optional InteractionOptions options = {});
  Promise<PropertyReadMap> readMultipleProperties(
                              sequence<DOMString> propertyNames,
                              optional InteractionOptions options = {});
  Promise<undefined> writeProperty(DOMString propertyName,
                              InteractionInput value,
                              optional InteractionOptions options = {});
  Promise<undefined> writeMultipleProperties(
                              PropertyWriteMap valueMap,
                              optional InteractionOptions options = {});
  /*Promise<undefined> writeAllProperties(
                              PropertyWriteMap valueMap,
                              optional InteractionOptions options = {});*/
  Promise<InteractionOutput> invokeAction(DOMString actionName,
                              optional InteractionInput params = {},
                              optional InteractionOptions options = {});
  Promise<Subscription> observeProperty(DOMString name,
                              InteractionListener listener,
                              optional ErrorListener onerror,
                              optional InteractionOptions options = {});
  Promise<Subscription> subscribeEvent(DOMString name,
                              InteractionListener listener,
                              optional ErrorListener onerror,
                              optional InteractionOptions options = {});
  ThingDescription getThingDescription();
};

dictionary InteractionOptions {
  unsigned long formIndex;
  object uriVariables;
  any data;
};

[SecureContext, Exposed=(Window,Worker)]
interface Subscription {
  readonly attribute boolean active;
  Promise<undefined> stop(optional InteractionOptions options = {});
};

[SecureContext, Exposed=(Window,Worker)]
interface PropertyReadMap {
  readonly maplike<DOMString, InteractionOutput>;
};

[SecureContext, Exposed=(Window,Worker)]
interface PropertyWriteMap {
  readonly maplike<DOMString, InteractionInput>;
};

callback InteractionListener = undefined(InteractionOutput data);
callback ErrorListener = undefined(Error error);

编辑注：writeAllProperties 方法在哪里？

writeAllProperties() 方法仍在讨论中。与此同时，请改用 writeMultipleProperties() 方法。

ConsumedThing 对象具有以下内部槽：

内部槽	初始值	描述（非规范性）
[[td]]	`null`	`ConsumedThing` 的物描述。
[[activeSubscriptions]]	`{}`	一个有序映射，其键为表示事件的字符串名称，而值是一个`Subscription` 对象。
[[activeObservations]]	`{}`	一个有序映射，其键为表示某个属性的字符串名称，而值是一个`Subscription` 对象。

在以 JSON 对象形式获取一个物描述之后，可以创建一个 ConsumedThing 对象。

要使用 ThingDescription td 创建 ConsumedThing，运行以下步骤：

在 td 上运行 validate a TD 步骤。如果失败，则抛出 SyntaxError 并停止。
在 td 上运行 expand a TD 步骤。如果失败，则重新抛出该错误并停止。
令 thing 为一个新的 ConsumedThing 对象。
将 thing 的内部槽 [[td]] 设置为 td。
返回 thing。

返回 ConsumedThing 对象的 [[td]]，该对象表示 ConsumedThing 的物描述。应用可以查询存储在 [[td]] 中的物元数据，以便在与其交互之前内省其能力。

读取一个属性值。接受 propertyName 以及可选的 options 作为实参。它返回一个


        Promise

，该 Promise 会以一个 InteractionOutput 对象形式表示的属性值兑现，或在错误时拒绝。该方法 MUST 运行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise 并停止。
令 interaction 为 [[td]].properties.propertyName。
如果 interaction 为 undefined，则用 NotFoundError 拒绝 promise 并停止。
如果 option.formIndex 已定义，则令 form 为 interaction.forms 数组中与 formIndex 关联的表单；否则，令 form 为 interaction.forms 中一个 op 为 readproperty 的表单，由实现选择。
如果 form 是 failure，则用 SyntaxError 拒绝 promise 并停止。
向底层平台发出请求（通过协议绑定），使用 form 以及 options.uriVariables 中给定的可选 URI 模板，检索 propertyName 属性的值。
如果请求失败，则用从协议绑定收到的错误拒绝 promise 并停止。
令 response 为该请求收到的响应。
令 data 为在 response、 form 和 interaction 上运行 parse interaction response 的结果。如果这失败，则用 SyntaxError 拒绝 promise 并停止。
用 data 兑现 promise。

用一个请求读取多个属性值。接受 propertyNames 以及可选的 options 作为实参。它返回一个


        Promise

，该 Promise 会以一个 PropertyReadMap 对象兑现，该对象将 propertyNames 中的键映射到由此算法返回的值。该方法 MUST 运行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise 并停止。
如果 option.formIndex 已定义，则令 form 为 [[td]].forms 数组中与 formIndex 关联的表单；否则，令 form 为 [[td]].forms 数组中 op 为 readmultipleproperties 的表单，由实现选择。
如果 form 是 failure，则用 SyntaxError 拒绝 promise 并停止。
令 result 为一个对象，并且对于 propertyNames 中的每个字符串 name，添加一个键为 name 且值为 null 的属性。
向底层平台发出请求（通过协议绑定），使用 form 以及 options 的 uriVariables 中给定的可选 URI 模板，检索 propertyNames 给定的属性值。
如果无法用协议绑定通过单个请求完成此操作，则用 NotSupportedError 拒绝 promise 并停止。
处理响应，并且对于 result 中的每个 key，运行以下子步骤：
1. 令 value 为 result[key]。
2. 令 schema 为 this.[[td]].properties[key]。
3. 令 property 为在 value、 form 和 schema 上运行 parse interaction response 的结果。
如果上述步骤在任何时刻抛出异常，则用该异常拒绝 promise 并停止。
用 result 兑现 promise。

用一个请求读取物的所有属性。接受 options 作为可选实参。它返回一个


        Promise

，该 Promise 会以一个 PropertyReadMap 对象兑现，该对象将属性名称中的键映射到由此算法返回的值。该方法 MUST 运行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise 并停止。
令 forms 为 subscription.[[interaction]].forms。
如果 forms 为 undefined，则用 SyntaxError 拒绝 promise 并停止。
如果 option.formIndex 不是 undefined 且小于 forms.length，则将 subscription.[[form]] 设置为 forms.[formIndex]。
否则，将 subscription.[[form]] 设置为 forms 中一个 op 为 "readallproperties" 的表单，由实现选择。
如果 subscription.[[form]] 是 failure，则用 SyntaxError 拒绝 promise 并停止。
使用协议绑定向底层平台发出请求，在给定 form 以及 options.uriVariables 中可选 URI 模板的情况下，从 TD 检索所有属性定义。
如果无法使用该物的协议绑定通过单个请求完成此操作，则用 NotSupportedError 拒绝 promise 并停止。
如果请求失败，则用从协议绑定收到的错误拒绝 promise 并停止。
处理回复，并令 result 为一个具有从回复中获得的键和值的对象。
处理响应，并且对于 result 中的每个 key，运行以下子步骤：
1. 令 value 为 result[key]。
2. 令 schema 为 this.[[td]].properties[key]。
3. 令 property 为在 value、 form 和 schema 上运行 parse interaction response 的结果。
用 result 兑现 promise。

写入单个属性。接受 propertyName、 value 以及可选的 options 作为实参。它返回一个


        Promise

，该 Promise 在成功时兑现，并在失败时拒绝。该方法 MUST 运行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise 并停止。
令 interaction 为 this.[[td]].properties[propertyName]。
如果 interaction 为 undefined，则用 NotFoundError 拒绝 promise 并停止。
如果 option.formIndex 不是 undefined，则令 form 为 interaction.forms 数组中与 formIndex 关联的表单；否则，令 form 为 interaction.forms 中一个 op 为 writeproperty 的表单，由实现选择。
如果 form 是 failure，则用 SyntaxError 拒绝 promise 并停止。
令 data 为给定 value、 form 和 interaction 运行 create interaction request 步骤的结果。如果这抛出异常，则用该异常拒绝 promise 并停止。
向底层平台发出请求（通过协议绑定），使用 data 以及 options 的 uriVariables 中给定的可选 URI 模板，写入由 propertyName 给定的属性。
如果请求失败，则用从协议绑定收到的错误拒绝 promise 并停止。
否则兑现 promise。

编辑注

如 Issue #193 中所讨论，设计决定是写入交互只返回成功或错误，而不返回写入的值（可选）。TD 应捕获属性值的模式，包括精度和替代格式。当交互预期有返回值时，应使用动作而不是属性。

用一个请求写入多个属性值。接受 properties 作为实参——它是一个对象，其中键为属性名称，值为属性值——并可选接受 options。它返回一个


        Promise

，该 Promise 在成功时兑现，并在失败时拒绝。该方法 MUST 运行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise 并停止。
如果 option.formIndex 已定义，则令 form 为 [[td]].forms 数组中与 formIndex 关联的表单；否则，令 form 为 [[td]].forms 数组中 op 为 writemultipleproperties 的表单，由实现选择。
如果 form 是 failure，则用 SyntaxError 拒绝 promise 并停止。
令 propertyNames 为一个 string 数组，其元素为 properties 对象的键。
对于 propertyNames 中的每个 name，令 property 为 this.[[td]].properties[name]。
如果 property 为 null 或 undefined，或者不是 writeable，则用 NotSupportedError 拒绝 promise 并停止。
令 result 为一个对象，并且对于 propertyNames 中的每个字符串 name，添加一个键为 name 的属性，并令其值为 null。
令 schemas 为一个对象，并且对于 propertyNames 中的每个 name，添加一个键为 name 的属性，并令其值为 this.[[td]].properties[name]。
对于 properties 中的每个键 key，给定 properties[key]、form 和 schema[key] 的值，运行 create interaction request 步骤。如果这对任何 name 抛出异常，则用该异常拒绝 promise 并停止。
向底层平台发出单个请求（通过协议绑定），使用 options 的 uriVariables 中给定的可选 URI 模板，写入 properties 中提供的每个属性。
如果无法使用该物的协议绑定通过单个请求完成此操作，则用 NotSupportedError 拒绝 promise 并停止。
如果请求失败，则返回从协议绑定收到的错误并停止。
否则兑现 promise。

发出对属性值变更通知的请求。接受 propertyName、listener 以及可选的 onerror 和 options 作为实参。它返回一个


        Promise

，该 Promise 在成功时兑现，并在失败时拒绝。

编辑注

此算法每个属性只允许一个活动的 Subscription。如果在已有活动 Subscription 时创建新的 Subscription，运行时将抛出 NotAllowedError。

该方法 MUST 运行以下步骤：

令 thing 为此 ConsumedThing 对象的引用。
返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise 并停止。
如果 listener 不是 Function，则用 TypeError 拒绝 promise 并停止。
如果 onerror 不是 null，并且不是 Function，则用 TypeError 拒绝 promise 并停止。
如果 thing.[[activeObservations]][propertyName] [=map/exists]，则用 NotAllowedError 拒绝 promise 并停止。
令 subscription 为一个新的 Subscription 对象，其内部槽设置如下：
- 令 subscription.[[type]] 为 "property"。
- 令 subscription.[[name]] 为 propertyName。
- 令 subscription.[[interaction]] 为 [[td]].properties[propertyName]。
- 令 subscription.[[thing]] 为 thing。
- 令 forms 为 subscription.[[interaction]].forms。
- 如果 forms 为 undefined，则用 SyntaxError 拒绝 promise 并停止。
- 如果 option.formIndex 不是 undefined 且小于 forms.length，则将 subscription.[[form]] 设置为 forms.[formIndex]。
- 否则，将 subscription.[[form]] 设置为 forms 中一个 op 为 "observeproperty" 的表单，由实现选择。
- 如果 subscription.[[form]] 是 failure，则用 SyntaxError 拒绝 promise 并停止。
- 如果 subscription.[[interaction]] 为 undefined，则用 NotFoundError 拒绝 promise 并停止。
向底层平台发出请求，使用 form 以及 options 的 uriVariables 中给定的可选 URI 模板，观察由 propertyName 标识的属性。
如果请求失败，则用从协议绑定收到的错误拒绝 promise 并停止。
将 thing.[[activeObservations]][|propertyName] 设置为 subscription，并兑现 promise。
每当底层平台检测到此 subscription 的通知，并且该通知以 propertyName 为键，带有新的属性值 value 时，运行以下子步骤：
- 令 reply 为使用 value、subscription.[[form]] 和 subscription.[[interaction]] 运行 parse interaction response 的结果。如果这抛出异常，则用该异常拒绝 promise 并停止。
- 用 reply 调用 listener。
每当底层平台检测到此订阅的错误时，运行以下子步骤：
- 如果该错误不可恢复并停止了订阅，则将 subscription.active 设置为 false，并抑制后续通知。
- 令 error 为一个新的 NetworkError，并将其 message 设置为反映底层错误条件的内容。
- 如果 onerror 是一个 Function，则用 error 调用它。

发出调用一个动作并返回结果的请求。接受 actionName、可选的 params 以及可选的 options 作为实参。它返回一个


        Promise

，该 Promise 会以动作的结果兑现，该结果表示为一个 InteractionOutput 对象；或以错误拒绝。该方法 MUST 运行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise 并停止。
令 interaction 为 this.[[td]].actions[actionName]。
如果 interaction 不是一个 object，则用 NotFoundError 拒绝 promise 并停止。
令 forms 为 subscription.[[interaction]].forms。
如果 forms 为 undefined，则用 SyntaxError 拒绝 promise 并停止。
如果 option.formIndex 不是 undefined 且小于 forms.length，则将 subscription.[[form]] 设置为 forms.[formIndex]。
否则，将 subscription.[[form]] 设置为 forms 中一个 op 为 "invokeaction" 的表单，由实现选择。
如果 subscription.[[form]] 是 failure，则用 SyntaxError 拒绝 promise 并停止。
令 args 为在 params、 form 和 interaction 上运行 create interaction request 步骤的结果。如果这抛出异常，则用该异常拒绝 promise 并停止。
向底层平台发出请求（通过协议绑定），在给定 args 和 options.uriVariables 的情况下，调用由 actionName 标识的动作。
如果请求在本地失败或通过网络返回错误，则用从协议绑定收到的错误拒绝 promise 并停止。
令 value 为回复中返回的回复。
令 result 为使用 value、 form 和 interaction 运行 parse interaction response 的结果。如果这抛出异常，则用该异常拒绝 promise 并停止。
用 result 兑现 promise。

发出订阅事件通知的请求。接受 eventName、 listener 以及可选的 onerror 和 options 作为实参。它返回一个


        Promise

来表示成功或失败。

编辑注

此算法每个事件只允许一个活动的 Subscription。如果在已有活动 Subscription 时创建新的 Subscription，运行时将抛出 NotAllowedError。

该方法 MUST 运行以下步骤：

令 thing 为此 ConsumedThing 对象的引用。
返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise 并停止。
如果 listener 不是一个 Function，则用 TypeError 拒绝 promise 并停止。
如果 onerror 不是 null，并且不是 Function，则用 TypeError 拒绝 promise 并停止。
如果 thing.[[activeSubscriptions]][eventName] 不存在，则用 NotAllowedError 拒绝 promise 并停止。
令 subscription 为一个新的 Subscription 对象，其内部槽设置如下：
- 令 subscription.[[type]] 为 "event"。
- 令 subscription.[[name]] 为 eventName。
- 令 subscription.[[interaction]] 为 thing. [[td]].events[eventName]。
- 如果 subscription.[[interaction]] 为 undefined，则用 NotFoundError 拒绝 promise 并停止。
- 令 subscription.[[thing]] 为 thing。
- 如果 options.formIndex 存在，则令 subscription.[[form]] 为 thing.[[interaction]].forms[formIndex]。
- 否则，令 subscription.[[form]] 为 subscription.[[interaction]].forms 数组中一个由实现定义的、op 为 "subscribeevent" 的表单。
- 如果 subscription.[[form]] 不存在，则用 SyntaxError 拒绝 promise 并停止。
通过协议绑定向底层平台发出请求，以使用 [[form]]、options.uriVariables 中给定的可选 URI 模板，以及 options.data 中给定的可选订阅数据，订阅由 eventName 标识的事件。
如果请求失败，则用从协议绑定收到的错误拒绝 promise 并停止。
将 eventName 设置到 thing.[[activeSubscriptions]][eventName] 为 subscription。
兑现 promise。
每当底层平台检测到以 eventName 为键的事件 subscription 通知时，运行以下子步骤：
1. 使用在该事件随附的数据、 subscription.[[form]] 和 subscription.[[interaction]] 运行 parse interaction response 的结果，调用 listener。
每当底层平台检测到以 eventName 为键的事件 subscription 的错误时，运行以下子步骤：
- 如果该错误不可恢复并停止了订阅，则将 subscription.active 设置为 false，并抑制后续通知。
- 令 error 为一个新的 NetworkError，并将其 message 设置为反映底层错误条件的内容。
- 如果 onerror 是一个 Function，则用 error 调用它。

保存根据物描述需要向应用脚本公开的交互选项。

formIndex 属性如果已定义，表示一个应用提示，指出对于给定的 WoT 交互，应使用 TD 中由该索引标识的哪个 Form 定义。实现 SHOULD 使用具有此索引的 Form 来进行交互，但如果未找到该索引或索引无效， MAY 覆盖此值。如果未定义，实现 SHOULD 尝试按照 TD 中列出的出现顺序，使用给定 Wot 交互的 Form 定义。

uriVariables 属性如果已定义，表示要与 WoT 交互一起使用的 URI 模板变量，这些变量表示为 [WOT-TD] 中定义的解析后的 JSON 对象。

编辑注

对 URI 变量的支持源于 Web of Things（WoT）物描述 1.1 规范所揭示的需求，即能够描述使用它们的现有 RESTful 端点。然而，应该可以编写一个物描述，使用动作来表示这类交互，并将 URI 变量建模为动作参数。在这种情况下，实现可以将参数序列化为 URI 变量，因此 options 参数可以被省略。

data 属性如果已定义，表示需要传递给交互的额外不透明数据。

表示从属性名称到 InteractionOutput 对象的映射，该对象表示属性可以取的值。它用作涉及多个属性同时进行的交互的属性包。

表示从属性名称到 InteractionInput 的映射，后者表示属性可以取的值。它用作涉及多个属性同时进行的交互的属性包。

用户提供的回调，会收到一个类型为 InteractionOutput 的实参，用于观察属性变化以及处理事件通知。由于订阅事件是 WoT 交互，并且可能接受选项甚至数据，因此它们不使用软件事件建模。

用户提供的回调，会收到一个类型为 Error 的实参，用于将来自协议绑定的关键和非关键错误传递给应用。

表示对属性变更和事件交互的订阅。

active 布尔属性表示该订阅是否处于活动状态，即它未因错误或因调用 stop() 方法而停止。

Subscription 对象具有以下内部槽：

内部槽	初始值	描述（非规范性）
[[type]]	`null`	指示该 `Subscription` 指向哪个WoT 交互。该值可以是 `"property"`、`"event"` 或 `null`。
[[name]]	`null`	属性或事件名称。
[[interaction]]	`null`	描述该 WoT 交互的物描述片段。
[[form]]	`null`	与订阅关联的表单。
[[thing]]	`null`	与订阅关联的 `ConsumedThing`。

停止传递该订阅的通知。它接受一个可选参数 options，并返回一个 Promise。调用时，该方法 MUST 执行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise 并停止。
如果 options 的 formIndex 已定义，则令 unsubscribeForm 为 [[interaction]] 的 forms 数组中与 formIndex 关联的表单。
否则，令 unsubscribeForm 为给定 [[form]] 运行 find a matching unsubscribe form 算法的结果。
如果 unsubscribeForm 是 failure，则用 SyntaxError 拒绝 promise 并停止。
如果 [[type]] 为 "property"，则通过协议绑定向底层平台发出请求，使用 unsubscribeForm 以及 options 的 uriVariables 中给定的可选 URI 模板，停止观察由 [[name]] 标识的属性。
否则，如果 [[type]] 为 "event"，则通过协议绑定向底层平台发出请求，使用 unsubscribeForm、options 的 uriVariables 中给定的可选 URI 模板，以及 options.data 中给定的可选取消订阅数据，取消订阅由 [[name]] 标识的事件。
如果请求失败，则用从协议绑定收到的错误拒绝 promise 并停止。
否则：
- 将 active 设置为 false。
- 如果 [[type]] 为 "event"，则从 [[thing]].[[activeSubscriptions]] 移除 [[name]] 。
- 如果 [[type]] 为 "property"，则从 [[thing]].[[activeObservations]] 移除 [[name]] 。
- 兑现 promise。
如果底层平台收到该订阅的后续通知，实现 SHOULD 静默抑制它们。

注

此算法正在开发中，并且是 非规范性内容。实现 MAY 选择另一种算法，为给定的 subscribe 表单查找匹配的 unsubscribe 表单。

要在 Subscription 对象的上下文中，给定 subscribeForm 来查找匹配的 unsubscribe 表单，运行以下步骤：

令 results 为一个空数组。
对于 [[interaction]].forms 中的每个 form，
1. 在 form 上添加一个内部槽 [[matchLevel]]，并将其值设置为 0。
2. 如果 [[type]] 为 "property" 且 form.op 为 "unobserveproperty"，或者如果 [[type]] 为"event" 且 form.op 为 "unsubscribeevent"，
  1. 将 form 上的内部槽 [[matchLevel]] 设置为 1，并将 form 添加到 results。
  2. 如果 form.href 和 [[subscribeForm]].href 是同源域，则递增 form.[[matchLevel]]。
  3. 如果 form.contentType 等于 [[subscribeForm]] 的 contentType，并且 form.[[matchLevel]] 大于 2，则递增 form.[[matchLevel]]。
如果 results 为空，则返回 null 并终止这些步骤。
返回 results 中第一个具有最高 [[matchLevel]] 值的 form。

下一个示例展示如何通过 URL 获取 TD，创建 ConsumedThing，读取元数据（title）、读取属性值、订阅属性变更、订阅 WoT 事件以及取消订阅。

示例 2：带数据值的物客户端 API 示例

try {
  let res = await fetch("https://tds.mythings.org/sensor11");
  let td = res.json();
  let thing = new ConsumedThing(td);
  console.log("物 " + thing.getThingDescription().title + " 已被使用。");
} catch (e) {
  console.log("TD 获取错误：" + e.message);
};

try {
  // 订阅 “temperature” 的属性变更
  await thing.observeProperty("temperature", async (data) => {
    try {
      console.log("温度已变为：" + await data.value());
    } catch (error) {
      console.error("无法读取已观察的 temperature 属性");
      console.error(error);
    }
  });
  // 订阅 TD 中定义的 “ready” 事件
  await thing.subscribeEvent("ready", async (eventData) => {
    try {
      console.log("已就绪；索引：" + await eventData.value());
      // 运行 TD 定义的 “startMeasurement” 动作
      await thing.invokeAction("startMeasurement", { units: "Celsius" });
      console.log("测量已开始。");
    } catch (error) {
      console.error("无法读取 ready 事件，或 startMeasurement 失败");
      console.error(error)
    }
  });
} catch (e) {
  console.log("启动测量时出错。");
}

setTimeout(async () => {
  try {
    const temperatureData = await thing.readProperty("temperature")
    const temperature = await temperatureData.value();
    console.log("温度：" + temperature);

    await thing.unsubscribe("ready");
    console.log("已取消订阅 ‘ready’ 事件。");
  } catch (error) {
    console.log("清理函数中出错");
  }
}, 10000);

下面展示了 InteractionOutput 的高级用法，用于读取没有 DataSchema 的属性。

示例 3：带 arrayBuffer 的物客户端 API 示例

/*
* takePicture affordance form:
* "form": {
*   "op": "invokeaction",
*   "href" : "http://camera.example.com:5683/takePicture",
*   "response": {
*     "contentType": "image/jpeg",
*     "contentCoding": "gzip"
*   }
*}
* 参见 https://www.w3.org/TR/wot-thing-description/#example-23
*/
let response;
let image;
try {
  response = await thing.invokeAction(“takePicture”));
  image = await response.value() // 抛出 NotReadableError --> 未定义 schema
} catch(ex) {
  image = await response.arrayBuffer();
  // image: ArrayBuffer [0x1 0x2 0x3 0x5 0x15 0x23 ...]
}

最后，接下来的两个示例展示了如何使用来自 InteractionOutput 的 ReadableStream。

示例 4：带可读流的物客户端 API 示例（例如视频流）

/*{
"video": {
  "description" : "the video stream of this camera",
  "forms": [
    {
      "op": "readproperty",
      "href": "http://camera.example.com/live",
      "subprotocol": "hls"
      "contentType": "video/mp4"
    }
  ]
}}*/

const video = await thing.readProperty("video")
const reader = video.data.getReader()
reader.read().then(function processVideo({ done, value }) {
  if (done) {
    console.log("实时视频已停止");
    return;
  }
  const decoded = decode(value)
  UI.show(decoded)
  // 再读取一些内容，并再次调用此函数
  return reader.read().then(processText);
});

这里假设 JSON 对象太大，无法整体读入内存。因此，我们使用流式处理来获取远程 Web Thing 记录的事件总数。

示例 5：带可读流的物客户端 API 示例（例如统计 json 对象）

/*
* "eventHistory":
* {
*   "description" : "A long list of the events recorded by this thing",
*   "type": "array",
*   "forms": [
*     {
*       "op": "readproperty",
*       "href": "http://recorder.example.com/eventHistory",
*     }
*   ]
* }
*/

// 流式处理示例：统计 json 对象
let objectCounter = 0
const parser = new Parser() // 用于 json 流式解析的用户库（即 https://github.com/uhop/stream-json/wiki/Parser）

parser.on('data', data => data.name === 'startObject' && ++objectCounter);
parser.on('end', () => console.log(`发现 ${objectCounter} 个对象。`));

const response = await thing.readProperty(“eventHistory”)
await response.data.pipeTo(parser);

// 发现 N 个对象

ExposedThing 接口是用于操作物的服务器 API，它允许定义请求处理器、属性、动作和事件交互。

WebIDL[SecureContext, Exposed=(Window,Worker)]
interface ExposedThing {
  ExposedThing setPropertyReadHandler(DOMString name,
          PropertyReadHandler handler);
  ExposedThing setPropertyWriteHandler(DOMString name,
          PropertyWriteHandler handler);
  ExposedThing setPropertyObserveHandler(DOMString name,
          PropertyReadHandler handler);
  ExposedThing setPropertyUnobserveHandler(DOMString name,
          PropertyReadHandler handler);
  Promise<undefined> emitPropertyChange(DOMString name,
          optional InteractionInput data);

  ExposedThing setActionHandler(DOMString name, ActionHandler action);

  ExposedThing setEventSubscribeHandler(DOMString name,
          EventSubscriptionHandler handler);
  ExposedThing setEventUnsubscribeHandler(DOMString name,
          EventSubscriptionHandler handler);
  Promise<undefined> emitEvent(DOMString name,
          optional InteractionInput data);

  Promise<undefined> expose();
  Promise<undefined> destroy();

  ThingDescription getThingDescription();
};

callback PropertyReadHandler = Promise<InteractionInput>(
        optional InteractionOptions options = {});

callback PropertyWriteHandler = Promise<undefined>(
        InteractionOutput value,
        optional InteractionOptions options = {});

callback ActionHandler = Promise<InteractionInput>(
        InteractionOutput params,
        optional InteractionOptions options = {});

callback EventSubscriptionHandler = Promise<undefined>(
        optional InteractionOptions options = {});

ExposedThing 对象具有以下内部槽：

内部槽	初始值	描述（非规范性）
[[td]]	`null`	`ExposedThing` 的物描述。
[[readHandlers]]	`{}`	一个 `Map`，其键为属性名称，值为 `PropertyReadHandler`
[[writeHandlers]]	`{}`	一个 `Map`，其键为属性名称，值为 `PropertyWriteHandler`
[[observeHandlers]]	`{}`	一个 `Map`，其键为属性名称，值为 `PropertyReadHandler`
[[unobserveHandlers]]	`{}`	一个 `Map`，其键为属性名称，值为 `Function`
[[actionHandlers]]	`{}`	一个 `Map`，其键为动作名称，值为 `ActionHandler`
[[subscribeHandlers]]	`{}`	一个 `Map`，其键为事件名称，值为 `EventSubscriptionHandler`
[[unsubscribeHandlers]]	`{}`	一个 `Map`，其键为事件名称，值为 `EventSubscriptionHandler`
[[propertyObservers]]	`{}`	一个 `Map`，其键为属性名称，值为监听器的 `Array`
[[eventListeners]]	`{}`	一个 `Map`，其键为事件名称，值为监听器的 `Array`

ExposedThing 接口扩展了 ConsumedThing。它从一个完整或部分的 ThingDescription 对象构造。

注

注意，现有的 ThingDescription 对象可以被可选地修改（例如通过在其 properties、 actions 和 events 内部属性上添加或移除元素），并且所得对象可以用于构造一个 ExposedThing 对象。这是当前添加和移除属性、动作和事件定义的方式，如示例中所示。

注

在调用 expose() 之前， ExposedThing 对象不会服务任何请求。这允许先构造 ExposedThing，然后在开始服务请求之前初始化其属性和服务处理器。

要使用 ExposedThingInit init 构造一个 ExposedThing，运行以下步骤：

如果出于安全原因，当前脚本上下文不允许调用此方法，则抛出一个 SecurityError 并停止。
在 init 上运行 expand an ExposedThingInit 步骤。如果失败，则重新抛出该错误并停止。否则，存储获得的 td
在 td 上运行 expand a TD 步骤。如果这失败，则重新抛出该错误并停止。
令 thing 为一个新的 ExposedThing 对象。
将 thing 的 [[td]] 设置为 td。
返回 thing。

返回 ExposedThing 对象的 [[td]]，该对象表示物的物描述。应用可以查询存储在 [[td]] 中的物元数据，以便在与其交互之前内省其能力。

当收到读取某个属性的外部请求时被调用的函数，并定义如何处理此类请求。它返回一个 Promise，并以一个 ReadableStream 对象，或一个符合 DataSchema 的 ECMAScript 值兑现，或者以错误拒绝。

接受 name 和 handler 作为实参。设置服务处理器，该处理器定义当收到读取与 name 匹配的指定属性的请求时应该做什么。错误时抛出异常。返回对 this 对象的引用以支持链式调用。

编辑注

注意，不需要注册用于处理读取多个或全部属性请求的处理器。请求和回复在单个网络请求中传输，但 ExposedThing 可以通过多次调用单个读取处理器来实现它们。

handler 回调函数应该实现读取一个属性，并且当从底层平台收到读取一个属性的请求时，实现 SHOULD 调用它。

对于任何给定的属性，最多 MUST 有一个处理器，因此新添加的处理器 MUST 替换先前的处理器。如果没有为任何给定的属性初始化处理器，实现 SHOULD 基于 [[td]] 内部槽中提供的物描述实现默认属性读取处理器。

当给定 name 和 handler 调用该方法时，实现 MUST 运行以下步骤：

如果出于安全原因，当前脚本上下文不允许调用此方法，则抛出一个 SecurityError 并停止。
如果 [[td]].properties[name] 不存在，则抛出 NotFoundError 并停止。
将 this.[[readHandlers]][name] 设置为 handler。

当实现收到读取属性 name 的网络请求，并带有 options 时，运行以下步骤：

如果此操作不受支持，则按照协议绑定发回一个 NotSupportedError 并停止。
如果此操作不被允许，则按照协议绑定发回一个 NotAllowedError 并停止。
令 value 为使用 name 和 options 运行以下 read server property 步骤的结果：
1. 令 interaction 为 [[td]].properties.name。
2. 如果名称为 name 的属性不存在，则抛出 NotFoundError 并停止。
3. 令 handler 为 null。
4. 如果在 [[readHandlers]] 内部槽中存在用于 interaction 的用户提供的 PropertyReadHandler，则令 handler 为它。
5. 否则，如果实现提供了默认读取处理器，则令 handler 为它。
6. 如果 handler 为 null，则抛出 NotSupportedError 并停止。
7. 令 value 为调用 handler 并给定 options 的结果。如果这失败，则抛出该错误并停止。
8. 返回 value。
  
  注
  
  这里返回的 value SHOULD 要么符合 DataSchema，要么 SHOULD 是一个由 handler 创建的 ReadableStream 对象。
如果上一步抛出了错误，则按照协议绑定创建回复，将该错误发回，并停止。
序列化并将返回的 value 添加到按照协议绑定创建的回复中。

当收到读取在对象 propertyNames 中给定的多个属性的网络请求，并带有 options 时，对 propertyNames 和 options 运行以下 read multiple properties 步骤：

如果此操作不受支持，则按照协议绑定发回一个 NotSupportedError 并停止。
如果此操作不被允许，则按照协议绑定发回一个 NotAllowedError 并停止。
对于在 propertyNames 中定义的每个键为 name 的属性，
1. 令 value 为在 name 和 options 上运行 read server property 步骤的结果。如果这抛出异常，则按照协议绑定创建的回复中发回该错误并停止。
2. 将 propertyNames.name 设置为 value。
通过发送一个按照协议绑定从 propertyNames 创建的单个回复来回复请求。

当收到读取所有属性的网络请求，并带有 options 时，运行以下步骤：

如果此操作不受支持，则按照协议绑定发回一个 NotSupportedError 并停止。
如果此操作不被允许，则按照协议绑定发回一个 NotAllowedError 并停止。
令 properties 为一个对象，该对象使用物中定义的所有属性创建，其值设置为 null。
在 properties 和 options 上运行 read multiple properties 步骤。

接受 name 和 handler 作为实参。设置服务处理器，该处理器定义当收到观察与 name 匹配的指定属性的请求时应该做什么。错误时抛出异常。返回对 this 对象的引用以支持链式调用。

handler 回调函数应该实现读取一个属性，并以一个 InteractionOutput 对象兑现，或以错误拒绝。

对于任何给定的属性，最多 MUST 有一个处理器，因此新添加的处理器 MUST 替换先前的处理器。如果没有为任何给定的属性初始化处理器，实现 SHOULD 基于物描述实现默认属性读取处理器。

当给定 name 和 handler 调用该方法时，实现 MUST 运行以下步骤：

如果出于安全原因，当前脚本上下文不允许调用此方法，则抛出一个 SecurityError 并停止。
如果 this.[[td]].properties[name] 不存在，则抛出 NotFoundError 并停止。
将 this[[observeHandlers]][name] 设置为 handler。

当实现收到观察一个属性 name 的网络请求，并带有 options 时，运行以下步骤：

如果此操作不受支持，则按照协议绑定发回一个 NotSupportedError 并停止。
如果此操作不被允许，则按照协议绑定发回一个 NotAllowedError 并停止。
如果 this.[[td]].properties[name] 不存在，则在回复中发回一个 NotFoundError 并停止。
在内部保存请求发送者信息，以及 options 和 this.[[propertyObservers]][name]，以便能够通知属性值变更。

注

每当 property 的值发生变化时，应用脚本都需要显式调用 emitPropertyChange()。

接受 name 和 handler 作为实参。设置服务处理器，该处理器定义当收到取消观察与 name 匹配的指定属性的请求时应该做什么。错误时抛出异常。返回对 this 对象的引用以支持链式调用。

handler 回调函数应该实现当实现收到取消观察请求时应做什么。

对于任何给定的属性，最多 MUST 有一个处理器，因此新添加的处理器 MUST 替换先前的处理器。如果没有为任何给定的属性初始化处理器，实现 SHOULD 基于物描述实现默认处理器。

当给定 name 和 handler 调用该方法时，实现 MUST 运行以下步骤：

如果出于安全原因，当前脚本上下文不允许调用此方法，则抛出一个 SecurityError 并停止。
如果 this.[[td]].properties[name] 不存在，则抛出 NotFoundError 并停止。
将 this.[[unobserveHandlers]][name] 设置为 handler。

当实现收到对属性 name 取消观察的网络请求，并带有 options 时，运行以下步骤：

如果此操作不受支持，则按照协议绑定发回一个 NotSupportedError 并停止。
如果此操作不被允许，则按照协议绑定发回一个 NotAllowedError 并停止。
如果 this.[[td]].properties[name] 不存在，则在回复中发回一个 NotFoundError 并停止。
令 handler 为 this.[[unobserveHandlers]][name]；
如果 handler 是一个 Function，则使用 options 调用它，然后发回一个遵循协议绑定的回复并停止。
否则，如果 this.[[propertyObservers]][name] 存在，则将其从 this.[[propertyObservers]] 中移除，按照协议绑定中定义的方式发回一个回复并停止。
否则，按照协议绑定中定义的方式，在回复中发回一个 NotFoundError 并停止。

接受 name 实参，表示一个属性名称，以及可选的 data 实参。触发向指定属性的所有观察者发出通知，其中数据由 data 实参提供；如果未提供，则由与该属性关联的观察处理器或读取处理器获得。该方法 MUST 运行以下步骤：

令 promise 为一个新的 Promise。
返回 promise 并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise 并停止。
令 name 为第一个实参。
令 property 为 this.[[td]].properties[name]。
如果 property 为 undefined，则用 NotFoundError 拒绝 promise 并停止。
令 data 为第二个实参。
如果 data 为 undefined，则运行以下子步骤：
1. 令 handler 为 null.
2. 如果 name 在 [[readHandlers]] 中不存在，则拒绝 promise 并停止。
3. 令 handler 为 [[readHandlers]][name]。
4. 如果 handler 为 null 或 undefined，则拒绝 promise 并停止。
5. 令 handled 为调用 handler 并给定 null 的结果。
6. 如果 handled 被拒绝，则拒绝 promise 并停止。
7. 否则，如果 handled 以 value 兑现，则令 data 为 value。
对于 [[propertyObservers]][name] 中的每个 observer，运行以下子步骤：
1. 令 options 为与 observer 一起保存的交互选项。
2. 请求底层平台按照协议绑定，从 data 和 options 创建一个 reply。
  
  编辑注
  
  此条款需要扩展，和/或引用 [WOT-PROTOCOL-BINDINGS] 中的算法。
3. 将 reply 发送给 observer。
兑现 promise。

当收到写入某个属性的外部请求时被调用的函数，并定义如何处理此类请求。接受 value 作为实参并返回一个 Promise，当由设置处理器时提供的名称标识的属性值已更新时兑现；或者如果未找到该属性或无法更新该值，则以错误拒绝。

编辑注

注意，如果需要，此回调函数中的代码可以在更新属性之前读取该属性，以便找出旧值。因此旧值不会提供给此函数。

注

该值由实现以 InteractionOutput 对象形式提供，以便能够表示未由 DataSchema 描述的值，例如流。

接受 name 和 handler 作为实参。设置服务处理器，该处理器定义当收到写入由设置处理器时给定的 name 匹配的属性的请求时应该做什么。错误时抛出异常。返回对 this 对象的引用以支持链式调用。

注

注意，即使对于 readonly 属性，也可以指定写入处理器，如 Issue 199 中所解释。在这种情况下，写入处理器可以以应用特定的方式定义使请求失败。

对于任何给定的属性，最多 MUST 有一个写入处理器，因此新添加的处理器 MUST 替换先前的处理器。如果没有为任何给定属性初始化写入处理器，实现 SHOULD 在该属性可写时实现默认属性更新，并在该属性可观察时通知观察者变化，这些均基于物描述。

当给定 name 和 handler 调用该方法时，实现 MUST 运行以下步骤：

如果出于安全原因，当前脚本上下文不允许调用此方法，则抛出一个 SecurityError 并停止。
如果 this.[[td]].properties[name] 不存在，则抛出 NotFoundError 并停止。
将 this.[[writeHandlers]][name] 设置为 handler。

当收到对属性 name 写入新值 value 的网络请求，并带有 options 时，实现 MUST 运行以下 update property steps，给定 name、 value、 options，并将 mode 设置为 "single"：

如果此操作不受支持，则按照协议绑定发回一个 NotSupportedError 并停止。
如果此操作不被允许，则按照协议绑定发回一个 NotAllowedError 并停止。
令 interaction 为 this.[[td]].properties[name]。
如果 interaction 为 undefined，则在回复中返回一个 NotFoundError 并停止。
令 handler 为 this.[[writeHandlers]][name]。
如果 handler 为 undefined，并且存在由实现提供的默认写入处理器，则令 handler 为它。
如果 handler 为 undefined，则随回复发回一个 NotSupportedError 并停止。
令 promise 为调用 handler 并给定 name 和 options 的结果。如果它失败，则在回复中返回该错误并停止。
如果 mode 为 "single"，则按照协议绑定回复请求并报告成功，然后停止。

当收到写入在对象 propertyNames 中给定的多个属性的网络请求，并带有 options 时，运行以下步骤：

如果此操作不受支持，则按照协议绑定发回一个 NotSupportedError 并停止。
如果此操作不被允许，则按照协议绑定发回一个 NotAllowedError 并停止。
对于 propertyNames 中定义的每个键为 name、值为 value 的属性，使用 name、value、 options 并将 mode 设置为 "multiple"，运行 update property steps。如果这失败，则用该错误回复请求并停止。
通过按照协议绑定发送单个回复来回复请求。

当收到调用某个动作的外部请求时被调用的函数，并定义如何处理此类请求。它会在给定 params 并可选给定一个 options 对象时被调用。它返回一个 Promise，该 Promise 以错误拒绝或以动作返回的值兑现，该值作为 InteractionInput。

注

应用脚本 MAY 从 ActionHandler 返回一个 ReadableStream 对象。实现随后将使用该流来构造动作的响应。

接受 name 和 action 作为实参。设置处理器函数，该函数定义当收到请求以调用与 name 匹配的动作时应做什么。错误时抛出异常。返回对 this 对象的引用以支持链式调用。

action 回调函数将实现一个动作，并且当从底层平台收到调用该动作的请求时，实现 SHOULD 调用它。

对于任何给定的动作，最多 MUST 有一个处理器，因此新添加的处理器 MUST 替换先前的处理器。

当给定 name 和 action 调用该方法时，运行以下步骤：

如果出于安全原因，当前脚本上下文不允许调用此方法，则抛出一个 SecurityError 并停止。
令 interaction 为 this.[[td]].actions[name]。
如果 interaction 为 undefined，则抛出一个 NotFoundError 并停止。
将 this.[[actionHandlers]][name] 设置为 action。

当收到调用由 name 标识的动作的网络请求，并给定 inputs 以及可选的 options 时，运行以下步骤：

如果此操作不受支持，则按照协议绑定发回一个 NotSupportedError 并停止。
如果此操作不被允许，则按照协议绑定发回一个 NotAllowedError 并停止。
令 interaction 为 this.[[td]].properties[name]。
如果 interaction 为 undefined，则在回复中返回一个 NotFoundError 并停止。
令 handler 为 this.[[actionHandlers]][name]。
如果 handler 为 undefined，则返回一个 NotSupportedError，并带有按照协议绑定创建的回复，然后停止。
令 promise 为调用 handler 并给定 name、inputs 和 options 的结果。
如果 promise 拒绝，则随回复发送该错误并停止。
当 promise 以 data 兑现时，使用 data 按照协议绑定创建并发送回复。

当收到订阅某个事件的外部请求时被调用的函数，并定义如何处理此类请求。它在给定由实现提供并来自订阅者的 options 对象时被调用。它返回一个 Promise，该 Promise 以错误拒绝或在订阅被接受时兑现。

接受 name 和 handler 作为实参。设置处理器函数，该函数定义当收到针对由 name 匹配的指定事件的订阅请求时应做什么。错误时抛出异常。返回对 this 对象的引用以支持链式调用。

handler 回调函数 SHOULD 实现当收到订阅请求时应做什么，例如必要的初始化。注意，用于发出事件的处理器是单独设置的。

对于任何给定的事件，最多 MUST 有一个事件订阅处理器，因此新添加的处理器 MUST 替换先前的处理器。

当给定 name 和 handler 调用该方法时，运行以下步骤：

如果出于安全原因，当前脚本上下文不允许调用此方法，则抛出一个 SecurityError 并停止。
令 interaction 为 this.[[td]].events[name]。
如果 interaction 为 undefined，则抛出一个 NotFoundError 并停止。
将 this.[[subscribeHandlers]][name] 设置为 handler。
返回 this。

接受 name 和 handler 作为实参。设置处理器函数，该函数定义当由 name 匹配的指定事件被取消订阅时应做什么。错误时抛出异常。返回对 this 对象的引用以支持链式调用。

handler 回调函数 SHOULD 实现当收到取消订阅请求时应做什么。

对于任何给定的事件，最多 MUST 有一个处理器，因此新添加的处理器 MUST 替换先前的处理器。

当给定 name 和 handler 调用该方法时，运行以下步骤：

如果出于安全原因，当前脚本上下文不允许调用此方法，则抛出一个 SecurityError 并停止。
令 interaction 为 this.[[td]].events[name]。
如果 interaction 为 undefined，则抛出一个 NotFoundError 并停止。
将 this.[[unsubscribeHandlers]][name] 设置为 handler。
返回 this。

当底层平台收到针对 name 的事件取消订阅请求，并可选带有 options 时，运行以下步骤：

如果此操作不受支持，则按照协议绑定发回一个 NotSupportedError 并停止。
如果此操作不被允许，则按照协议绑定发回一个 NotAllowedError 并停止。
令 interaction 为 this.[[td]].events[name]。
如果 interaction 为 undefined，则发回一个 NotFoundError 并停止。
如果 this.[[unsubscribeHandlers]][name] 存在并且是一个 Function，则用 options 调用它并停止。
否则，如果 name 在 this.[[eventListeners]] 中 [=map/exists]，则移除 name。
返回 this。

当 emitEvent() 方法发出一个名称为 name、带有 data 的事件时，运行以下步骤：

令 listeners 为 [[eventListeners]].name。
对于 listeners 中的每个 subscriber，运行以下子步骤：
1. 按照协议绑定，从 data 和 subscriber 创建一个事件通知 response，包括其 options。
2. 如果 data 为 undefined，则假定该通知 response 将包含一个空数据载荷，如协议绑定所规定。
3. 如果底层协议栈允许传达事件错误，并且 UA 检测到错误条件，则按照协议绑定，使用 data、 subscriber 及其 options，将 response 创建为错误通知。
  
  注
  
  错误报告是协议特定的，并由实现封装。在客户端端，如果客户端 UA 检测到该错误，则会调用随订阅传入的错误监听器。
4. 将 response 发送给由 subscriber 标识的订阅者。

接受 name 作为实参，表示一个事件名称，并可选接受 data。触发发出带有可选数据的事件。该方法 MUST 运行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise 并停止。
令 interaction 为 [[td]].events.name。
如果找不到名称为 name 的事件，则用 NotFoundError 拒绝 promise 并停止。
向底层平台发出请求，以发出一个带有可选 data 的事件。调用 handling events 步骤。

开始为该物服务外部请求，使得使用属性、动作和事件的 WoT 交互成为可能。该方法 MUST 运行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise 并停止。
在 [[td]] 上运行 expand a TD 步骤。
在 [[td]] 上运行 validate a TD。如果失败，则用 TypeError 拒绝 promise 并停止。
对于 [[td]].properties 中的每个 key，将 this.[[propertyObservers]].key 初始化为一个空 Array，以存储在值变化时通知观察者所需的观察请求数据。
对于 this.[[td]].events 中的每个 key，将 this.[[eventListeners]].key 初始化为一个空 Array，以存储在事件发出时通知订阅者所需的订阅请求数据。
基于内省 [[td]] 来设置 WoT 交互，如 [WOT-TD] 和 [WOT-PROTOCOL-BINDINGS] 中所解释。向底层平台发出请求以初始化协议绑定，然后基于协议绑定，开始服务针对 WoT 交互的外部请求（读取、写入和观察属性，调用动作并管理事件订阅）。实现 MAY 因任何原因拒绝此步骤（例如，如果它们想对交互形式强制执行进一步检查和约束）。
如果请求期间发生错误，则用一个 Error 对象 error 拒绝 promise，其中 error.message 设置为协议绑定看到的错误代码，然后停止。
否则兑现 promise 并停止。

停止为该物服务外部请求并销毁对象。注意，最终的注销应在调用此方法之前完成。该方法 MUST 运行以下步骤：

返回一个 Promise promise，并并行执行后续步骤。
如果出于安全原因，当前脚本上下文不允许调用此方法，则用 SecurityError 拒绝 promise 并停止。
向底层平台发出请求，以基于协议绑定，停止服务针对WoT 交互的外部请求。
如果请求期间发生错误，则用一个 Error 对象 error 拒绝 promise，其 message 设置为协议绑定看到的错误代码，然后停止。
否则兑现 promise 并停止。

下一个示例展示如何基于预先构造的部分 TD 对象创建一个 ExposedThing。

示例 6：使用简单属性创建 ExposedThing

try {
  let temperaturePropertyDefinition = {
    type: "number",
    minimum: -50,
    maximum: 10000
  };
  let tdFragment = {
    properties: {
      temperature: temperaturePropertyDefinition
    },
    actions: {
      reset: {
        description: "重置温度传感器",
        input: {
          temperature: temperatureValueDefinition
        },
        output: null,
        forms: []
      },
    },
    events: {
      onchange: temperatureValueDefinition
    }
  };
  let thing1 = await WOT.produce(tdFragment);
  // 初始化属性
  await thing1.writeProperty("temperature", 0);
  // 添加服务处理器
  thing1.setPropertyReadHandler("temperature", () => {
     return readLocalTemperatureSensor();  // Promise
  });
  // 开始服务请求
  await thing1.expose();
} catch (err) {
   console.log("创建 ExposedThing 时出错：" + err);
}

下一个示例展示如何在现有的 ExposedThing 上添加或修改一个属性定义：取其 td 属性，添加或修改它，然后用它创建另一个 ExposedThing。

示例 7：添加一个对象属性

try {
  // 创建 thing1 的 TD 的深拷贝
  let instance = JSON.parse(JSON.stringify(thing1.td));
  const statusValueDefinition = {
    type: "object",
    properties: {
      brightness: {
        type: "number",
        minimum: 0.0,
        maximum: 100.0,
        required: true
      },
      rgb: {
        type: "array",
        "minItems": 3,
        "maxItems": 3,
        items : {
            "type" : "number",
            "minimum": 0,
            "maximum": 255
        }
      }
  };
  instance["name"] = "mySensor";
  instance.properties["brightness"] = {
    type: "number",
    minimum: 0.0,
    maximum: 100.0,
    required: true,
  };
  instance.properties["status"] = statusValueDefinition;
  instance.actions["getStatus"] = {
    description: "获取状态对象",
    input: null,
    output: {
      status : statusValueDefinition;
    },
    forms: [...]
  };
  instance.events["onstatuschange"] = statusValueDefinition;
  instance.forms = [...];  // 更新
  var thing2 = new ExposedThing(instance);
  // TODO: 添加服务处理器
  await thing2.expose();
  });
} catch (err) {
   console.log("创建 ExposedThing 时出错：" + err);
}

以下内容将涵盖一组示例，说明如何使用 expand an ExposedThingInit 步骤，从 ExposedThingInit 生成一个物描述。作为假设，运行时支持 HTTP 和 COAP 协议绑定，并托管在 192.168.0.1。

下一个示例展示如何利用 ExposedThingInit 创建一个简单的物描述，其中包含一个使用默认值的属性。

示例 8：创建带有一个属性可供性项的物描述

{
  "properties" : {
    "temperature":{}
  }
}

{
  "@context": [
    "https://www.w3.org/2019/wot/td/v1"
  ],
  "title": "Thing-123",
  "securityDefinitions": {
    "no_sec": {
      "scheme": "nosec"
    }
  },
  "security": "no_sec",
  "properties": {
    "temperature": {
      "forms": [{
        "href": "http://192.168.0.1:8080/properties/temperature",
        "contentType": "application/json"
      },
      {
      "href": "coap://192.168.0.1:9090/properties/temperature",
      "contentType": "application/json"
      }]
    }
  }
}

编辑注

TODO：添加更多示例，其中 ExposedThingInit 包含由算法替换的建议值。

Discovery는 참여하는 네트워크 노드 (클라이언트, 서버, 디렉터리 서비스)의 프로비저닝과 지원이 필요한 분산 애플리케이션입니다. 이 API는 다양한 IoT 배포에서 지원되는 일반적인 discovery 방식의 클라이언트 측을 모델링합니다.

ThingDiscoveryProcess 객체는 discovery process를 제어하고 결과를 반환하는 속성과 메서드를 제공합니다.

WebIDL[SecureContext, Exposed=(Window,Worker)]
interface ThingDiscoveryProcess {
  constructor(optional ThingFilter filter = {});
  readonly attribute boolean done;
  readonly attribute Error? error;
  undefined stop();
  async iterable<ThingDescription>;
};

ThingDiscoveryProcess 객체에는 다음 internal slot이 있습니다.

Internal Slot	초기값	설명(비규범적)
[[filter]]	`undefined`	discovery에서 사용되는 `ThingFilter` 객체입니다.
[[url]]	`undefined`	discovery에서 TD Directory를 나타내는 `URL`입니다.

done 속성은 discovery가 중지되었거나 더 이상 보고할 결과 없이 완료된 경우 true입니다.

error 속성은 discovery process 중 발생한 마지막 오류를 나타냅니다. 일반적으로 discovery를 중지시키는 심각한 오류에 사용됩니다.

ThingDiscoveryProcess 객체는 async iterator 개념을 구현합니다.

filter로 ThingDiscoveryProcess를 생성하려면 다음 단계를 실행합니다:

filter가 객체 또는 null이 아니면, TypeError를 throw하고 중지합니다.
새 ThingDiscoveryProcess 객체를 discovery로 둡니다.
discovery.[[filter]]를 filter로 설정합니다.
discovery.done을 false로 설정합니다.
discovery.error를 null로 설정합니다.
discovery를 반환합니다.

Thing을 discovery하기 위한 제약 조건을 key-value 쌍으로 포함하는 객체를 나타냅니다.

WebIDLdictionary ThingFilter {
  object? fragment;
  
};

fragment 속성은 발견된 Thing과 속성별로 매칭하는 데 사용되는 템플릿 객체를 나타냅니다.

편집자 주

query 속성은 WoT Discovery 태스크포스에서 표준화될 때까지 ThingFilter에서 일시적으로 제거되었습니다. 이는 구현이 수락하는 query string, 예를 들어 SPARQL 또는 JSON query를 나타냈습니다. 지원은 WoT Runtime에서 로컬로 구현되거나, TD Directory의 서비스로 원격 구현될 예정이었습니다.

편집자 주

url 속성은 제거되었습니다. 이 속성은 discovery 요청을 제공하는 대상 엔티티, 예를 들어 TD Directory의 URL 또는 직접 대상으로 지정된 Thing의 URL을 나타냈지만, 이제는 전용 메서드로 구현됩니다.

이미 시작된 discovery process 동안 무엇을 해야 하는지 설명합니다. 이 알고리즘은 discovery가 주어졌을 때 다음 단계를 실행합니다:

Thing Description으로 이어지는 새 link가 발견되어 기본 플랫폼에서 제공될 때마다 다음 하위 단계를 실행합니다:
1. 기본 discovery process에서 사용하는 Protocol Binding(link로 지정됨)을 사용하여 td를 JSON 객체로 가져옵니다. HTTP(S) Binding의 경우, 이 과정은 td를 가져오기 위해 Fetch API를 사용할 수 있습니다.
2. 실패하면 discovery.error 속성을 SyntaxError로 설정하고, td를 폐기한 다음 discovery process를 계속합니다.
Thing Description td가 발견되어 기본 플랫폼 또는 이전 단계에서 제공될 때마다 다음 하위 단계를 실행합니다:

참고

이 시점에서 구현은 discovery process의 흐름을 제어할 수 MAY 있습니다 (예를 들어 메모리 제약에 따라 결과를 큐에 넣거나, 큐가 너무 커지면 discovery를 일시적으로 중지하거나, 큐가 충분히 비워지면 discovery를 재개할 수 있습니다). 이 단계들은 발견/가져온 각 td에 대해 실행됩니다.
1. discovery.[[filter]].fragment를 fragment로 둡니다.
2. fragment가 object이면, 그 안에 정의된 각 key에 대해:
  1. 그 key가 json 안에 exists하는지, 그리고 json[key]가 fragment.key와 같은지 확인합니다.
  2. 이 검사 중 어느 하나라도 실패하면, td를 폐기하고 discovery process를 계속합니다.
3. asyncIterator를 사용하여 td를 yield합니다.
  
  편집자 주
  
  적절한 asyncIterator 용어를 사용하여 이 단계를 개선합니다.
discovery process 중 오류가 발생할 때마다 다음 하위 단계를 실행합니다:

참고

마지막 오류가 유지됩니다. 구현은 오류가 보고되어야 한다고 판단하면 discovery process를 중지하기로 선택할 수 MAY 있습니다.
1. 새 Error 객체를 error로 둡니다. error.name을 "DiscoveryError"로 설정합니다.
2. Protocol Bindings에서 제공한 오류 코드 또는 메시지가 있었다면, error.message를 그 값의 문자열로 설정합니다.
3. discovery.error를 error로 설정합니다.
4. 오류가 복구 불가능하고 기본 플랫폼에 의해 discovery가 중지되었거나, 구현이 discovery process를 중지하고 오류를 보고하기로 결정했다면, discovery.done을 true로 설정하고 이 단계를 종료합니다.

discovery process를 중지하거나 억제합니다. 모든 discovery 메서드와 엔드포인트에서 지원되는 것은 아닐 수 있지만, 이후의 discovery 결과 또는 오류는 모두 폐기되고 discovery는 완료된 것으로 표시됩니다. 이 메서드는 다음 단계를 실행해야 MUST 합니다:

보안상의 이유로 현재 스크립팅 컨텍스트에서 이 메서드 호출이 허용되지 않으면, SecurityError를 throw하고 중지합니다.
기본 플랫폼에 discovery process를 중지하도록 요청합니다. 이것이 오류를 반환하거나, 예를 들어 discovery가 끝이 열린 multicast 요청에 기반한 경우처럼 불가능하다면, 구현은 이후 발견된 항목을 폐기해야 SHOULD 합니다.
done 속성을 true로 설정합니다.

다음 예제는 로컬 하드웨어에 의해 노출된 Thing의 ThingDescription 객체를 찾습니다. 실행 중인 WoT Runtime 인스턴스 수와 관계없이, Discovery 객체가 제공하는 asyncIterator를 사용하여 결과를 비동기적으로 순회하고, 얻은 ThingDescription 객체로 작업을 수행할 수 있습니다.

예제 9: Thing의 Thing Description 가져오기

let url = "https://mythings.com/thing1";
let td = await WOT.requestThingDescription(url);
console.log("Found Thing Description for " + td.title);

다음 예제는 TD Directory 서비스에 나열된 Thing의 ThingDescription 객체를 찾습니다. 안전을 위해 timeout을 설정합니다.

예제 10: directory를 통해 Things discovery하기

let discovery = await WOT.exploreDirectory("http://directory.wotservice.org");
setTimeout( () => {
    discovery.stop();
    console.log("Discovery stopped after timeout.");
  },
  3000);
for await (const td of discovery) {
  console.log("Found Thing Description for " + td.title);
  let thing = new ConsumedThing(td);
  console.log("Thing name: " + thing.getThingDescription().title);
};
if (discovery.error) {
  console.log("Discovery stopped because of an error: " + error.message);
}

다음 예제는 WOT runtime에 프로비저닝된 어떤 방식으로든 수행되는 일반 discovery를 위한 것으로, 사용 가능한 경우 로컬 Things도 포함합니다.

예제 11: 네트워크에서 Things discovery하기

let discovery = await WOT.discover();
setTimeout( () => {
    discovery.stop();
    console.log("Stopped open-ended discovery");
  },
  10000);
for await (const td of discovery) {
  console.log("Found Thing Description for " + td.title);
};
if (discovery.error) {
  console.log("Discovery stopped because of an error: " + error.message);
}

Web of Things（WoT）脚本 API

摘要

本文档状态

1. 引言

2. 用例场景

2.1 使用物

2.2 公开物

2.3 发现

3. 一致性

4. 术语和约定

5. ThingDescription 类型

5.1 获取物 描述

5.2 展开物 描述

5.3 验证物 描述

6. WOT 命名空间

6.1 consume() 方法

6.2 produce() 方法

6.2.1 展开 ExposedThingInit

6.2.2 验证 ExposedThingInit

6.3 discover() 方法

6.4 exploreDirectory() 方法

6.5 requestThingDescription() 方法

7. 处理交互数据

7.1 InteractionInput 类型

7.2 InteractionOutput 接口

7.2.1 value() 函数

7.2.2 arrayBuffer() 函数

7.2.3 check data schema 算法

7.2.4 create interaction request 算法

7.2.5 parse interaction response 算法

7.3 使用 InteractionInput 和 InteractionOutput

7.4 错误处理

8. ConsumedThing 接口

8.1 ConsumedThing 的内部槽

8.2 构造 ConsumedThing

8.3 getThingDescription() 方法

8.4 readProperty() 方法

8.5 readMultipleProperties() 方法

8.6 readAllProperties() 方法

8.7 writeProperty() 方法

8.8 writeMultipleProperties() 方法

8.9 observeProperty() 方法

8.10 invokeAction() 方法

8.11 subscribeEvent() 方法

8.12 InteractionOptions 字典

8.13 PropertyReadMap 类型

8.14 PropertyWriteMap 类型

8.15 InteractionListener 回调

8.16 ErrorListener 回调

8.17 Subscription 接口

8.17.1 Subscription 的内部槽

8.17.2 stop() 方法

8.17.3 查找 unsubscribe 表单

8.18 ConsumedThing 示例

9. ExposedThing 接口

9.1 ExposedThing 的内部槽

9.2 构造 ExposedThing

9.3 getThingDescription() 方法

9.4 PropertyReadHandler 回调

9.5 setPropertyReadHandler() 方法

9.6 处理读取 属性的请求

9.7 处理读取 多个属性的请求

9.8 处理读取 所有属性的请求

9.9 setPropertyObserveHandler() 方法

9.10 处理属性观察 请求

9.11 setPropertyUnobserveHandler() 方法

9.12 处理属性取消观察 请求

9.13 emitPropertyChange() 方法

9.14 PropertyWriteHandler 回调

9.15 setPropertyWriteHandler() 方法

9.16 处理写入 属性的请求

9.17 处理写入 多个属性的请求

9.18 ActionHandler 回调

9.19 setActionHandler() 方法

9.20 处理动作请求

9.21 EventSubscriptionHandler 回调

9.22 setEventSubscribeHandler() 方法

9.23 处理事件订阅 请求

9.24 setEventUnsubscribeHandler() 方法

9.25 处理事件取消订阅 请求

5. `ThingDescription` 类型

5.1 获取物描述

5.2 展开物描述

5.3 验证物描述

6. `WOT` 命名空间

6.1 `consume()` 方法

6.2 `produce()` 方法

6.3 `discover()` 方法

6.4 `exploreDirectory()` 方法

6.5 `requestThingDescription()` 方法

7.1 `InteractionInput` 类型

7.2 `InteractionOutput` 接口

7.2.1 `value()` 函数

7.2.2 `arrayBuffer()` 函数

7.3 使用 `InteractionInput` 和 `InteractionOutput`

8. `ConsumedThing` 接口

8.1 `ConsumedThing` 的内部槽

8.2 构造 `ConsumedThing`

8.3 `getThingDescription()` 方法

8.4 `readProperty()` 方法

8.5 `readMultipleProperties()` 方法

8.6 `readAllProperties()` 方法

8.7 `writeProperty()` 方法

8.8 `writeMultipleProperties()` 方法

8.9 `observeProperty()` 方法

8.10 `invokeAction()` 方法

8.11 `subscribeEvent()` 方法

8.12 `InteractionOptions` 字典

8.13 `PropertyReadMap` 类型

8.14 `PropertyWriteMap` 类型

8.15 `InteractionListener` 回调

8.16 `ErrorListener` 回调

8.17 `Subscription` 接口

8.17.1 `Subscription` 的内部槽

8.17.2 `stop()` 方法

9. `ExposedThing` 接口

9.2 构造 `ExposedThing`

9.3 `getThingDescription()` 方法

9.4 `PropertyReadHandler` 回调

9.5 `setPropertyReadHandler()` 方法

9.6 处理读取属性的请求

9.7 处理读取多个属性的请求

9.8 处理读取所有属性的请求

9.9 `setPropertyObserveHandler()` 方法

9.10 处理属性观察请求

9.11 `setPropertyUnobserveHandler()` 方法

9.12 处理属性取消观察请求

9.13 `emitPropertyChange()` 方法

9.14 `PropertyWriteHandler` 回调

9.15 `setPropertyWriteHandler()` 方法

9.16 处理写入属性的请求

9.17 处理写入多个属性的请求

9.18 `ActionHandler` 回调

9.19 `setActionHandler()` 方法

9.21 `EventSubscriptionHandler` 回调

9.22 `setEventSubscribeHandler()` 方法

9.23 处理事件订阅请求

9.24 `setEventUnsubscribeHandler()` 方法

9.25 处理事件取消订阅请求

9.27 `emitEvent()` 方法

9.28 `expose()` 方法

9.29 `destroy()` 方法

10. `ThingDiscoveryProcess` 인터페이스

10.1 `ThingDiscoveryProcess` 구성하기

10.2 `ThingFilter` dictionary

10.4 `stop()` 메서드