:::callout{theme="warning" title="GA"} Subscriptions were released as part of OSDK v2.1; to access this feature, open Developer Console and generate a 2.1.x (or later) version of your SDK.

Before using subscriptions, ensure that you have installed a matching 2.1.x version of the @osdk/client package in your project by using the command below or updating your package.json.

npm install @osdk/client@^2.1.0

:::

This page provides documentation on how to receive real time updates about changes to objects in your Ontology using the TypeScript OSDK.

Overview¶

The subscriptions feature in the TypeScript OSDK allows you to receive updates when objects in a specified object set are changed. This includes the addition and deletion of new objects, as well as changes to properties on objects in the object set.

The examples in the following sections use a Country object type with a @subscribe-osdk-example/sdk package name. Replace the example package name and object type with the package you created, and the object type you selected, respectively. Lastly, replace references to population with a property from your object type.

Note that object sets constructed using .pivotTo are not supported for subscriptions. Additionally, only one subscription may be active per query at a time. For example, if you are building an OSDK application and using TSv2 to subscribe to object set changes, two React components cannot simultaneously be listening on separate subscriptions for changes in the same object set.

`.subscribe`¶

To subscribe to an object set, chain .subscribe onto an OSDK object set. The .subscribe function accepts a multitude of functions that will be triggered for different events during the lifecycle of the subscription. These functions can contain any logic you want to execute for the given event.

The subscribe function returns an object containing a function to end the subscription.

import { Country } from "@subscribe-osdk-example/sdk";

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

subscription.unsubscribe();

Additionally, it is possible to filter the object set that is subscribed to. This will narrow the set of objects you will receive updates for.

client(Country)
    .where({ population: { $gte: "1000000" } })
    .subscribe({});

Object sets that are constructed using .pivotTo are not supported for subscriptions.

`onChange`¶

The onChange handler is triggered when an object in the specified object set has been added, changed, or deleted.

The handler function provides an object that consists of two properties:

Object: An Osdk.Instance object and an enum describing what happened to the provided object. This is identical to the object type returned from a .fetchPage method on an object set.
State: An enum describing what happened to the provided object.
ADDED_OR_UPDATED: The provided object was added to the object set or a property has changed on the provided object.
DELETED: The provided object was deleted.

Below is an example of onChange handler usage:

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];
        }
    },
});

Property nullability¶

Properties on the Osdk.Instance object provided to the handler represent the most up to date values for that object. The primary key property and the $primaryKey field on the object will always be defined.

It is possible for any property on the Osdk.Instance object to be undefined. This does not necessarily indicate that the property was updated to be undefined, but rather that the property simply wasn't returned.

If more properties have been added to an object type since the SDK was last generated, it is possible to receive updates even though none of the properties on the provided value have changed. This indicates that a property that your SDK is not aware of has changed on the object.

Geotime series updates¶

If a subscription is requested for an object type with a geotime series property, updates will be triggered when there is a new value for that series. This value will be available on the lastFetchedValue property on the returned object.

`onSuccessfulSubscription`¶

This handler is executed when the OSDK establishes a successful subscription and will start receiving updates. Updates before this handler is triggered may not be reflected in calls to other handlers.

`onOutOfDate`¶

This handler is executed when up to date information could not be provided for updates that occurred to the object set. This indicates that you should reload the entire object set with a call to .fetchPage in order to make sure you receive the most up to date information.

`onError`¶

This handler is executed when there has been an error in the subscription process, indicating that the subscription has been closed.

Specify properties¶

The .subscribe method allows specifying which properties to receive on objects returned from updates. This can improve performance by reducing the amount of information sent over a network connection. To specify these, pass in an array of the properties you want as part of the second parameter on the method.

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

中文翻译¶

使用 TypeScript OSDK 订阅对象集变更¶

:::callout{theme="warning" title="GA"} 订阅功能作为 OSDK v2.1 的一部分发布；要访问此功能，请打开开发者控制台(Developer Console)并生成 2.1.x（或更高）版本的 SDK。

在使用订阅功能之前，请确保已通过以下命令或更新 package.json 在项目中安装了匹配的 2.1.x 版本的 @osdk/client 包。

npm install @osdk/client@^2.1.0

:::

本页提供有关如何使用 TypeScript OSDK 接收本体论(Ontology)中对象变更的实时更新的文档。

概述¶

