Web of Things (WoT) スクリプティング API

概要

Web of Things は、自身の機能を機械が解釈可能な Thing Description (TD) で記述し、それらの機能を WoT Interface、すなわち Properties（値の読み取りおよび書き込み用）、Action（戻り値の有無にかかわらずリモート手続きを実行するため）および Event（通知をシグナルするため）としてモデル化されたネットワーク相互作用を通じて公開できるエンティティ（Thing）で構成されます。

主な Web of Things (WoT) の概念は、 Web of Things (WoT) Architecture 1.1 仕様で説明されています。

スクリプティングは WoT における任意の構成要素であり、通常は WoT Runtime およびスクリプト管理を実行できるゲートウェイまたはブラウザーで使用され、WoT のサポートを新しい種類のエンドポイントに拡張し、 TD Directory などの WoT アプリケーションを実装する便利な方法を提供します。

この仕様は、スクリプトが Thing を発見し、操作し、またスクリプトによって指定された WoT Interactions によって特徴付けられるローカルに定義された Thing を公開できるようにする、WoT Interface を表すアプリケーションプログラミングインターフェイス (API) について説明します。

この文書で定義される API は、意図的に Web of Things (WoT) Thing Description 1.1 仕様に密接に従っています。これらの上により抽象的な API を実装すること、または WoT のネットワーク向けインターフェイス（すなわち WoT Interface）を直接実装することが可能です。

編集者注

この仕様は、少なくとも Eclipse Thingweb プロジェクト（node-wot としても知られる）によって実装されており、現時点で参照用のオープンソース実装とみなされています。ソースコード（例を含む）を確認してください。

WoT API object をシングルトンとして定義し、適合クラスごとにグループ化された 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 引数を期待し、 Thing を操作するためのクライアントインターフェイスを表す ConsumedThing オブジェクトで解決される


        Promise

を返します。このメソッドは、次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
thing を、 td から構築された新しい ConsumedThing オブジェクトとする。
[WOT-TD] および [WOT-PROTOCOL-BINDINGS] で説明されるように、td を内省することに基づいて WoT Interactions を設定する。 Protocol Bindings を初期化するように、基盤となるプラットフォームへ要求を行う。

編集者注

実装は、 WoT interactions を実装するために Protocol Bindings をどのように使用するかの複雑さをカプセル化します。将来的には、その要素が標準化される可能性があります。
promise を thing で Resolveする。

編集者注

ConsumedThing を構築することと、consume() メソッドを使用することの違いに注意してください。後者はプロトコルバインディングも初期化しますが、単に構築されたオブジェクトでは、呼び出されるまで WoT Interactions は初期化されません。

WebIDLtypedef object ExposedThingInit;

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

WoT Producer 適合クラスに属します。 init 引数を期待し、要求ハンドラーを定義する能力、すなわちサーバーインターフェイスで ConsumedThing を拡張する ExposedThing オブジェクトで解決される


        Promise

を返します。 init オブジェクトは、ExposedThingInit 型のインスタンスです。具体的には、 ExposedThingInit 値は ExposedThing の初期化に使用される辞書であり、 [WOT-ARCHITECTURE] で説明される Partial TD を表します。そのため、これは Thing Description と同じ構造を持ちますが、一部の情報を省略することがあります。このメソッドは、次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
thing を、 init で構築された新しい ExposedThing オブジェクトとする。
promise を thing で Resolveする。

init が与えられ、有効な td を結果として取得するために ExposedThingInit を展開するには、次の手順を実行します:

init に対して ExposedThingInit を検証するを実行する。それが失敗した場合、 SyntaxError をthrowし、停止する。
td を、 init が与えられて clone を実行した結果とする。
td.["securityDefinitions"] 内の各 scheme について、それが少なくとも 1 つの Protocol Binding によってサポートされているかを確認するよう、基盤となるプラットフォームへ要求を行う。サポートされていない場合は、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 に未知のスキーマがある場合、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 context URI を割り当てる。
3. missing が instance の場合、文字列 1.0.0 を割り当てる。
4. missing が forms の場合、利用可能な Protocol Bindings および content types エンコーダーを使用して Forms のリストを生成する。次に、得られたリストを forms に割り当てる。
5. missing が security の場合、 securityDefinitions フィールド内の最初にサポートされる SecurityScheme のラベルを割り当てる。 SecurityScheme が見つからない場合は、nosec と呼ばれる NoSecurityScheme を生成し、文字列 nosec を security に割り当てる。
  
  Issue 1
  
  security の値を適切に生成する方法についての議論はまだ未解決です。issue #299 を参照してください
6. missing が href の場合、 href を持たない部分的な Form として formStub を定義する。 formStub の要件を満たす最初の Protocol Binding を使用して、有効な url を生成する。url を href に割り当てる。該当する Protocol Binding が見つからない場合は、td から formStub を削除する。
7. missing を value を値として td に追加する
td に対して TD を検証するを実行する。それが失敗した場合、エラーを再throwし、停止する
td を返す

init が与えられたときに ExposedThingInit を検証するには、次の手順を実行します:

TD JSON Schema を解析し、 exposedThingInitSchema と呼ばれるオブジェクトに読み込む
optional を、次の文字列を含むリストとする: title, @context, instance, forms, security, および href.
exposedThingInitSchema 内の各プロパティおよびサブプロパティ key が required に等しい場合、次の手順を実行する:
1. key の value が Array である場合、optional 内の要素と等しいすべての要素を削除する
2. key の value が string である場合、value が optional 内のいずれかの要素と等しければ、 exposedThingInitSchema から key を削除する
init および exposedThingInitSchema が与えられたときに JSON Schema でオブジェクトを検証する結果を返す。

編集者注

JSON Schema でオブジェクトを検証する手順は、まだ議論中です。現在、この仕様は JSONSchema の検証プロセスを参照しています。 init を exposedThingInitSchema で検証するときは、この文書に従ってください。ワーキンググループが代替となる形式的アプローチを評価していることに注意してください。

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

WoT Discovery 適合クラスに属します。型が ThingFilter である省略可能な filter 引数に一致する Thing Description のために ThingDescription オブジェクトを提供する発見プロセスを開始します。このメソッドは、次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
実装が発見をサポートしていない場合、 promise を NotSupportedError で rejectし、停止する。
discovery を、新しい ThingDiscoveryProcess オブジェクトとする。
discovery.[[filter]] を filter に設定する。
discovery.[[url]] を undefined に設定する。
実装が一般にフィルターをサポートしておらず、 filter が undefined または null でない場合、 promise を NotSupportedError で rejectし、停止する。
基盤となるプラットフォームによって発見を開始できない場合、 promise を OperationError でrejectし、停止する。
discovery を渡し、スクリプトがアクセス権を持つ WoT Runtime 内でサポートおよびプロビジョニングされた任意の手段により、発見プロセスを開始するよう、基盤となるプラットフォームに要求する。
promise を discovery で Resolveする。

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

WoT Discovery 適合クラスに属します。 TD Directory URL が与えられたときに、型が ThingFilter である省略可能な filter 引数に一致する Thing Description のために ThingDescription オブジェクトを提供する発見プロセスを開始します。このメソッドは、次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
実装がディレクトリ発見をサポートしていない場合、 promise を NotSupportedError で rejectし、停止する。
discovery を、新しい ThingDiscoveryProcess オブジェクトとする。
discovery.[[url]] を url に設定する。
discovery.[[filter]] を filter に設定する。
ディレクトリ発見プロセスを開始するよう、基盤となるプラットフォームへ要求する。

注

これは、発見アルゴリズムのより詳細な記述のためのプレースホルダーです。実装は、 [WOT-DISCOVERY] および [WOT-PROTOCOL-BINDINGS] 仕様で説明される手順に従うべきです。いくつかの規範的手順を以下に示します。
1. url が TD Directory でない場合、または基盤となる実装が url によって示される Protocol Binding をサポートできない場合、 promise を NotSupportedError で rejectし、これらの手順を終了する。
2. 実装が一般にフィルターをサポートしておらず、 filter が undefined または null でない場合、 promise を NotSupportedError で rejectし、停止する。
3. discovery が与えられたときに発見プロセスを実行する。
  
  注
  
  この時点以降、エラーは error にのみ記録され、もはや promise には影響しません。
promise を discovery で Resolveする。

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

WoT Discovery 適合クラスに属します。与えられた URL から Thing Description を要求します。このメソッドは、次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
実装が Thing Description のフェッチをサポートしていない場合、 promise を NotSupportedError で rejectし、停止する。
td を、 url によって指定された Protocol Binding を使用して Thing Description を取得するよう、基盤となるプラットフォームへ要求した結果とする。 td の取得に失敗した場合、 promise を NotFoundError でrejectし、停止する。
promise を td で Resolveする。

Web of Things (WoT) Thing Description 1.1 仕様で指定されているように、WoT interactions は DataSchema を拡張し、相互作用のために 1 つが選択される複数の可能な Form を含みます。 Form には、データを説明するための contentType が含まれます。特定の content types については、JSON Schema に基づいて DataSchema が定義され、これらの内容を JavaScript 型として表現し、最終的にデータに範囲制約を設定することが可能になります。

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

WoT Consumer 適合クラスに属し、アプリケーションスクリプトから UA に提供される WoT Interaction データを表します。

