TypeScript オントロジー SDK でオブジェクトセットの変更を購読する

購読機能はオントロジー SDK v2.1 の一部としてリリースされました。この機能を利用するには、Developer Console を開き、SDK の 2.1.x 以降のバージョンを生成します。

購読機能を使用する前に、以下のコマンドを使用するか、package.json を更新して、対応する 2.1.x バージョンの @osdk/client パッケージがプロジェクトにインストールされていることを確認してください。

Copied!1
npm install @osdk/client@^2.1.0

このページでは、TypeScript オントロジー SDK を使用して、オントロジー内のオブジェクトの変更に関する更新をリアルタイムで受信する方法を説明します。

概要

TypeScript オントロジー SDK の購読機能を使用すると、指定されたオブジェクトセット内のオブジェクトが変更されたときに更新を受信できます。これには、新しいオブジェクトの追加と削除、およびオブジェクトセット内のオブジェクトのプロパティの変更が含まれます。

基盤となる WebSocket API に直接アクセスする必要がある場合（たとえば、TypeScript 以外の言語で購読を実装する場合や、接続をより細かく制御する場合）は、WebSocket 経由でオブジェクトセットの変更を購読するを参照してください。

以降のセクションの例では、パッケージ名が @subscribe-osdk-example/sdk の Country オブジェクトタイプを使用します。例のパッケージ名を作成したパッケージに置き換え、オブジェクトタイプを選択したオブジェクトタイプに置き換えてください。最後に、population を参照している箇所を、オブジェクトタイプのプロパティに置き換えてください。

.pivotTo を使用して構築されたオブジェクトセットは購読に対応していません。また、クエリごとに同時にアクティブにできる購読は1つだけです。たとえば、オントロジー SDK アプリケーションを構築し、TSv2 を使用してオブジェクトセットの変更を購読している場合、2つの React コンポーネントが別々の購読で同じオブジェクトセットの変更を同時に監視することはできません。

`.subscribe`

オブジェクトセットを購読するには、オントロジー SDK のオブジェクトセットに .subscribe をチェーンします。.subscribe 関数は、購読のライフサイクル中のさまざまなイベントに応じて呼び出される多数の関数を受け付けます。これらの関数には、指定されたイベントに対して実行したい任意のロジックを含めることができます。

subscribe 関数は、購読を終了するための関数を含むオブジェクトを返します。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
import { Country } from "@subscribe-osdk-example/sdk";

const subscription = client(Country).subscribe(
    {
        onChange: (update) => {},
        onSuccessfulSubscription: () => {},
        onOutOfDate: () => {},
        onError: () => {},
    },
    { properties: [] },
);

subscription.unsubscribe();

また、購読するオブジェクトセットを絞り込むこともできます。これにより、更新を受信する対象のオブジェクトを絞り込めます。

Copied!1
2
3
client(Country)
    .where({ population: { $gte: "1000000" } })
    .subscribe({});

.pivotTo を使用して構築されたオブジェクトセットは購読に対応していません。

`onChange`

onChange ハンドラーは、指定されたオブジェクトセット内のオブジェクトが追加、変更、または削除されたときに呼び出されます。

ハンドラー関数には、次の2個のプロパティで構成されるオブジェクトが渡されます。

オブジェクト： Osdk.Instance オブジェクトと、渡されたオブジェクトに何が起きたかを示す列挙型です。これは、オブジェクトセットの .fetchPage メソッドから返されるオブジェクトタイプと同じです。
状態： 渡されたオブジェクトに何が起きたかを示す列挙型です。
- ADDED_OR_UPDATED: 渡されたオブジェクトがオブジェクトセットに追加されたか、そのオブジェクトのプロパティが変更されました。
- DELETED: 渡されたオブジェクトが削除されました。

以下は、onChange ハンドラーの使用例です。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
const populations: { [key: string]: number } = {};

client(Country).subscribe({
    onChange: (update) => {
        if (update.state === "ADDED_OR_UPDATED") {
            populations[update.object.$primaryKey] =
                update.object.population ??
                populations[update.object.$primaryKey];
        } else if (update.state === "DELETED") {
            delete populations[update.object.$primaryKey];
        }
    },
});

プロパティの null 許容性

ハンドラーに渡される Osdk.Instance オブジェクトのプロパティは、そのオブジェクトの最新の値を表します。オブジェクトの主キープロパティと $primaryKey フィールドは、常に定義されています。

Osdk.Instance オブジェクトのどのプロパティも未定義になる可能性があります。これは、必ずしもプロパティが未定義になるように更新されたことを示すものではなく、単にそのプロパティが返されなかったことを示します。

SDK が最後に生成されてからオブジェクトタイプにプロパティが追加された場合、渡された値のプロパティがどれも変更されていなくても、更新を受信することがあります。これは、SDK が認識していないプロパティがそのオブジェクトで変更されたことを示します。

地理時系列の参照プロパティの更新

地理時系列の参照プロパティを持つオブジェクトタイプの購読がリクエストされた場合、その時系列に新しい値があると更新がトリガーされます。この値は、返されたオブジェクトの lastFetchedValue プロパティで利用できます。

`onSuccessfulSubscription`

このハンドラーは、オントロジー SDK が購読を正常に確立し、更新の受信を開始するときに実行されます。このハンドラーが呼び出される前の更新は、ほかのハンドラーの呼び出しに反映されない場合があります。

`onOutOfDate`

このハンドラーは、オブジェクトセットで発生した更新に対して最新の情報を提供できなかったときに実行されます。これは、確実に最新の情報を受信するために、.fetchPage を呼び出してオブジェクトセット全体を再読み込みする必要があることを示します。

`onError`

このハンドラーは、購読処理でエラーが発生したときに実行され、購読が終了したことを示します。

プロパティを指定する

.subscribe メソッドでは、更新で返されるオブジェクトで受信するプロパティを指定できます。これにより、ネットワーク接続を介して送信される情報量が減り、パフォーマンスを向上させることができます。これらを指定するには、必要なプロパティの配列をメソッドの第2パラメーターの一部として渡します。

Copied!1
client(Country).subscribe({}, { properties: ["population"] });

←

PREVIOUSほかの言語向けの OSDK の生成

NEXTWebSocket 経由でのオントロジー変更の購読

→