TypeScript OSDK 中的订阅功能允许您在指定对象集(object set)中的对象发生变更时接收更新。这包括新对象的添加和删除，以及对象集中对象属性的变更。

以下各节中的示例使用了包名为 @subscribe-osdk-example/sdk 的 Country 对象类型。请将示例包名和对象类型分别替换为您创建的包和选择的对象类型。最后，将对 population 的引用替换为您对象类型中的某个属性。

请注意，不支持对使用 .pivotTo 构建的对象集进行订阅。此外，每个查询一次只能有一个处于活动状态的订阅。例如，如果您正在构建 OSDK 应用程序并使用 TSv2 订阅对象集变更，则两个 React 组件不能同时通过单独的订阅监听同一对象集的变更。

`.subscribe`¶

要订阅对象集，请将 .subscribe 链接到 OSDK 对象集上。.subscribe 函数接受多个回调函数，这些函数将在订阅生命周期的不同事件发生时触发。这些函数可以包含您希望针对给定事件执行的任何逻辑。

subscribe 函数返回一个对象，其中包含用于结束订阅的函数。

import { Country } from "@subscribe-osdk-example/sdk";

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

subscription.unsubscribe();

此外，还可以对订阅的对象集进行过滤。这将缩小您接收更新的对象范围。

client(Country)
    .where({ population: { $gte: "1000000" } })
    .subscribe({});

不支持对使用 .pivotTo 构建的对象集进行订阅。

`onChange`¶

当指定对象集中的对象被添加、更改或删除时，将触发 onChange 处理程序。

处理程序函数提供一个包含两个属性的对象：

Object： 一个 Osdk.Instance 对象和一个描述所提供对象发生何种变化的枚举。这与对象集上 .fetchPage 方法返回的对象类型相同。
State： 一个描述所提供对象发生何种变化的枚举。
ADDED_OR_UPDATED： 所提供的对象已添加到对象集中，或所提供对象的属性已更改。
DELETED： 所提供的对象已被删除。

以下是 onChange 处理程序的使用示例：

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];
        }
    },
});

属性可空性¶

提供给处理程序的 Osdk.Instance 对象上的属性代表该对象的最新值。对象上的主键属性和 $primaryKey 字段将始终被定义。

Osdk.Instance 对象上的任何属性都可能为 undefined。这并不一定表示该属性被更新为 undefined，而是仅仅表示未返回该属性。

如果自上次生成 SDK 以来向对象类型添加了更多属性，即使所提供值上的所有属性均未更改，也有可能收到更新。这表明对象上发生了您的 SDK 未感知到的属性变更。

地理时间序列(Geotime series)更新¶

如果请求订阅具有地理时间序列属性的对象类型，则当该序列出现新值时将触发更新。此值将在返回对象的 lastFetchedValue 属性上提供。

`onSuccessfulSubscription`¶

当 OSDK 成功建立订阅并将开始接收更新时，将执行此处理程序。在触发此处理程序之前的更新可能不会反映在对其他处理程序的调用中。

`onOutOfDate`¶

当无法为对象集发生的更新提供最新信息时，将执行此处理程序。这表明您应通过调用 .fetchPage 重新加载整个对象集，以确保接收到最新信息。

`onError`¶

当订阅过程中出现错误，表明订阅已关闭时，将执行此处理程序。

指定属性¶

.subscribe 方法允许指定在更新返回的对象上接收哪些属性。这可以通过减少通过网络连接发送的信息量来提高性能。要指定这些属性，请将所需属性的数组作为该方法的第二个参数的一部分传入。

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

Subscribe to changes in object sets with the TypeScript OSDK（使用 TypeScript OSDK 订阅对象集变更）¶

Overview¶

.subscribe¶

onChange¶

Property nullability¶

Geotime series updates¶

onSuccessfulSubscription¶

onOutOfDate¶

onError¶

Specify properties¶

中文翻译¶

使用 TypeScript OSDK 订阅对象集变更¶

概述¶

.subscribe¶

onChange¶

属性可空性¶

地理时间序列(Geotime series)更新¶

onSuccessfulSubscription¶

onOutOfDate¶

onError¶

指定属性¶

`.subscribe`¶

`onChange`¶

`onSuccessfulSubscription`¶

`onOutOfDate`¶

`onError`¶

`.subscribe`¶

`onChange`¶

`onSuccessfulSubscription`¶

`onOutOfDate`¶

`onError`¶