TypeScript OSDK 移行ガイド (1.x から 2.0)

このガイドは、TypeScript OSDK 1.x を使用しているアプリケーションを TypeScript OSDK 2.0 に移行する際の支援を目的としています。以下のセクションでは、2 つのバージョン間の違いと、構文や構造の変更点を説明します。

TypeScript OSDK 1.x から 2.0 にアップグレードする理由

パフォーマンスとスケーラビリティ

TypeScript OSDK 1.x は、ユーザーが Palantir プラットフォームの外部でオントロジーと対話することを可能にします。しかし、この初期バージョンにはスケーラビリティの制限がありました。

• TypeScript OSDK 1.x は、任意のオブジェクト、アクション、または他のオントロジー項目のコードを完全に実装します。これにより、OSDK 1.x はユーザーの全オントロジーのサイズに応じてスケールし、非常に大規模になる可能性があります。
• TypeScript OSDK 1.x は、クライアントを生成されたオントロジーに密接に結び付けます。

TypeScript OSDK 2.0 は、SDK の生成方法とオントロジーへのアクセス方法を見直すことで、多くのパフォーマンスと使いやすさの改善を提供します。

• TypeScript OSDK 2.0 は、実際のオントロジーではなく、ユーザーのオントロジーの形状とメタデータに応じて線形にスケールします。これにより、OSDK のパフォーマンスが大幅に向上し、オントロジー内のすべての項目に縛られることがなくなります。また、TypeScript OSDK 2.0 は遅延読み込みをサポートしており、アプリケーションは使用するものだけを必要なときに取得します。
• TypeScript OSDK 2.0 は、クライアントを生成されたコードから分離し、ライブラリの依存関係を迅速に更新して SDK の再生成を必要とせずに急速なホットフィックスを展開しやすくします。また、OSDK のコードベースを通じてコードの再利用能力を飛躍的に向上させます。
• TypeScript OSDK 2.0 は、コード生成を効率化し、大規模なオントロジーに対してビルドする際の反復速度を大幅に向上させます。

2 つのバージョン間の主要な設計上の違いとその背後にある理由についての詳細は、オープンソースの TypeScript OSDK リポジトリ内の開発者ドキュメントを参照してください。

サポートと機能

新しい TypeScript バージョンの OSDK は、オントロジーとの対話能力を向上させます。これにより、新しい機能のリリース、たとえば インターフェース や メディアセット などは、TypeScript OSDK 2.0 が必要となります。

TypeScript OSDK 1.x から 2.0 にどのようにアップグレードしますか？

既存の Developer Console アプリケーションに対して、SDK バージョン タブで TypeScript OSDK 2.0 ジェネレーターを使用して新しい SDK バージョンを生成できます。既存のアプリケーションは、新たに生成された SDK を使用するために必要な依存関係も持っている必要があります。Developer Console で作成された新しいアプリケーションはデフォルトで TypeScript OSDK 2.0 ジェネレーターを使用して SDK を生成し、開発者は Start developing タブの指示に従ってすぐに開始できます。

TypeScript OSDK 1.x から 2.0 への移行

1. プロジェクトにすべての新たに必要な依存関係をインストールします。
2. 新しい TypeScript OSDK 2.0 クライアントをインスタンス化します。
3. プロジェクトのクエリ呼び出しを修正し、呼び出しの構文を更新し、必要に応じて戻り値の型の処理を調整します。
4. プロジェクトのアクション呼び出しを修正します。構文以外では、バリデーションやアクションの編集応答を確認する可能性のあるコードを更新することが重要です。
5. オブジェクトタイプを移行します。
   1. コード内で OSDK のオブジェクトタイプがどのように使用されているかを徹底的にレビューします。
      1. OSDK の 1.x バージョンで生成されたオブジェクトタイプに依存している場所を特定し、2.0 バージョンで使用されるタイプとの違いを理解します。
      2. コードベースのための最適な解決策パスを決定します。
   2. 次に、OSDK の使用をレビューし、新しいクライアントを使用するようにオブジェクトのロードを変更します。オブジェクトの構文翻訳セクションの手順に従い、プロパティタイプの変更を注意してください。
6. OSDK の 2 つのバージョン間のその他の違いを確認します。

初期設定

最新バージョンの @osdk/client パッケージを npm からインストールするか、プロジェクトの package-lock.json を適宜更新します。

Client/Auth

作成