DataSchemaValue は、[WoT-TD] で定義される DataSchema に対して受け入れられる ECMAScript 値です。取り得る値は、 null, boolean, number, string, array, または object 型でなければなりません（MUST）。

ReadableStream は、Thing Description 内に DataSchema を持たず、ストリームで表現できる Form の contentType のみを持つ WoT Interactions に使用されることを意図しています。

実際には、Thing Description 内に定義された DataSchema を持つ WoT Interactions、または実装によって Thing Description 内で定義された Form の contentType にマッピングできる WoT Interactions には、任意の ECMAScript 値を使用できます。

この文書のアルゴリズムは、 WoT Interactions で入力データが正確にどのように使用されるかを指定します。

WoT Consumer 適合クラスに属します。 InteractionOutput オブジェクトは常に実装によって作成され、 WoT Interactions から返されたデータをアプリケーションスクリプトに公開します。

このインターフェイスは、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 Interactions における生のペイロードを ReadableStream として表します。初期値は null です。

dataUsed プロパティは、データストリームが disturbed されたかどうかを示します。初期値は false です。

form 属性は、この WoT Interaction のために Thing Description から選択された Form を表します。初期値は null です。

schema 属性は、ペイロードの DataSchema（[WoT-TD] で定義）を JSON オブジェクトとして表します。初期値は null です。

[[value]] 内部スロットは、解析済みの WoT Interaction の値を表します。初期値は undefined です（null は有効な値であることに注意してください）。

WoT Interaction によって返されたデータを解析し、存在する場合は相互作用の DataSchema によって記述される型、または相互作用の Form の contentType によって記述される型の値を返します。このメソッドは次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
this.[[value]] が undefined でない場合、 promise をその値で resolveし、停止する。
this.data が ReadableStream でない場合、または dataUsed が true である場合、または form が object でない場合、または schema もしくはその type が null または undefined である場合、 promise を NotReadableError で rejectし、停止する。
form.contentType が application/json でなく、かつ form.contentType から [JSON-SCHEMA] へのマッピングが Protocol Bindings で利用できない場合、 promise を NotSupportedError で rejectし、停止する。
reader を、data からリーダーを取得する結果とする。それが例外を throw した場合、 promise をその例外で rejectし、停止する。
bytes を、reader で data からすべての bytes を読み取る結果とする。
dataUsed を true に設定する。
form.contentType が application/json でなく、かつ form.contentType から [JSON-SCHEMA] へのマッピングが Protocol Bindings で利用できる場合、そのマッピングで bytes を変換する。
json を、bytes に対して bytes から JSON を解析するを実行した結果とする。それが throw した場合、 promise をその例外で rejectし、停止する。
[[value]] を、 json と schema に対して check data schema を実行した結果に設定する。それが throw した場合、 promise をその例外で rejectし、停止する。
promise を [[value]] で Resolveする。

呼び出されたとき、次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
data が ReadableStream でない場合、または dataUsed が true である場合、 promise を NotReadableError で rejectし、停止する。
reader を、data からリーダーを取得する結果とする。それが例外を throw した場合、 promise をその例外で rejectし、停止する。
bytes を、reader で data からすべての bytes を読み取る結果とする。
dataUsed を true に設定する。
arrayBuffer を、内容が bytes である新しい ArrayBuffer とする。それが throw した場合、 promise をその例外で rejectし、停止する。
promise を arrayBuffer で Resolveする。

payload と schema に対して check data schema 手順を実行するには、

type を schema.type とする。
type が "null" であり、 payload が null でない場合、 TypeError を throw して停止する。そうでなければ null を返す。
type が "boolean" であり、 payload が falsy 値であるか、その byte length が 0 である場合は false を返し、そうでなければ true を返す。
type が "integer" または "number" である場合、
1. payload が number でない場合、 TypeError を throw して停止する。
2. form.minimum が定義されており payload がそれより小さい場合、または form.maximum が定義されており payload がそれより大きい場合、 RangeError を throw して停止する。
type が "string" である場合、 payload を返す。
type が "array" である場合、次のサブ手順を実行する:
1. payload が array でない場合、 TypeError を throw して停止する。
2. form.minItems が定義されており payload.length がそれ未満である場合、または form.maxItems が定義されており payload.length がそれより多い場合、 RangeError を throw して停止する。
3. payload を、payload の各要素 item と schema.items に対して check data schema 手順を実行して得られる items の array とする。これがいずれかの段階で throw した場合、その例外を再 throw して停止する。
type が "object" である場合、次のサブ手順を実行する:
1. payload または schema.properties が object でない場合、 TypeError を throw して停止する。
2. payload 内の各 key について:
  1. prop を payload[key] とする。
  2. propSchema を interaction.properties[key] とする。
  3. prop を、prop と propSchema に対して check data schema 手順を実行した結果とする。これが throw した場合、その例外を再 throw して停止する。
3. required を、schema.required が array である場合はそれとし、そうでない場合は空 array とする。
4. required 内の各 key について、 key が payload 内に存在しない場合、 SyntaxError を throw して停止する。
payload を返す。

与えられた ConsumedThing オブジェクト thing について、 source、form および schema が与えられたときに create interaction request を行うため、次の手順を実行する:

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 を throw して停止する。
2. type が "boolean" であり、 source が falsy 値である場合、 idata.[[value]] を false に設定し、そうでない場合は true に設定する。
3. type が "integer" または "number" であり、 source が number でない場合、または form.minimum が定義されており source がそれより小さい場合、または form.maximum が定義されており source がそれより大きい場合、 RangeError を throw して停止する。
4. type が "string" であり、 source が string でない場合、idata.[[value]] を、 source が与えられたときに JSON を bytes にシリアライズするを実行した結果とする。それが failure である場合、 SyntaxError を throw して停止する。
5. type が "array" である場合、次のサブ手順を実行する:
  1. source が array でない場合、 TypeError を throw して停止する。
  2. length を source の length とする。
  3. form.minItems が定義されており length がそれ未満である場合、または form.maxItems が定義されており length がそれより多い場合、 RangeError を throw して停止する。
  4. source 内の各 item について、 itemschema を schema.items とし、 item を、item, form および itemschema が与えられたときに create interaction request 手順を実行した結果とする。これが throw した場合、その例外を再 throw して停止する。
  5. data.[[value]] を source に設定する。
6. type が "object" である場合、次のサブ手順を実行する:
  1. source が object でない場合、 TypeError を throw して停止する。
  2. schema.properties が object でない場合、 TypeError を throw して停止する。
  3. source 内の各 key について、
    1. value を source[key] とする。
    2. propschema を properties.interactions[key] とする。
    3. value を、value, form および propschema に対して create interaction request 手順を実行した結果とする。これが throw した場合、その例外を再 throw して停止する。
  4. schema.required が array である場合、required 内の各 item について、 item が source 内の property name であるか確認する。 item が source 内に見つからない場合、 SyntaxError を throw して停止する。
  5. data.[[value]] を source に設定する。
idata.data を、 idata.[[value]] internal slot をその underlying source として作成された新しい ReadableStream に設定する。
idata を返す。

与えられた ConsumedThing オブジェクト thing について、 response, form および schema が与えられたときに parse interaction response を行うため、次の手順を実行する:

result を新しい InteractionOutput オブジェクトとする。
result.schema を schema とする。
result.form を form とする。
result.data を、 response のペイロードデータをその underlying source とする新しい ReadableStream とする。
result.dataUsed を false とする。
result を返す。

次の図に示されているように、 InteractionOutput インターフェイスは、実装がスクリプトにデータを提供するたびに使用され、一方で InteractionInput は、スクリプトが実装にデータを渡すときに使用されます。

ConsumedThing がデータを読み取るとき、実装から InteractionOutput オブジェクトとしてデータを受け取ります。

ExposedThing の read handler は、読み取られるデータを InteractionInput として実装に提供します。

ConsumedThing がデータを書き込むとき、それを InteractionInput として実装に提供します。

ExposedThing の write handler は、実装から InteractionOutput オブジェクトとしてデータを受け取ります。

アクションの呼び出し — 図 3 Action を呼び出すときに使用されるデータ構造

ConsumedThing が Action を呼び出すとき、パラメーターを InteractionInput として提供し、Action の出力を InteractionOutput オブジェクトとして受け取ります。

ExposedThing の action handler は、実装から引数を InteractionOutput オブジェクトとして受け取り、 Action の出力を InteractionInput として実装に提供します。

この API のアルゴリズムは、アプリケーションスクリプトに報告されるエラーを定義します。

他方の通信エンドに報告されるエラーは、 Protocol Bindings によってマッピングされ、カプセル化されます。

編集者注

このトピックは Issue #200 でまだ議論されています。スクリプトエラーからプロトコルエラーへ、またその逆へのマッピングの一貫性を確保するためには、標準化されたエラーマッピングが必要です。特に、アルゴリズムが「Protocol Bindings から受け取ったエラー」と述べる場合、それは明示的なエラーマッピングアルゴリズムとして切り出される予定です。現時点では、それは実装によってカプセル化されています。

Thing を操作するためのクライアント 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 オブジェクトは、次の internal slots を持ちます:

内部スロット	初期値	説明（非規範的）
[[td]]	`null`	`ConsumedThing` の Thing Description。
[[activeSubscriptions]]	`{}`	Event を表す string name で keyed された ordered map であり、 value は `Subscription` オブジェクトです。
[[activeObservations]]	`{}`	Property を表す string name で keyed された ordered map であり、 value は `Subscription` オブジェクトです。

フェッチした Thing Description を JSON オブジェクトとして取得した後、 ConsumedThing オブジェクトを作成できます。

ThingDescription td を用いて ConsumedThing を作成するには、次の手順を実行します:

td に対して validate a TD 手順を実行する。失敗した場合、 SyntaxError をthrow して停止する。
td に対して expand a TD 手順を実行する。失敗した場合、そのエラーを再throw して停止する。
thing を、新しい ConsumedThing オブジェクトとする。
thing の internal slot [[td]] を td に設定する。
thing を返す。

ConsumedThing の Thing Description を表す ConsumedThing オブジェクトの [[td]] を返します。アプリケーションは、相互作用する前にその機能を内省するため、 [[td]] に格納された Thing metadata を参照できます。

Property 値を読み取ります。引数として propertyName と、任意で options を取ります。 Property 値を InteractionOutput オブジェクトとして表したもので解決される、またはエラーで拒否される


        Promise

を返します。このメソッドは次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
interaction を [[td]].properties.propertyName とする。
interaction が undefined の場合、 promise を NotFoundError でrejectし、停止する。
option.formIndex が定義されている場合、 form を interaction.forms array 内の formIndex に関連付けられた Form とする。そうでない場合、 form を interaction.forms 内で op が readproperty である Form とし、実装によって選択されるものとする。
form が failure の場合、 promise を SyntaxError でrejectし、停止する。
form と options.uriVariables に与えられた任意の URI templates を用いて、 propertyName Property の値を取得するため、基盤となるプラットフォーム（ Protocol Bindings 経由）へリクエストを行う。
リクエストが失敗した場合、 promise を Protocol Bindings から受け取ったエラーで rejectし、停止する。
response を、リクエストに対して受信した応答とする。
data を、response、 form および interaction に対して parse interaction response を実行した結果とする。失敗した場合、 promise を SyntaxError でrejectし、停止する。
promise を data で Resolveする。

1 つのリクエストで複数の Property 値を読み取ります。引数として propertyNames と、任意で options を取ります。このアルゴリズムによって返された値へ propertyNames のキーをマッピングする PropertyReadMap オブジェクトで解決される


        Promise

を返します。このメソッドは次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
option.formIndex が定義されている場合、 form を [[td]].forms array 内の formIndex に関連付けられた Form とする。そうでない場合、 form を [[td]].forms array 内で op が readmultipleproperties である Form とし、実装によって選択されるものとする。
form が failure の場合、 promise を SyntaxError でrejectし、停止する。
result を object とし、 propertyNames 内の各 string name について、 key が name で、値が null である property を追加する。
form と options' uriVariables に与えられた任意の URI templates を用いて、 propertyNames で与えられた Property 値を取得するため、基盤となるプラットフォーム（ Protocol Bindings 経由）へリクエストを行う。
これを Protocol Bindings で単一のリクエストとして実行できない場合、 promise を NotSupportedError で rejectし、停止する。
応答を処理し、result 内の各 key について、次のサブ手順を実行する:
1. value を result[key] とする。
2. schema を this.[[td]].properties[key] とする。
3. property を、value、 form および schema に対して parse interaction response を実行した結果とする。
上記の手順がいずれかの時点で throw した場合、 promise をその例外で rejectし、停止する。
promise を result で Resolveする。

1 つのリクエストで Thing のすべての properties を読み取ります。任意引数として options を取ります。このアルゴリズムによって返された値へ Property names のキーをマッピングする PropertyReadMap オブジェクトで解決される


        Promise

を返します。このメソッドは次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
forms を subscription.[[interaction]].forms とする。
forms が undefined の場合、 promise を SyntaxError でrejectし、停止する。
option.formIndex が undefined でなく、かつ forms.length より小さい場合、 subscription.[[form]] を forms.[formIndex] に設定する。
そうでない場合、 subscription.[[form]] を、 forms 内で op が "readallproperties" である Form に設定し、実装によって選択されるものとする。
subscription.[[form]] が failure の場合、 promise を SyntaxError でrejectし、停止する。
form と options.uriVariables 内の任意の URI templates を用いて、 TD からすべての Property 定義を取得するため、 Protocol Bindings を使用して基盤となるプラットフォームへリクエストを行う。
Thing の Protocol Bindings でこれを単一のリクエストとして実行できない場合、 promise を NotSupportedError で rejectし、停止する。
リクエストが失敗した場合、 promise を Protocol Bindings から受け取ったエラーで rejectし、停止する。
応答を処理し、result を、応答で得られたキーと値を持つ object とする。
応答を処理し、result 内の各 key について、次のサブ手順を実行する:
1. value を result[key] とする。
2. schema を this.[[td]].properties[key] とする。
3. property を、value、 form および schema に対して parse interaction response を実行した結果とする。
promise を result で Resolveする。

単一の Property を書き込みます。引数として propertyName、 value、および任意で options を取ります。成功時に解決され、失敗時に拒否される


        Promise

を返します。このメソッドは次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
interaction を this.[[td]].properties[propertyName] とする。
interaction が undefined の場合、 promise を NotFoundError でrejectし、停止する。
option.formIndex が undefined でない場合、form を interaction.forms array 内の formIndex に関連付けられた Form とする。そうでない場合、form を interaction.forms 内で op が writeproperty である Form とし、実装によって選択されるものとする。
form が failure の場合、 promise を SyntaxError でrejectし、停止する。
data を、value、 form および interaction が与えられたときに create interaction request 手順を実行した結果とする。それが throw した場合、 promise をその例外で rejectし、停止する。
data と options' uriVariables に与えられた任意の URI templates を用いて、 propertyName で与えられた Property を書き込むため、基盤となるプラットフォーム（ Protocol Bindings 経由）へリクエストを行う。
リクエストが失敗した場合、 promise を Protocol Bindings から受け取ったエラーで rejectし、停止する。
そうでなければ、 promise を resolveする。

編集者注

Issue #193 で議論されているように、設計上の判断として、write interactions は成功またはエラーのみを返し、書き込まれた値は（任意でも）返しません。 TD は、精度や代替形式を含め、 Property 値の schema を捕捉するべきです。相互作用から戻り値が期待される場合は、 Property の代わりに Action を使用するべきです。

1 つのリクエストで複数の Property 値を書き込みます。引数として、キーが Property names であり、値が Property values である object としての properties と、任意で options を取ります。成功時に解決され、失敗時に拒否される


        Promise

を返します。このメソッドは次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
option.formIndex が定義されている場合、 form を [[td]].forms array 内の formIndex に関連付けられた Form とする。そうでない場合、 form を [[td]].forms array 内で op が writemultipleproperties である Form とし、実装によって選択されるものとする。
form が failure の場合、 promise を SyntaxError でrejectし、停止する。
propertyNames を、 properties object のキーを要素とする string の array とする。
propertyNames 内の各 name について、 property を this.[[td]].properties[name] とする。
property が null または undefined である場合、または writeable でない場合、 promise を NotSupportedError で rejectし、停止する。
result を object とし、 propertyNames 内の各 string name について、 key が name で、その値が null である property を追加する。
schemas を object とし、 propertyNames 内の各 name について、 key が name で、その値が this.[[td]].properties[name] である property を追加する。
properties 内の各 key key について、 properties[key]、form および schema[key] の値が与えられたときに create interaction request 手順を実行する。いずれかの name についてそれが throw した場合、 promise をその例外で reject して停止する。
options' uriVariables に与えられた任意の URI templates を用いて、 properties で提供される各 Property を書き込むため、基盤となるプラットフォーム（ Protocol Bindings 経由）へ単一のリクエストを行う。
Thing の Protocol Bindings でこれを単一のリクエストとして実行できない場合、 promise を NotSupportedError で rejectし、停止する。
リクエストが失敗した場合、 Protocol Bindings から受け取ったエラーを返し、停止する。
そうでなければ、 promise を resolveする。

Property 値の変更通知を要求します。引数として propertyName、 listener、および任意で onerror と options を取ります。成功時に解決され、失敗時に拒否される


        Promise

を返します。

編集者注

このアルゴリズムは、各 Property ごとに有効な Subscription を 1 つだけ許可します。既存の Subscription が有効な間に新しい Subscription が作成されると、runtime は NotAllowedError を throw します。

このメソッドは次の手順を実行しなければなりません（MUST）:

thing を、この ConsumedThing オブジェクトの参照とする。
Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
listener が Function でない場合、 promise を TypeError で rejectし、停止する。
onerror が null でなく、かつ Function でない場合、 promise を TypeError で rejectし、停止する。
thing.[[activeObservations]][propertyName] [=map/exists] の場合、 promise を NotAllowedError で rejectし、停止する。
subscription を、次のように internal slots を設定した新しい Subscription オブジェクトとする:
- subscription.[[type]] を "property" とする。
- subscription.[[name]] を propertyName とする。
- subscription.[[interaction]] を [[td]].properties[propertyName] とする。
- subscription.[[thing]] を thing とする。
- forms を subscription.[[interaction]].forms とする。
- forms が undefined の場合、 promise を SyntaxError で rejectし、停止する。
- option.formIndex が undefined でなく、かつ forms.length より小さい場合、 subscription.[[form]] を forms.[formIndex] に設定する。
- そうでない場合、 subscription.[[form]] を forms 内で op が "observeproperty" である Form に設定し、実装によって選択されるものとする。
- subscription.[[form]] が failure の場合、 promise を SyntaxError で rejectし、停止する。
- subscription.[[interaction]] が undefined の場合、 promise を NotFoundError で rejectし、停止する。
form と options' uriVariables に与えられた任意の URI templates を用いて、 propertyName で識別される Property を監視するため、基盤となるプラットフォームへリクエストを行う。
リクエストが失敗した場合、 promise を Protocol Bindings から受け取ったエラーで rejectし、停止する。
thing.[[activeObservations]][|propertyName] を subscription に Set し、 promise を resolveする。
基盤となるプラットフォームが、この subscription について propertyName で keyed された通知を、新しい Property 値 value とともに検出するたびに、次のサブ手順を実行する:
- reply を、 value、 subscription.[[form]] および subscription.[[interaction]] を用いて parse interaction response を実行した結果とする。それが throw した場合、 promise をその例外で rejectし、停止する。
- reply が与えられた listener を呼び出す。
基盤となるプラットフォームがこの subscription のエラーを検出するたびに、次のサブ手順を実行する:
- エラーが回復不能で subscription を停止する場合、 subscription.active を false に設定し、それ以降の通知を抑制する。
- error を新しい NetworkError とし、その message を基盤となるエラー条件を反映するように設定する。
- onerror が Function である場合、error が与えられたそれを呼び出す。

Action の呼び出しを要求し、結果を返します。引数として actionName、任意で params、および任意で options を取ります。 Action の結果を InteractionOutput オブジェクトとして表したもので解決される、またはエラーで拒否される


        Promise

を返します。このメソッドは次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
interaction を this.[[td]].actions[actionName] とする。
interaction が object でない場合、 promise を NotFoundError でrejectし、停止する。
forms を subscription.[[interaction]].forms とする。
forms が undefined の場合、 promise を SyntaxError でrejectし、停止する。
option.formIndex が undefined でなく、かつ forms.length より小さい場合、 subscription.[[form]] を forms.[formIndex] に設定する。
そうでない場合、 subscription.[[form]] を、 forms 内で op が "invokeaction" である Form に設定し、実装によって選択されるものとする。
subscription.[[form]] が failure の場合、 promise を SyntaxError でrejectし、停止する。
args を、 params、 form および interaction に対して create interaction request 手順を実行した結果とする。それが throw した場合、 promise をその例外で rejectし、停止する。
args と options.uriVariables が与えられたときに、 actionName で識別される Action を呼び出すため、基盤となるプラットフォーム（ Protocol Bindings 経由）へリクエストを行う。
リクエストがローカルで失敗するか、ネットワーク越しにエラーを返した場合、 promise を Protocol Bindings から受け取ったエラーで rejectし、停止する。
value を、reply で返された応答とする。
result を、 value、 form および interaction を用いて parse interaction response を実行した結果とする。それが throw した場合、 promise をその例外で rejectし、停止する。
promise を result で Resolveする。

Event 通知への購読を要求します。引数として eventName、 listener、および任意で onerror と options を取ります。成功または失敗を通知する


        Promise

を返します。

編集者注

このアルゴリズムは、各 Event ごとに有効な Subscription を 1 つだけ許可します。既存の Subscription が有効な間に新しい Subscription が作成されると、runtime は NotAllowedError を throw します。

このメソッドは次の手順を実行しなければなりません（MUST）:

thing を、この ConsumedThing オブジェクトの参照とする。
Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
listener が Function でない場合、 promise を TypeError で rejectし、停止する。
onerror が null でなく、かつ Function でない場合、 promise を TypeError で rejectし、停止する。
thing.[[activeSubscriptions]][eventName] が存在しない場合、 promise を NotAllowedError で rejectし、停止する。
subscription を、次のように internal slots を設定した新しい Subscription オブジェクトとする:
- subscription.[[type]] を "event" とする。
- subscription.[[name]] を eventName とする。
- subscription.[[interaction]] を thing. [[td]].events[eventName] とする。
- subscription.[[interaction]] が undefined の場合、 promise を NotFoundError で rejectし、停止する。
- subscription.[[thing]] を thing とする。
- options.formIndex が存在する場合、 subscription.[[form]] を thing.[[interaction]].forms[formIndex] とする。
- そうでない場合、 subscription.[[form]] を、 subscription.[[interaction]].forms array からの、op が "subscribeevent" である実装定義の Form とする。
- subscription.[[form]] が存在しない場合、 promise を SyntaxError で rejectし、停止する。
[[form]]、 options.uriVariables に与えられた任意の URI templates、および options.data に与えられた任意の subscription data を用いて、 eventName で識別される Event を購読するため、 Protocol Bindings 経由で基盤となるプラットフォームへリクエストを行う。
リクエストが失敗した場合、 promise を Protocol Bindings から受け取ったエラーで rejectし、停止する。
eventName を thing.[[activeSubscriptions]][eventName] から subscription へ Setする。
promise を Resolveする。
基盤となるプラットフォームが、 eventName で keyed された Event subscription の通知を検出するたびに、次のサブ手順を実行する:
1. Event とともに提供されたデータ、 subscription.[[form]] および subscription.[[interaction]] に対して parse interaction response を実行した結果を与えて、 listener を呼び出す。
基盤となるプラットフォームが、 eventName で keyed された Event subscription のエラーを検出するたびに、次のサブ手順を実行する:
- エラーが回復不能で subscription を停止する場合、 subscription.active を false に設定し、それ以降の通知を抑制する。
- error を新しい NetworkError とし、その message を基盤となるエラー条件を反映するように設定する。
- onerror が Function である場合、error が与えられたそれを呼び出す。

Thing Description に従ってアプリケーションスクリプトに公開する必要がある interaction options を保持します。

formIndex プロパティは、定義されている場合、与えられた WoT interaction に対して使用する TD の Form 定義のうち、この index によって識別されるものについてのアプリケーション hint を表します。実装は interaction を行うためにこの index の Form を使用するべきですが（SHOULD）、 index が見つからないか有効でない場合、この値を上書きしてもよいです（MAY）。定義されていない場合、実装は、与えられた Wot Interaction について TD に列挙されている出現順に Form 定義を使用するよう試みるべきです（SHOULD）。

uriVariables プロパティは、定義されている場合、 [WOT-TD] で定義される解析済み JSON オブジェクトとして表される、WoT Interaction で使用される URI template variables を表します。

編集者注

URI variables のサポートは、 Web of Things (WoT) Thing Description 1.1 仕様によって明らかにされた、それらを使用する既存の RESTful endpoints を記述できるようにする必要性に由来します。しかし、この種類の interactions を表現するために Action を使用し、 URI variables を action parameters としてモデル化する Thing Description を書くことも可能であるべきです。その場合、実装は parameters を URI variables としてシリアライズできるため、 options parameter は不要にできます。

data プロパティは、定義されている場合、interaction に渡す必要がある追加の opaque data を表します。

Property names から、 Property が取り得る値を表す InteractionOutput オブジェクトへの map を表します。複数の Properties が同時に関与する interactions の property bag として使用されます。

Property names から、 Property が取り得る値を表す InteractionInput への map を表します。複数の Properties が同時に関与する interactions の property bag として使用されます。

ユーザーが提供する callback であり、型 InteractionOutput の引数が与えられ、 Property changes の監視および Event notifications の処理に使用されます。 Events への購読は WoT interactions であり、 options や data さえ取る可能性があるため、software events としてモデル化されません。

ユーザーが提供する callback であり、型 Error の引数が与えられ、 Protocol Bindings からアプリケーションへ重大および非重大なエラーを伝達するために使用されます。

Property change および Event interactions への subscription を表します。

active boolean プロパティは、subscription が active であるかどうか、すなわちエラーや stop() メソッドの呼び出しによって停止されていないかどうかを示します。

Subscription オブジェクトは、次の internal slots を持ちます:

内部スロット	初期値	説明（非規範的）
[[type]]	`null`	`Subscription` がどの WoT Interaction を参照するかを示します。値は `"property"`、`"event"`、または `null` のいずれかです。
[[name]]	`null`	Property または Event name。
[[interaction]]	`null`	WoT interaction を記述する Thing Description fragment。
[[form]]	`null`	subscription に関連付けられた Form。
[[thing]]	`null`	subscription に関連付けられた `ConsumedThing`。

subscription への通知の配信を停止します。任意 parameter options を取り、 Promise を返します。呼び出されたとき、このメソッドは次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
options' の formIndex が定義されている場合、 unsubscribeForm を [[interaction]]'s forms array 内の formIndex に関連付けられた Form とする。
そうでない場合、unsubscribeForm を [[form]] が与えられたときに find a matching unsubscribe form アルゴリズムを実行した結果とする。
unsubscribeForm が failure の場合、 promise を SyntaxError でrejectし、停止する。
[[type]] が "property" である場合、 unsubscribeForm と options' の uriVariables に与えられた任意の URI templates を用いて、 [[name]] で識別される Property の監視を停止するため、 Protocol Bindings 経由で基盤となるプラットフォームへリクエストを行う。
そうでなく、[[type]] が "event" である場合、 unsubscribeForm、 options' の uriVariables に与えられた任意の URI templates、および options.data に与えられた任意の unsubscribe data を用いて、 [[name]] で識別される Event の購読を解除するため、 Protocol Bindings 経由で基盤となるプラットフォームへリクエストを行う。
リクエストが失敗した場合、 promise を Protocol Bindings から受け取ったエラーで rejectし、停止する。
そうでなければ:
- active を false に設定する。
- [[type]] が "event" である場合、 [[thing]].[[activeSubscriptions]] から [[name]] を削除する。
- [[type]] が "property" である場合、 [[thing]].[[activeObservations]] から [[name]] を削除する。
- promise を Resolveする。
基盤となるプラットフォームがこの subscription について追加の通知を受信した場合、実装はそれらを静かに抑制するべきです（SHOULD）。

注

このアルゴリズムは開発中であり、 非規範的です。実装は、与えられた subscribe Form に一致する unsubscribe Form を検索するために、別のアルゴリズムを選択してもよいです（MAY）。

Subscription オブジェクトのコンテキストで subscribeForm が与えられたときに、一致する unsubscribe form を検索するには、次の手順を実行します:

results を空 array とする。
[[interaction]].forms 内の各 form について、
1. form 上に internal slot [[matchLevel]] を追加し、その値を 0 に設定する。
2. [[type]] が "property" の場合に form.op が "unobserveproperty" である場合、または [[type]] が"event" の場合に form.op が "unsubscribeevent" である場合、
  1. form 上の internal slot [[matchLevel]] を 1 に設定し、 form を results に追加する。
  2. form.href と [[subscribeForm]].href が same origin-domain の場合、 form.[[matchLevel]] を増分する。
  3. form.contentType が [[subscribeForm]] の contentType と等しく、かつ form.[[matchLevel]] が 2 より大きい場合、 form.[[matchLevel]] を増分する。
results が空の場合、 null を返し、これらの手順を終了する。
results 内で最も高い [[matchLevel]] 値を持つ最初の form を返す。

次の例は、URL によって TD をフェッチし、 ConsumedThing を作成し、metadata（title）を読み取り、property 値を読み取り、property change に購読し、 WoT event に購読し、購読解除する方法を示します。

例 2: data value を用いた Thing Client API の例

try {
  let res = await fetch("https://tds.mythings.org/sensor11");
  let td = res.json();
  let thing = new ConsumedThing(td);
  console.log("Thing " + thing.getThingDescription().title + " consumed.");
} catch (e) {
  console.log("TD fetch error: " + e.message);
};

try {
  // subscribe to property change for “temperature”
  await thing.observeProperty("temperature", async (data) => {
    try {
      console.log("Temperature changed to: " + await data.value());
    } catch (error) {
      console.error("Cannot read the observed property temperature");
      console.error(error);
    }
  });
  // subscribe to the “ready” event defined in the TD
  await thing.subscribeEvent("ready", async (eventData) => {
    try {
      console.log("Ready; index: " + await eventData.value());
      // run the “startMeasurement” action defined by TD
      await thing.invokeAction("startMeasurement", { units: "Celsius" });
      console.log("Measurement started.");
    } catch (error) {
      console.error("Cannot read the ready event or startMeasurement failed");
      console.error(error)
    }
  });
} catch (e) {
  console.log("Error starting measurement.");
}

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

    await thing.unsubscribe("ready");
    console.log("Unsubscribed from the ‘ready’ event.");
  } catch (error) {
    console.log("Error in the cleanup function");
  }
}, 10000);

次に示すのは、 DataSchema なしで property を読み取るための InteractionOutput の高度な使用法です。

例 3: arrayBuffer を用いた Thing Client API の例

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

最後に、次の 2 つの例は、 InteractionOutput からの ReadableStream の使用法を示します。

例 4: readable stream（例: video stream）を用いた Thing Client 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("live video stoped");
    return;
  }
  const decoded = decode(value)
  UI.show(decoded)
  // Read some more, and call this function again
  return reader.read().then(processText);
});

ここでは、JSON オブジェクトが大きすぎてメモリ内で全体を読み取れないと考えます。したがって、リモート Web Thing によって記録された events の総数を取得するために、 streaming processing を使用します。

例 5: readable stream（例: counting json objects）を用いた Thing Client API の例

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

// Example of streaming processing: counting json objects
let objectCounter = 0
const parser = new Parser() //User library for json streaming parsing (i.e. https://github.com/uhop/stream-json/wiki/Parser)

parser.on('data', data => data.name === 'startObject' && ++objectCounter);
parser.on('end', () => console.log(`Found ${objectCounter} objects.`));

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

// Found N objects

ExposedThing インターフェイスは、request handlers、Property、Action、および Event interactions の定義を可能にする Thing を操作するためのサーバー 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 オブジェクトは、次の internal slots を持ちます:

内部スロット	初期値	説明（非規範的）
[[td]]	`null`	`ExposedThing` の Thing Description。
[[readHandlers]]	`{}`	property names をキーとし、 `PropertyReadHandler`s を値とする `Map`
[[writeHandlers]]	`{}`	property names をキーとし、 `PropertyWriteHandler`s を値とする `Map`
[[observeHandlers]]	`{}`	property names をキーとし、 `PropertyReadHandler`s を値とする `Map`
[[unobserveHandlers]]	`{}`	property names をキーとし、 `Function`s を値とする `Map`
[[actionHandlers]]	`{}`	action names をキーとし、 `ActionHandler`s を値とする `Map`
[[subscribeHandlers]]	`{}`	event names をキーとし、 `EventSubscriptionHandler`s を値とする `Map`
[[unsubscribeHandlers]]	`{}`	event names をキーとし、 `EventSubscriptionHandler`s を値とする `Map`
[[propertyObservers]]	`{}`	property names をキーとし、listeners の `Array` を値とする `Map`
[[eventListeners]]	`{}`	event names をキーとし、listeners の `Array` を値とする `Map`

ExposedThing インターフェイスは ConsumedThing を拡張します。これは完全または部分的な ThingDescription オブジェクトから構築されます。

注

既存の ThingDescription オブジェクトは任意で変更できることに注意してください（たとえば、その properties、 actions、および events 内部 properties に要素を追加または削除することによって）。その結果のオブジェクトを ExposedThing オブジェクトの構築に使用できます。これは、Property、Action、および Event 定義を追加および削除する現在の方法であり、例で示されています。

注

expose() を呼び出す前は、 ExposedThing オブジェクトは一切のリクエストを処理しないことに注意してください。これにより、まず ExposedThing を構築し、次に requests の処理を開始する前にその Properties と service handlers を初期化できます。

ExposedThingInit init を用いて ExposedThing を構築するには、次の手順を実行します:

セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 SecurityError をthrow して停止する。
init に対して expand an ExposedThingInit 手順を実行する。それが失敗した場合、 error を再throw して停止する。そうでない場合、得られた td を保存する
td に対して expand a TD 手順を実行する。それが失敗した場合、error を再throw して停止する。
thing を、新しい ExposedThing オブジェクトとする。
thing の [[td]] を td に設定する。
thing を返す。

Thing の Thing Description を表す ExposedThing オブジェクトの [[td]] を返します。アプリケーションは、それと相互作用する前にその機能を内省するため、 [[td]] に格納された Thing metadata を参照できます。

Property を読み取る外部リクエストを受信したときに呼び出され、そのような requests に対して何を行うかを定義する関数です。 Promise を返し、 ReadableStream オブジェクト、または DataSchema に適合する ECMAScript value で解決されるか、error で拒否されます。

引数として name と handler を取ります。 name に一致する指定された Property の読み取りリクエストを受信したときに何を行うかを定義する service handler を設定します。 error 時に throw します。chaining をサポートするために this オブジェクトへの参照を返します。

編集者注

複数またはすべての Properties の読み取り requests を処理するために handlers を登録する必要はないことに注意してください。request と reply は単一の network request で送信されますが、 ExposedThing は単一 read handler への複数回の呼び出しを使用してそれらを実装できます。

handler callback function は Property の読み取りを実装するべきであり（SHOULD）、基盤となるプラットフォームから Property を読み取る request が受信されたとき、実装によって呼び出されるべきです。

任意の与えられた Property について handler は最大 1 つでなければならないため（MUST）、新しく追加された handlers は以前の handlers を置き換えなければなりません（MUST）。任意の与えられた Property について handler が初期化されていない場合、実装は [[td]] internal slot に提供された Thing Description に基づく default property read handler を実装するべきです（SHOULD）。

name と handler が与えられてこのメソッドが呼び出されたとき、実装は次の手順を実行しなければなりません（MUST）:

セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 SecurityError をthrow して停止する。
[[td]].properties[name] が存在しない場合、 NotFoundError をthrow して停止する。
this.[[readHandlers]][name] を handler に設定する。

Property name を読み取る network request が options とともに実装によって受信されたとき、次の手順を実行します:

この operation がサポートされていない場合、 Protocol Bindings に従って NotSupportedError を返送して停止する。
この operation が許可されていない場合、 Protocol Bindings に従って NotAllowedError を返送して停止する。
value を、name と options を用いて server property を読み取る手順を実行した結果とする:
1. interaction を [[td]].properties.name とする。
2. name を持つ Property が存在しない場合、 NotFoundError を throw して停止する。
3. handler を null とする。
4. interaction について [[readHandlers]] internal slot 内に、ユーザー提供の PropertyReadHandler が存在する場合、 handler をそれとする。
5. そうでなく、実装によって提供される default read handler が存在する場合、 handler をそれとする。
6. handler が null の場合、 NotSupportedError を throw して停止する。
7. value を、 options を与えて handler を呼び出した結果とする。それが失敗した場合、error を throw して停止する。
8. value を返す。
  
  注
  
  ここで返される value は、 DataSchema に適合するべきであるか（SHOULD）、または handler によって作成された ReadableStream オブジェクトであるべきです（SHOULD）。
前の手順が error を throw した場合、 Protocol Bindings に従って作成された reply で error を返送し、停止する。
返された value をシリアライズし、 Protocol Bindings に従って作成された reply に追加する。

object propertyNames 内で与えられた複数の Properties を読み取る network request が options とともに受信されたとき、 propertyNames と options に対して次の複数 properties を読み取る手順を実行します:

この operation がサポートされていない場合、 Protocol Bindings に従って NotSupportedError を返送して停止する。
この operation が許可されていない場合、 Protocol Bindings に従って NotAllowedError を返送して停止する。
propertyNames に定義された key name を持つ各 property について、
1. value を、name と options に対して server property を読み取る手順を実行した結果とする。それが throw した場合、 Protocol Bindings に従って作成された reply で error を返送し、停止する。
2. propertyNames.name を value に設定する。
Protocol Bindings に従って propertyNames から作成された単一の reply を送信することで、 request に応答する。

すべての Properties を読み取る network request が options とともに受信されたとき、次の手順を実行します:

この operation がサポートされていない場合、 Protocol Bindings に従って NotSupportedError を返送して停止する。
この operation が許可されていない場合、 Protocol Bindings に従って NotAllowedError を返送して停止する。
properties を、Thing に定義されたすべての properties から作成され、値が null に設定された object とする。
properties と options に対して複数 properties を読み取る手順を実行する。

引数として name と handler を取ります。 name に一致する指定された Property の観測 request を受信したときに何を行うかを定義する service handler を設定します。 error 時に throw します。chaining をサポートするために this オブジェクトへの参照を返します。

handler callback function は Property の読み取りを実装し、 InteractionOutput オブジェクトでresolveするか、 error でrejectするべきです。

任意の与えられた Property について handler は最大 1 つでなければならないため（MUST）、新しく追加された handlers は以前の handlers を置き換えなければなりません（MUST）。任意の与えられた Property について handler が初期化されていない場合、実装は Thing Description に基づく default property read handler を実装するべきです（SHOULD）。

name と handler が与えられてこのメソッドが呼び出されたとき、実装は次の手順を実行しなければなりません（MUST）:

セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 SecurityError をthrow して停止する。
this.[[td]].properties[name] が存在しない場合、 NotFoundError をthrow して停止する。
this[[observeHandlers]][name] を handler に設定する。

Property name を観測する network request が options とともに実装によって受信されたとき、次の手順を実行します:

この operation がサポートされていない場合、 Protocol Bindings に従って NotSupportedError を返送して停止する。
この operation が許可されていない場合、 Protocol Bindings に従って NotAllowedError を返送して停止する。
this.[[td]].properties[name] が存在しない場合、 reply 内に NotFoundError を返送して停止する。
Property 値の changes を通知できるようにするため、 request sender information を options および this.[[propertyObservers]][name] とともに内部的に保存する。

注

property の値が変化するたびに、 emitPropertyChange() は application script によって明示的に呼び出される必要があります。

引数として name と handler を取ります。 name に一致する指定された Property の unobserving request を受信したときに何を行うかを定義する service handler を設定します。 error 時に throw します。chaining をサポートするために this オブジェクトへの参照を返します。

handler callback function は、unobserve request が実装によって受信されたときに何を行うかを実装するべきです。

任意の与えられた Property について handler は最大 1 つでなければならないため（MUST）、新しく追加された handlers は以前の handlers を置き換えなければなりません（MUST）。任意の与えられた Property について handler が初期化されていない場合、実装は Thing Description に基づく default handler を実装するべきです（SHOULD）。

name と handler が与えられてこのメソッドが呼び出されたとき、実装は次の手順を実行しなければなりません（MUST）:

セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 SecurityError をthrow して停止する。
this.[[td]].properties[name] が存在しない場合、 NotFoundError をthrow して停止する。
this.[[unobserveHandlers]][name] を handler に設定する。

Property name の unobserving network request が options とともに実装によって受信されたとき、次の手順を実行します:

この operation がサポートされていない場合、 Protocol Bindings に従って NotSupportedError を返送して停止する。
この operation が許可されていない場合、 Protocol Bindings に従って NotAllowedError を返送して停止する。
this.[[td]].properties[name] が存在しない場合、 reply 内に NotFoundError を返送して停止する。
handler を this.[[unobserveHandlers]][name] とする。
handler が Function である場合、options が与えられたそれを呼び出し、 Protocol Bindings に従って reply を返送して停止する。
そうでなく、 this.[[propertyObservers]][name] が存在する場合、 this.[[propertyObservers]] からそれを削除し、 Protocol Bindings で定義される reply を返送して停止する。
そうでなければ、 Protocol Bindings で定義される reply 内に NotFoundError を返送して停止する。

Property name を示す name 引数と、任意で data 引数を取ります。指定された Property のすべての observers に、 data 引数で提供された data による notification の発行をトリガーします。提供されない場合、その Property に関連付けられた observe handler または read handler によって取得されます。このメソッドは次の手順を実行しなければなりません（MUST）:

promise を新しい Promise とする。
promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
name を最初の引数とする。
property を this.[[td]].properties[name] とする。
property が undefined の場合、 promise を NotFoundError でrejectし、停止する。
data を第 2 引数とする。
data が undefined の場合、次のサブ手順を実行する:
1. handler を null. とする。
2. name が [[readHandlers]] に存在しない場合、 promise を reject して停止する。
3. handler を [[readHandlers]][name] とする。
4. handler が null または undefined の場合、 promise を reject して停止する。
5. handled を、 null が与えられた handler を呼び出した結果とする。
6. handled が rejected である場合、promise を reject して停止する。
7. そうでなく、handled が value で resolved した場合、data を value とする。
[[propertyObservers]][name] 内の各 observer について、次のサブ手順を実行する:
1. options を、 observer とともに保存された interaction options とする。
2. Protocol Bindings に従って、 data と options から reply を作成するよう、基盤となるプラットフォームに要求する。
  
  編集者注
  
  この節は拡張が必要であり、および/または [WOT-PROTOCOL-BINDINGS] のアルゴリズムを参照する必要があります。
3. reply を observer に送信する。
promise を Resolveする。

Property を書き込む外部リクエストを受信したときに呼び出され、そのような requests に対して何を行うかを定義する関数です。引数として value を取り、 Promise を返します。これは、 handler の設定時に提供された name によって識別される Property の値が更新されたときに解決され、property が見つからない場合または値を更新できない場合には error で拒否されます。

編集者注

この callback function 内の code は、必要に応じて古い値を把握するために、更新前に property を読み取ることができることに注意してください。したがって、この function には古い値は提供されません。

注

値は、streams のような DataSchema によって記述されていない値を表現できるようにするため、実装によって InteractionOutput オブジェクトとして提供されます。

引数として name と handler を取ります。 handler の設定時に与えられた name に一致する Property を書き込む request を受信したときに何を行うかを定義する service handler を設定します。 error 時に throw します。chaining をサポートするために this オブジェクトへの参照を返します。

注

Issue 199 で説明されているように、readonly Properties であっても write handler を指定することが可能であることに注意してください。この場合、 write handler は、request を失敗させる方法をアプリケーション固有の方法で定義してもよいです。

任意の与えられた Property について write handler は最大 1 つでなければならないため（MUST）、新しく追加された handlers は以前の handlers を置き換えなければなりません（MUST）。任意の与えられた Property について write handler が初期化されていない場合、実装は Thing Description に基づいて、 Property が writeable であれば default property update を実装し、 Property が observable であれば change について observers に通知するべきです（SHOULD）。

name と handler が与えられてこのメソッドが呼び出されたとき、実装は次の手順を実行しなければなりません（MUST）:

セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 SecurityError をthrow して停止する。
this.[[td]].properties[name] が存在しない場合、 NotFoundError をthrow して停止する。
this.[[writeHandlers]][name] を handler に設定する。

新しい値 value および options とともに、 Property name を書き込む network request が受信されたとき、実装は、name、 value、 options が与えられ、 mode が "single" に設定された次の property を更新する手順を実行しなければなりません（MUST）:

この operation がサポートされていない場合、 Protocol Bindings に従って NotSupportedError を返送して停止する。
この operation が許可されていない場合、 Protocol Bindings に従って NotAllowedError を返送して停止する。
interaction を this.[[td]].properties[name] とする。
interaction が undefined の場合、 reply 内に NotFoundError を返して停止する。
handler を this.[[writeHandlers]][name] とする。
handler が undefined であり、かつ実装によって提供される default write handler が存在する場合、 handler をそれとする。
handler が undefined の場合、reply とともに NotSupportedError を返送して停止する。
promise を、 name および options が与えられた handler を呼び出した結果とする。失敗した場合、 reply 内に error を返して停止する。
mode が "single" の場合、 Protocol Bindings に従って、成功を報告して request に応答し、停止する。