TypeScript OSDK 2.0 のクライアントは createClient 関数を使用して作成されます。この関数には ontologyRid という追加のパラメーターが必要です。ontologyRid パラメーターは文字列として渡すか、環境変数から読み取るか、またはSDKパッケージで生成された新しい $ontologyRid 変数から動的に読み取ることができます。

TypeScript OSDK 1.x (レガシー)

TypeScript OSDK 2.0

使用法と一般的な構文

TypeScript OSDK 1.x (レガシー)

TypeScript OSDK 1.xでは、クライアント上のメソッドにネストされたオブジェクト構造を通じてアクセスできます。たとえば:

Copied!
1
2
 legacyClient.objects.legacyObject.fetchPage(); 
 // 古いクライアントのオブジェクトからページを取得する

TypeScript OSDK 2.0

TypeScript OSDK 2.0 では、クライアントが直接呼び出せるようになりました。これにより、クライアントとインターフェースし、作業したいオブジェクトやアクションを渡すことができます。新しい使用パターンは一般的に次の構文に従います。

Copied!
1
2
client(myObject).fetchPage()
client($Objects.myObject).fetchPage()

このコードは2つの行からなり、どちらもclientオブジェクトのfetchPage()メソッドを呼び出しています。

1. client(myObject).fetchPage()
   • myObjectという変数をclient関数に渡してfetchPage()メソッドを呼び出しています。
2. client($Objects.myObject).fetchPage()
   • $Objects.myObjectというプロパティを持つオブジェクトをclient関数に渡してfetchPage()メソッドを呼び出しています。

このコードは、オブジェクトの取得方法が異なるだけで、最終的にはfetchPage()を呼び出すという動作を行っています。注意すべきは、$Objectsのような特殊なオブジェクトが使われている点です。

オブジェクト

TypeScript バージョン 1.x とバージョン 2.0 のオブジェクト型の主な違いは、オブジェクトのデータにアクセスするために使用される異なる型にあります。1.x バージョンでは、myObject 型とインターフェースすることでオブジェクトのプロパティにアクセスできました。しかし、バージョン 2.0 では、ラップされた型 Osdk.Instance<myObject> でレガシーオブジェクト型と同様の機能が提供されています。

これは、SDK 全体のメソッドの戻り値の型に反映されています。たとえば、TypeScript OSDK 1.x のページ結果型は Page<myObject> ですが、TypeScript OSDK 2.0 のページ結果型は PageResult<Osdk.Instance<myObject>> です。

これにより、コードを変換する際に直面する可能性のあるさまざまな互換性の問題が発生します。

問題: Osdk.Instance<myObject> は legacyMyObject と同等ではない

2 つのオブジェクト内のプロパティに大きな変更がありました。

• TypeScript OSDK 1.x は GeoShape, GeoPoint を使用しますが、TypeScript OSDK 2.0 は GeoJSON を使用します
• TypeScript OSDK 1.x は Timestamp, LocalDate を使用しますが、TypeScript OSDK 2.0 はこれらの型を strings として扱います

たとえば、新しいクライアントでオブジェクトのロードコールを置き換えたいが、レガシー TypeScript OSDK 1.x のオブジェクト型を期待するヘルパー関数を変更したくないとします。この場合、レガシー TypeScript OSDK 1.x からオブジェクト型をインポートし続けていると、2 つの型が互換性がないためエラーが発生します。 これは、Osdk.Instance<myObjectV2> が legacyMyObject と互換性がないためです。

問題: ObjectType ≠ Osdk.Instance

TypeScript OSDK 2.0 では、オブジェクトタイプを Osdk.Instance<> でラップすることが、さまざまなプロパティにアクセスするために重要です。Osdk ラッパーは、これらのプロパティをタイプの最上位に引き上げ、TypeScript OSDK 1.x のレガシータイプにより類似させます。

しかし、オブジェクトタイプのインポートを TypeScript OSDK 2.0 から行うように変更すると、問題が発生します。Osdk ラッパーがなければ、オブジェクトプロパティへの最上位アクセスができず、上記の他のフィールドがインポートに欠けてしまいます。 これは、Osdk.Instance<myObjectV2> が myObjectV2 と互換性がないためです。

解決策のパス

以下の方法を考慮してコードを編集し、TypeScript OSDK 2.0 の新しい OSDK オブジェクトタイプを使用します。