object propertyNames 内で与えられた複数の Properties を書き込む network request が options とともに受信されたとき、次の手順を実行します:

この operation がサポートされていない場合、 Protocol Bindings に従って NotSupportedError を返送して停止する。
この operation が許可されていない場合、 Protocol Bindings に従って NotAllowedError を返送して停止する。
propertyNames に定義された key name および value value を持つ各 property について、 name、value、 options が与えられ、 mode が "multiple" に設定された property を更新する手順を実行する。それが失敗した場合、その error で request に応答し、停止する。
Protocol Bindings に従って単一の reply を送信することで、 request に応答する。

Action を呼び出す外部 request を受信したときに呼び出され、そのような requests に対して何を行うかを定義する関数です。 params が与えられて呼び出され、任意で options object とともに呼び出されます。 error で拒否されるか、 Action によって返された値を InteractionInput として解決する Promise を返します。

注

Application scripts は ActionHandler から ReadableStream オブジェクトを返してもよいです（MAY）。実装はその場合、stream を使用して Action の response を構築します。

引数として name と action を取ります。 name に一致する Action を呼び出す request を受信したときに何を行うかを定義する handler function を設定します。error 時に throw します。 chaining をサポートするために this オブジェクトへの参照を返します。

action callback function は Action を実装し、基盤となるプラットフォームから Action を呼び出す request を受信したとき、実装によって呼び出されるべきです（SHOULD）。

任意の与えられた Action について handler は最大 1 つでなければならないため（MUST）、新しく追加された handlers は以前の handlers を置き換えなければなりません（MUST）。

name と action が与えられてこのメソッドが呼び出されたとき、次の手順を実行します:

セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 SecurityError をthrow して停止する。
interaction を this.[[td]].actions[name] とする。
interaction が undefined の場合、 NotFoundError をthrow して停止する。
this.[[actionHandlers]][name] を action に設定する。

inputs と任意で options が与えられて、 name で識別される Action を呼び出す network request が受信されたとき、次の手順を実行します:

この operation がサポートされていない場合、 Protocol Bindings に従って NotSupportedError を返送して停止する。
この operation が許可されていない場合、 Protocol Bindings に従って NotAllowedError を返送して停止する。
interaction を this.[[td]].properties[name] とする。
interaction が undefined の場合、 reply 内に NotFoundError を返して停止する。
handler を this.[[actionHandlers]][name] とする。
handler が undefined の場合、 Protocol Bindings に従って作成された reply とともに NotSupportedError を返して停止する。
promise を、 name、inputs、および options が与えられた handler を呼び出した結果とする。
promise が rejects した場合、reply とともに error を送信して停止する。
promise が data で resolves したとき、 Protocol Bindings に従って reply を作成して送信するために data を使用する。

Event に購読する外部 request を受信したときに呼び出され、そのような requests に対して何を行うかを定義する関数です。実装によって提供され、subscribers から来る options object が与えられて呼び出されます。 error で拒否されるか、subscription が受け入れられたときに解決する Promise を返します。

引数として name と handler を取ります。 name に一致する指定された Event に対する subscription request を受信したときに何を行うかを定義する handler function を設定します。error 時に throw します。 chaining をサポートするために this オブジェクトへの参照を返します。

handler callback function は、 subscribe request が受信されたときに何を行うか、たとえば必要な initializations を実装するべきです（SHOULD）。 Events を発行するための handler は別個に設定されることに注意してください。

任意の与えられた Event について event subscribe handler は最大 1 つでなければならないため（MUST）、新しく追加された handlers は以前の handlers を置き換えなければなりません（MUST）。

name と handler が与えられてこのメソッドが呼び出されたとき、次の手順を実行します:

セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 SecurityError をthrow して停止する。
interaction を this.[[td]].events[name] とする。
interaction が undefined の場合、 NotFoundError をthrow して停止する。
this.[[subscribeHandlers]][name] を handler に設定する。
this を返す。

引数として name と handler を取ります。 name に一致する指定された Event が購読解除されたときに何を行うかを定義する handler function を設定します。error 時に throw します。 chaining をサポートするために this オブジェクトへの参照を返します。

handler callback function は、 unsubscribe request が受信されたときに何を行うかを実装するべきです（SHOULD）。

任意の与えられた Event について handler は最大 1 つでなければならないため（MUST）、新しく追加された handlers は以前の handlers を置き換えなければなりません（MUST）。

name と handler が与えられてこのメソッドが呼び出されたとき、次の手順を実行します:

セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 SecurityError をthrow して停止する。
interaction を this.[[td]].events[name] とする。
interaction が undefined の場合、 NotFoundError をthrow して停止する。
this.[[unsubscribeHandlers]][name] を handler に設定する。
this を返す。

name についての Event unsubscribe request が、任意で options とともに基盤となるプラットフォームによって受信されたとき、次の手順を実行します:

この operation がサポートされていない場合、 Protocol Bindings に従って NotSupportedError を返送して停止する。
この operation が許可されていない場合、 Protocol Bindings に従って NotAllowedError を返送して停止する。
interaction を this.[[td]].events[name] とする。
interaction が undefined の場合、 NotFoundError を返送して停止する。
this.[[unsubscribeHandlers]][name] が存在し、かつ Function である場合、 options が与えられたそれを呼び出し、停止する。
そうでなく、name が this.[[eventListeners]] 内に [=map/exists] する場合、 name を remove する。
this を返す。

name name を持つ Event が、emitEvent() メソッドによって data とともに発行されたとき、次の手順を実行します:

listeners を [[eventListeners]].name とする。
listeners 内の各 subscriber について、次のサブ手順を実行する:
1. data と subscriber（その options を含む）から、 Protocol Bindings に従って Event notification response を作成する。
2. data が undefined の場合、notification response は Protocol Bindings によって指定されるとおり、空の data payload を含むと仮定する。
3. 基盤となる protocol stack が event errors の伝達を許可し、かつ UA によって error condition が検出された場合、 Protocol Bindings に従い、 data、 subscriber およびその options を使用して、 response を error notification として作成する。
  
  注
  
  error reporting は protocol specific であり、実装によってカプセル化されます。client 側では、 client UA が error を検出した場合、subscription とともに渡された error listener が呼び出されます。
4. subscriber によって識別される subscriber に response を送信する。

Event name を示す name と、任意で data を引数として取ります。任意の data とともに Event を発行することをトリガーします。このメソッドは次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
interaction を [[td]].events.name とする。
name という name を持つ Event が見つからない場合、 promise を NotFoundError でrejectし、停止する。
任意の data とともに Event を発行するため、基盤となるプラットフォームへリクエストを行う。 events の処理手順を呼び出す。

Thing に対する外部 requests の処理を開始し、 Properties、Actions、および Events を使用する WoT Interactions を可能にします。このメソッドは次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
[[td]] に対して expand a TD 手順を実行する。
[[td]] に対して validate a TD を実行する。それが失敗した場合、 promise を TypeError で rejectし、停止する。
[[td]].properties 内の各 key について、 value changes について observers に通知するために必要な observe request data を格納するため、 this.[[propertyObservers]].key を空の Array に初期化する。
this.[[td]].events 内の各 key について、 event emission について subscribers に通知するために必要な subscribe request data を格納するため、 this.[[eventListeners]].key を空の Array に初期化する。
[WOT-TD] および [WOT-PROTOCOL-BINDINGS] で説明されるとおり、 [[td]] を内省することに基づいて WoT Interactions を設定する。基盤となるプラットフォームに Protocol Bindings を初期化するよう要求し、次に Protocol Bindings に基づいて、 WoT Interactions （Properties の read、write、observe、 Actions の invoke、および Event subscriptions の管理）に対する外部 requests の処理を開始する。実装は任意の理由でこの手順を reject してもよいです（MAY）（例: interaction forms に対して追加の checks と constraints を強制したい場合）。
request 中に error があった場合、 promise を Error object error で rejectし、 error.message を Protocol Bindings によって見られた error code に設定して停止する。
そうでなければ、 promise を resolve して停止する。

Thing に対する外部 requests の処理を停止し、オブジェクトを破棄します。最終的な unregistering は、このメソッドを呼び出す前に行われるべきであることに注意してください。このメソッドは次の手順を実行しなければなりません（MUST）:

Promise promise を返し、次の手順を並列に実行する。
セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 promise を SecurityError でrejectし、停止する。
Protocol Bindings に基づいて、 WoT Interactions に対する外部 requests の処理を停止するため、基盤となるプラットフォームへリクエストを行う。
request 中に error があった場合、 promise を Error object error で rejectし、その message を Protocol Bindings によって見られた error code に設定して停止する。
そうでなければ、 promise を resolve して停止する。

次の例は、事前に構築された部分的な TD object に基づいて ExposedThing を作成する方法を示します。

例 6: 単純な Property を用いた ExposedThing の作成