1. 直接置換: オブジェクトの取得を変更する際に、コードベース内のレガシーオブジェクトタイプのすべてのインスタンスを対応する TypeScript OSDK 2.0 オブジェクトタイプに置き換えます。これは単純なユースケースには最適ですが、TypeScript OSDK 1.x オブジェクトタイプを多用するコードベースには難しいです。
2. カスタムフロントエンドタイプ: オブジェクトを TypeScript OSDK 2.0 に移行する前に、組み込みのレガシー TypeScript OSDK 1.x タイプの代わりにカスタムフロントエンドタイプを使用するようにコードをリファクタリングします。その後、レガシー TypeScript OSDK 1.x タイプをカスタムタイプにマッピングするトランスレータ関数を開発します。TypeScript OSDK 2.0 への移行を開始するときは、トランスレータ関数のみを更新すればよく、コードベースの残りはそのままです。

構文の変換

このセクションには、TypeScript OSDK 1.x と 2.0 クライアント間のマッピングを説明する簡単な例が含まれています。より複雑な TypeScript OSDK 2.0 構文の例については、Palantir の公開 GitHub リポジトリの OSDK 例 ↗を参照してください。

単一オブジェクトの読み込み

TypeScript OSDK 1.x （レガシー）

TypeScript OSDK 2.0

ページングを使用したオブジェクトのロード

TypeScript OSDK 1.x（レガシー）

すべてのオブジェクトを読み込む

TypeScript OSDK 1.x（従来版）

リンク

TypeScript OSDK 1.x (旧バージョン)

フィルター処理

WHERE句

TypeScript OSDK 1.x（レガシー）**

// `legacyClient`の`ontology`オブジェクトの中にある`legacyObject`をフィルタリング
legacyClient.ontology.objects.legacyObject
    // `legacyProperty`が"foo"で始まるものを選択
    .where(query => query.legacyProperty.startsWith("foo"))...

TypeScript OSDK 2.0

// myObject のプロパティが "foo" で始まる条件を指定して検索を行う
client(myObject).where({
        myObjectProperty: { $startsWith: "foo" }
    })...

orderBy句

Order-by句は、別個のフィルター処理句ではなく、fetchPageに渡されるオブジェクト内で指定されるようになりました。

TypeScript OSDK 1.x（レガシー）

// clientオブジェクトのontologyプロパティから、レガシーオブジェクト(legacyObject)を取得
client.ontology.objects.legacyObject
    // ソート基準を指定して昇順で並べ替え
    .orderBy(sortBy => sortBy.OntologyProperty.asc())
    // ページサイズを30に設定してデータを取得、エラーも取得する
    .fetchPageWithErrors({ pageSize: 30 });

Copied!
1
2
3
4
client(myObject).fetchPage({
        $orderBy: { "OntologyProperty": "asc" } // "OntologyProperty" で昇順に並べ替え
        $pageSize: 30 // ページサイズを30に設定
    });

集約

TypeScript OSDK 2.0 の構文では、集約の順序を指定する引数を渡すことができます。これにより、groupBy 集約を指定する際に結果が返される順序を制御できます。利用可能なオプションは unordered、asc（昇順）、desc（降順）です。

オブジェクトの数を返す

TypeScript OSDK 1.x（レガシー）

グループ化 (groupBy)

TypeScript OSDK 1.x (レガシー)

// legacyObjectをimageIdとobjectLabelでグループ化し、各グループの数を計算するコード
legacyClient.ontology.objects.legacyObject.where(...)
    .groupBy(legacyObject => legacyObject.imageId.exact) // imageIdでグループ化
    .groupBy(legacyObject => legacyObject.objectLabel.exact) // objectLabelでさらにグループ化
    .count() // 各グループの要素数をカウント
    .compute(); // 計算を実行

// クライアントオブジェクトでwhere句を使用し、集約処理を行っています。
// $select: { $count: "unordered" } は、カウントを無順序で取得することを指定しています。
// $groupBy: { imageId: "exact", objectLabel: "exact" } は、imageIdとobjectLabelで正確にグループ化することを指定しています。
client(myObject).where(...).aggregate({ $select: { $count: "unordered" },
    $groupBy: { imageId: "exact", objectLabel: "exact" }});

一般的な集計

TypeScript OSDK 1.x (レガシー)

アクション

シンプルなアクション

TypeScript OSDK 2.0 でシンプルなアクションを適用するための構文は、従来の TypeScript OSDK 1.x の構文と非常に似ています。どちらも applyAction 関数を呼び出します。

TypeScript OSDK 1.x (従来)