try {
  let temperaturePropertyDefinition = {
    type: "number",
    minimum: -50,
    maximum: 10000
  };
  let tdFragment = {
    properties: {
      temperature: temperaturePropertyDefinition
    },
    actions: {
      reset: {
        description: "Reset the temperature sensor",
        input: {
          temperature: temperatureValueDefinition
        },
        output: null,
        forms: []
      },
    },
    events: {
      onchange: temperatureValueDefinition
    }
  };
  let thing1 = await WOT.produce(tdFragment);
  // initialize Properties
  await thing1.writeProperty("temperature", 0);
  // add service handlers
  thing1.setPropertyReadHandler("temperature", () => {
     return readLocalTemperatureSensor();  // Promise
  });
  // start serving requests
  await thing1.expose();
} catch (err) {
   console.log("Error creating ExposedThing: " + err);
}

次の例は、既存の ExposedThing 上で Property 定義を追加または変更する方法を示します: その td property を取得し、追加または変更してから、それを用いて別の ExposedThing を作成します。

例 7: object Property の追加

try {
  // create a deep copy of thing1's 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: "Get status object",
    input: null,
    output: {
      status : statusValueDefinition;
    },
    forms: [...]
  };
  instance.events["onstatuschange"] = statusValueDefinition;
  instance.forms = [...];  // update
  var thing2 = new ExposedThing(instance);
  // TODO: add service handlers
  await thing2.expose();
  });
} catch (err) {
   console.log("Error creating ExposedThing: " + err);
}

以下では、 expand an ExposedThingInit 手順を使用して、 ExposedThingInit から Thing Description を生成する一連の例を扱います。仮定として、runtime は HTTP および COAP protocol bindings をサポートし、192.168.0.1 でホストされています。

次の例は、 ExposedThingInit を活用して、default values を持つ 1 つの Property を備えた単純な Thing Description を作成する方法を示します。

例 8: 1 つの Property affordance を備えた Thing Description の作成

{
  "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 が、algorithm によって置き換えられる suggested values を含む例をさらに追加する。

Discovery は、参加する network nodes （clients、servers、directory services）からの provisioning と support を必要とする分散アプリケーションです。この API は、さまざまな IoT deployments によってサポートされる典型的な discovery schemes の client 側をモデル化します。

ThingDiscoveryProcess オブジェクトは、discovery process を制御し、結果を返す properties と methods を提供します。

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 slots を持ちます。

内部スロット	初期値	説明（非規範的）
[[filter]]	`undefined`	discovery で使用される `ThingFilter` オブジェクト。
[[url]]	`undefined`	discovery における TD Directory を表す `URL`。

done property は、discovery が停止されているか、報告すべき結果がもうなく完了している場合に true です。

error property は、discovery process 中に発生した最後の error を表します。通常、discovery を停止する重大な errors に使用されます。

ThingDiscoveryProcess オブジェクトは async iterator 概念を実装します。

filter を用いて ThingDiscoveryProcess を作成するには、次の手順を実行します:

filter が object または null でない場合、 TypeError をthrowして停止する。
discovery を新しい ThingDiscoveryProcess オブジェクトとする。
discovery.[[filter]] を filter に設定する。
discovery.done を false に設定する。
discovery.error を null に設定する。
discovery を返す。

Things を発見するための制約を key-value pairs として含む object を表します。

WebIDLdictionary ThingFilter {
  object? fragment;
  
};

fragment property は、発見された Things に対して property ごとに照合するために使用される template object を表します。

編集者注

query property は、WoT Discovery task force で標準化されるまで、 ThingFilter から一時的に削除されました。これは、実装によって受け入れられる query string、たとえば SPARQL または JSON query を表していました。 Support は WoT Runtime 内でローカルに、または TD Directory 内の service としてリモートに実装される予定でした。

編集者注

url property は削除されました。これは、discovery request を処理する target entity、たとえば TD Directory の URL、または直接対象とされた Thing の URL を表していましたが、現在これらは専用の methods によって実装されています。

すでに開始された discovery process の間に何を行うかを記述します。 discovery が与えられたこの algorithm は、次の手順を実行します:

Thing Description への新しい link が発見され、基盤となるプラットフォームによって提供されるたびに、次のサブ手順を実行する:
1. 基盤となる discovery process によって使用される Protocol Binding（link によって指定される）を使用して、 td を JSON object として取得する。 HTTP(S) Binding の場合、この process は td の取得に Fetch API を使用できます。
2. それが失敗した場合、discovery.error property を SyntaxError に設定し、td を破棄して discovery process を続行する。
Thing Description td が発見され、基盤となるプラットフォームまたは前の手順によって提供されるたびに、次のサブ手順を実行する:

注

この時点で実装は、discovery process の flow を制御してもよいです（MAY）（たとえば memory constraints に応じて、結果を queue に入れる、 queue が大きくなりすぎた場合に discovery を一時的に停止する、または queue が十分に空になったときに discovery を再開するなど）。これらの手順は、発見/取得された各 td に対して実行されます。
1. fragment を discovery.[[filter]].fragment とする。
2. fragment が object である場合、その中で定義された各 key について:
  1. その key が json 内に存在するか、および json[key が fragment.key と等しいかを確認する。
  2. いずれかの checks でこれが失敗した場合、 td を破棄し、 discovery process を続行する。
3. asyncIterator を使用して td を yield する。
  
  編集者注
  
  適切な asyncIterator terminology を使用してこの手順を改善する。
discovery process 中に error が発生するたびに、次のサブ手順を実行する:

注

最後の error が保持されます。実装は、それを報告すべきだと判断した場合、 discovery process を停止することを選択してもよいです（MAY）。
1. error を新しい Error object とする。 error.name を "DiscoveryError" に設定する。
2. Protocol Bindings によって error code または message が提供されていた場合、 error.message をその値の string に設定する。
3. discovery.error を error に設定する。
4. error が回復不能であり、基盤となるプラットフォームによって discovery が停止されている場合、または実装が discovery process を停止して error を報告することを決定した場合、 discovery.done を true に設定し、これらの手順を終了する。

discovery process を停止または抑制します。これはすべての discovery methods および endpoints によってサポートされるとは限りませんが、以後の discovery results または errors は破棄され、 discovery は done としてマークされます。このメソッドは次の手順を実行しなければなりません（MUST）:

セキュリティ上の理由により、現在のスクリプティングコンテキストでこのメソッドの呼び出しが許可されていない場合、 SecurityError をthrow して停止する。
discovery process を停止するよう基盤となるプラットフォームに要求する。これが error を返す場合、またはたとえば discovery が open ended multicast requests に基づく場合のように不可能な場合、実装は以後の discovered items を破棄するべきです（SHOULD）。
done property を true に設定する。

次の例は、local hardware によって公開される Things の ThingDescription objects を、実行されている WoT Runtime の instances の数にかかわらず見つけます。Discovery object によって提供される asyncIterator を使用して、結果を非同期に反復し、得られた ThingDescription objects で operations を実行できます。

例 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 service に listed された Things の ThingDescription objects を見つけます。安全のため timeout を設定します。

例 10: directory 経由で Things を発見する

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 に provisioned された任意の手段による generic discovery のためのもので、利用可能な場合は local Things も含みます。

例 11: network 内の Things を発見する

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 Thing を消費する

2.2 Thing を公開する

2.3 発見

3. 適合性

4. 用語と規約

5. ThingDescription 型

5.1 Thing Description のフェッチ

5.2 Thing Description の展開

5.3 Thing Description の検証

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 購読解除 Form の検索

8.18 ConsumedThing の例

9. ExposedThing インターフェイス

9.1 ExposedThing の内部スロット

9.2 ExposedThing の構築

9.3 getThingDescription() メソッド

9.4 PropertyReadHandler コールバック

9.5 setPropertyReadHandler() メソッド

9.6 Property 読み取り requests の処理

9.7 複数 Properties の読み取り requests の処理

9.8 すべての Properties の読み取り requests の処理

9.9 setPropertyObserveHandler() メソッド

9.10 Property observe requests の処理

9.11 setPropertyUnobserveHandler() メソッド

9.12 Property unobserve requests の処理

9.13 emitPropertyChange() メソッド

9.14 PropertyWriteHandler コールバック

9.15 setPropertyWriteHandler() メソッド

9.16 Property 書き込み requests の処理

9.17 複数 Properties の書き込み requests の処理

9.18 ActionHandler コールバック

9.19 setActionHandler() メソッド

9.20 Action requests の処理

9.21 EventSubscriptionHandler コールバック

9.22 setEventSubscribeHandler() メソッド

9.23 Event subscribe requests の処理

9.24 setEventUnsubscribeHandler() メソッド

9.25 Event unsubscribe requests の処理

5. `ThingDescription` 型

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.9 `setPropertyObserveHandler()` メソッド

9.11 `setPropertyUnobserveHandler()` メソッド

9.13 `emitPropertyChange()` メソッド

9.14 `PropertyWriteHandler` コールバック

9.15 `setPropertyWriteHandler()` メソッド

9.18 `ActionHandler` コールバック

9.19 `setActionHandler()` メソッド

9.21 `EventSubscriptionHandler` コールバック

9.22 `setEventSubscribeHandler()` メソッド

9.24 `setEventUnsubscribeHandler()` メソッド

9.27 `emitEvent()` メソッド

9.28 `expose()` メソッド

9.29 `destroy()` メソッド

10. `ThingDiscoveryProcess` インターフェイス

10.1 `ThingDiscoveryProcess` の構築

10.2 `ThingFilter` dictionary

10.4 `stop()` メソッド