Copied!
1
2
3
4
await legacyClient.ontology.actions.createObject({ ...params });
// legacyClientを使ってオブジェクトを作成する非同期関数
// paramsにはオブジェクト作成に必要なパラメータが含まれる
// '...'はスプレッド演算子で、paramsの内容を展開する

// createObjectのアクションを非同期で適用する
// paramsにはアクションに必要なパラメータが含まれている
await client(createObject).applyAction({ ...params });

バッチアクション

バッチアクションは、シンプルなアクションと同様に構文の変更が必要になります。

TypeScript OSDK 1.x (レガシー)

Copied!
1
2
3
4
5
6
// 'legacyClient'は古いクライアントのインスタンス
// 'ontology'はオントロジー関連の機能を提供するオブジェクト
// 'batchActions'はバッチでのアクションを扱うプロパティ
// 'createObject'メソッドは、新しいオブジェクトを作成するためのもの
// 'params'にはオブジェクト作成に必要なパラメータが含まれる
await legacyClient.ontology.batchActions.createObject({ ...params });

Copied!
1
2
// createObject のアクションをバッチで適用するための関数呼び出し
await client(createObject).batchApplyAction({ ...params });

アクションの検証と編集

OSDK 1.x で入力を検証したり ActionEdits を受信したりしていた場合、Options オブジェクトで $returnEdits と $validateOnly プロパティを指定することでこれらを定義できるようになりました。編集を返すことと validateOnly を同時に行うことはできません。

TypeScript OSDK 1.x (レガシー)

// オブジェクトを作成し、検証と実行を同時に行いたい場合
await legacyClient.ontology.actions.`createObject`({ ...params },
    { mode: ActionExcecutionMode.VALIDATE_AND_EXECUTE,
    returnEdits: ReturnEditsMode.ALL });

// 検証のみを行いたい場合
await legacyClient.ontology.actions.createObject({ ...params },
    { mode: ActionExcecutionMode.VALIDATE_ONLY });

Copied!
1
2
3
4
5
// この呼び出しは、検証エラーが発生した場合に例外をスローします
await client(createObject).applyAction({ ...params }, { $returnEdits: true });

// 検証のみを行い、実際のアクションは実行しません
await client(createObject).applyAction({ ...params }, { $validateOnly: true });

クエリ

TypeScript OSDK 1.x から 2.0 へのクエリ構文の変更は、Actions の変更と非常に類似しています。TypeScript OSDK 2.0 では、実行したいクエリを渡した後、クライアント上で executeFunction オブジェクトを呼び出すことができます。

TypeScript OSDK 1.x (レガシー)

Copied!
1
2
3
await legacyClient.queries.legacyQuery({ ...params });
// `legacyClient`オブジェクトの`queries`メソッドを使用して、`legacyQuery`を非同期に呼び出します。
// `params`オブジェクトのプロパティを展開して渡します。

// 'executeFunction' メソッドを非同期で呼び出し、'exampleQuery' を使ってクライアントから実行する。
// 'params' オブジェクトをスプレッド構文で展開して渡す。
await client(exampleQuery).executeFunction({ ...params });

その他の違い

DateTime の取り扱い

TypeScript OSDK のバージョン 1.x では、LocalDate や Timestamp などの日付や時刻を処理するためのカスタム型を提供していました。TypeScript OSDK 2.0 では、DateTime の具体的な型は提供されていません。その代わりに、OSDK 内で DateTime 値を返したり受け取ったりする操作では、国際標準である ISO 8601 ↗ の形式で生の文字列を使用します。

OSDK は、DateTime プロパティを使用する際に、正しくフォーマットされた ISO 8601 文字列を期待します。たとえば、DateTime プロパティを使用して where 句でオブジェクトセットをフィルター処理する場合、正しくフォーマットされた文字列を指定する必要があります。

// 特定の日付より後の日付を持つオブジェクトをフィルタリングするクエリ
client(myObject).where({
    "dateTimeProperty": {
        "$gt": "2010-10-01T00:00:00Z", // 2010年10月1日午前0時以降の日付
    }
});

DateTime 値は、さまざまな OSDK メソッドからもこの形式で返されます。たとえば、オブジェクトをロードする際、オブジェクトの DateTime プロパティは datetime 文字列で返されます。

共通ユーティリティ

OntologyObject

OntologyObject 型は TypeScript OSDK V2 には存在しません。文脈的に同等の型は、@osdk/api パッケージにある OsdkBase 型です。

IsOntologyObject

IsOntologyObject は TypeScript OSDK V2 には存在しません。