Documentation
ドキュメントの検索
karat

+

K

APIリファレンス ↗
開発者ツールチェーンオントロジー SDKTypeScript OSDK 移行ガイド

注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

TypeScript オントロジー SDK 移行ガイド（1.x から2.0へ）

このガイドは、TypeScript オントロジー SDK 1.x を使用するアプリケーションを TypeScript オントロジー SDK 2.0 に移行するためのものです。以下のセクションでは、2つのバージョンの違いを説明し、関連する構文と構造の変更点を取り上げます。

TypeScript のドキュメントは、プラットフォーム内の Developer Console（/workspace/developer-console/）でも利用できます。TypeScript オントロジー SDK 2.0 のドキュメントを表示するには、バージョンピッカーで 2.0 を選択します。

TypeScript オントロジー SDK 1.x から2.0にアップグレードする理由は何ですか？

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

TypeScript オントロジー SDK 1.x を使用すると、Palantir プラットフォームの外部からオントロジーを操作できます。ただし、この初期バージョンにはスケーラビリティに制限がありました。

  • TypeScript オントロジー SDK 1.x は、あらゆるオブジェクト、アクション、その他のオントロジー項目について、完全なコード実装を生成します。つまり、オントロジー SDK 1.x の規模はオントロジー全体の規模に応じて大きくなり、非常に大きくなる可能性があります。
  • TypeScript オントロジー SDK 1.x では、クライアントと生成されたオントロジーが密接に結合しています。

TypeScript オントロジー SDK 2.0 は、SDK の生成方法とオントロジーへのアクセス方法を全面的に見直すことで、パフォーマンスと使いやすさをさまざまな点で改善しています。

  • TypeScript オントロジー SDK 2.0 の規模は、オントロジー自体ではなく、その形式とメタデータに比例して増加します。オントロジー SDK がオントロジーのすべての項目に依存しなくなったため、パフォーマンスが大幅に向上します。また、TypeScript オントロジー SDK 2.0 は遅延読み込みにも対応しており、アプリケーションは使用するものだけを、使用するときに必要とします。
  • TypeScript オントロジー SDK 2.0 は、クライアントを生成コードから分離しています。SDK を再生成せずにライブラリの依存関係をより迅速に更新できるため、緊急のホットフィックスをデプロイしやすくなります。また、TypeScript オントロジー SDK 2.0 は、オントロジー SDK のコードベース全体でコードを再利用できる範囲を飛躍的に拡大します。
  • TypeScript オントロジー SDK 2.0 はコード生成を効率化しており、大規模なオントロジーを対象に開発する際の反復速度を大幅に向上できます。

2つのバージョン間の主な設計上の違いとその根拠について詳しくは、オープンソースの TypeScript オントロジー SDK リポジトリにある開発者向けドキュメント ↗を参照してください。

サポートと機能

オントロジー SDK の新しい TypeScript バージョンでは、オントロジーとのインタラクション機能が拡充されています。このため、インターフェースやメディアセットなどの新機能を使用するには、TypeScript オントロジー SDK 2.0 が必要になります。

Palantir は、TypeScript オントロジー SDK 2.0 のリリース後、少なくとも1年間はオントロジー SDK の TypeScript バージョン1.x のサポートを継続します。

TypeScript オントロジー SDK 1.x から2.0にアップグレードするにはどうすればよいですか？

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

TypeScript オントロジー SDK の新しいバージョン2.0で、SDK の新しいバージョンを生成します。

TypeScript オントロジー SDK 1.x から2.0に移行する

  1. プロジェクトに新たに必要になったすべての依存関係がインストールされていることを確認してください。
  2. 新しい TypeScript オントロジー SDK 2.0 クライアントをインスタンス化します。
  3. プロジェクトのクエリ呼び出しを変更します。呼び出しの構文を更新し、必要に応じて戻り値の型の処理を調整することに重点を置きます。
  4. プロジェクトのアクション呼び出しを変更します。構文以外の主な変更点は、検証やアクションの編集レスポンスを参照している可能性のあるコードの更新です。
  5. オブジェクトタイプを移行します。
    1. コード内でオントロジー SDK のオブジェクトタイプがどのように使用されているかを詳しく確認します。
      1. オントロジー SDK のバージョン1.x が生成したオブジェクトタイプに依存している箇所を特定し、バージョン2.0で使用されるタイプとどのように異なるかを把握します。
      2. コードベースに最適な解決方法を決定します。
    2. 次に、オントロジー SDK の使用状況を確認し、新しいクライアントを使用するようにオブジェクトの読み込みを変更します。オブジェクトの構文変換セクションの手順に従い、プロパティタイプの変更点にも注意してください。
  6. オントロジー SDK の2つのバージョン間のその他の違いを確認します。

初期セットアップ

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

Copied!
1
2
npm install @osdk/client
npm install @osdk/oauth

クライアント/認証

作成

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

TypeScript オントロジー SDK 1.x（レガシー）

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
import { FoundryClient, PublicClientAuth } from "@your-generated-sdk";

//パブリック OAuth
const auth = new PublicClientAuth({
        clientId: FOUNDRY_CLIENT_ID,
        url: FOUNDRY_API_URL,
        redirectUrl: APPLICATION_REDIRECT_URL,
    });

const legacyClient = new FoundryClient({
    url: API_PROXY_TARGET_URL,
    auth: auth,
});

TypeScript オントロジー SDK 2.0

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import { createClient } from "@osdk/client";
import {
    PublicOauthClient,
    createConfidentialOauthClient,
    createPublicOauthClient
} from "@osdk/oauth";
import { $ontologyRid } from "@your-generated-sdk";

// コンフィデンシャル OAuth
const auth = createConfidentialOauthClient(
    FOUNDRY_CLIENT_ID,
    FOUNDRY_CLIENT_SECRET,
    FOUNDRY_API_URL,
);

// または

// パブリック OAuth
const auth = createPublicOauthClient(
    FOUNDRY_CLIENT_ID,
    FOUNDRY_API_URL,
    APPLICATION_REDIRECT_URL
);

const client = createClient(
    FOUNDRY_API_URL,
    $ontologyRid, // 以下の説明を参照してください
    auth
);

CLI を使用してオントロジーのオントロジー SDK をインストールした場合、$ontologyRid は SDK パッケージのルートからエクスポートされ、上記のようにアクセスできます。それ以外の場合は、クライアントを構築する箇所で、既知の ontologyRid を渡す必要があります。この情報は Foundry の Ontology Manager から取得できます。対象のオントロジーを選択し、オントロジー設定タブに移動して、オントロジーメタデータセクションからオントロジー RID をコピーします。

サービスユーザーによるコンフィデンシャル OAuth を使用してバックエンドサービスアプリケーションをセットアップする完全なウォークスルーについては、バックエンドの TypeScript アプリケーションをセットアップするを参照してください。

使用方法と一般的な構文

TypeScript オントロジー SDK 1.x（レガシー）

TypeScript オントロジー SDK 1.x では、ネストされたオブジェクト構造を通じてクライアントのメソッドにアクセスできます。例を示します。

 legacyClient.objects.legacyObject.fetchPage();

TypeScript オントロジー SDK 2.0

TypeScript オントロジー SDK 2.0 では、クライアントを直接呼び出せるようになりました。つまり、操作したいオブジェクトやアクションを渡して、クライアントを操作できます。新しい使用パターンは、通常、次の構文に従います。

client(myObject).fetchPage()
client($Objects.myObject).fetchPage()

オブジェクト

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

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

このため、コードを変換する際に、いくつかの異なる互換性の問題が発生する可能性があります。

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

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

  • TypeScript オントロジー SDK 1.x は GeoShape, GeoPoint を使用しますが、TypeScript オントロジー SDK 2.0 は GeoJSON を使用します
  • TypeScript オントロジー SDK 1.x は Timestamp, LocalDate を使用しますが、TypeScript オントロジー SDK 2.0 はこれらのデータ型を strings として扱います

オブジェクトを読み込む呼び出しを新しいクライアントに置き換えたいものの、レガシーの TypeScript オントロジー SDK 1.x のオブジェクトタイプを想定するヘルパー関数は変更したくない場合を考えます。レガシーの TypeScript オントロジー SDK 1.x から引き続きオブジェクトタイプをインポートしていると仮定すると、2つのデータ型に互換性がないため、エラーが発生します。

Copied!
1
2
3
4
5
6
7
8
9
10
const objectResult: Result<legacyMyObject, GetObjectError> =
    await legacyClient.ontology.
    objects.legacyMyObject.fetchOne("<primaryKey");

const object = client(myObject).fetchOne("<primaryKey>");
   -> Returns Osdk.Instance<myObjectV2>

const locationName = getObjectLocation(object)

function getLocation(obj: legacyMyObject){...} : Unmodified

これは、Osdk.Instance<myObjectV2> が legacyMyObject に対応していないためです。

問題：ObjectType ≠ Osdk.Instance

TypeScript オントロジー SDK 2.0 では、さまざまなプロパティにアクセスするために、オブジェクトタイプを Osdk.Instance<> でラップすることが重要です。Osdk ラッパーは、これらのプロパティを型のトップレベルに配置し、TypeScript オントロジー SDK 1.x のレガシーの型により近いものにします。

ただし、オブジェクトタイプのインポート元を TypeScript オントロジー SDK 2.0 に変更すると、問題が発生します。Osdk ラッパーがないと、オブジェクトのプロパティにトップレベルでアクセスできず、インポートした型には上記のほかのフィールドもありません。

Copied!
1
2
3
4
5
const object = client(myObjectV2).fetchOne("<primaryKey>");
    -> returns Osdk.Instance<myObjectV2>
const locationName = getObjectLocation(object)

function getLocation(obj: myObjectV2){ ... }

これは、Osdk.Instance<myObjectV2> が myObjectV2 に対応していないためです。

解決方法

TypeScript オントロジー SDK 2.0 の新しいオントロジー SDK オブジェクトタイプを使用するために、次の方法でコードを編集することを検討してください。

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

構文の変換

このセクションでは、TypeScript オントロジー SDK 1.x と 2.0 のクライアント間での対応付けを示す簡単な例を紹介します。より複雑な TypeScript オントロジー SDK 2.0 の構文例については、Palantir の公開 GitHub リポジトリにあるオントロジー SDK の例 ↗を参照してください。

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

TypeScript オントロジー SDK 1.x（レガシー）

Copied!
1
2
const objectResult: Result<legacyObject, GetObjectError> =
    await legacyClient.ontology.objects.legacyObject.fetchOneWithErrors("<primaryKey>");

TypeScript オントロジー SDK 2.0

Copied!
1
2
const objectResult: Result<Osdk.Instance<myObject>> =
    await client(myObject).fetchOneWithErrors("<primaryKey>");

fetchOne メソッドを使用して、結果ラッパーなしでオブジェクトを返すこともできます。

オブジェクトの RID にアクセスする

TypeScript オントロジー SDK 2.0 では、オブジェクトを取得する際、デフォルトではオブジェクトの RID は含まれません。オブジェクトの RID にアクセスするには、取得呼び出しで $includeRid: true オプションを使用して明示的にリクエストし、返されるインスタンスに適切な型を指定する必要があります。

TypeScript オントロジー SDK 2.0

Copied!
1
2
3
4
5
const objectWithRid: Osdk.Instance<myObject, "$rid"> =
    await client(myObject).fetchOne("<primaryKey>", { $includeRid: true });

// 返されたオブジェクトで RID が利用可能になりました
const rid = objectWithRid.$rid;

$includeRid オプションは、fetchPage およびほかの取得メソッドでも使用できます。返されるオブジェクトの $rid プロパティにアクセスするために、必ず結果の型を Osdk.Instance<ObjectType, "$rid"> として指定してください。

ページングを使用してオブジェクトを読み込む

TypeScript オントロジー SDK 1.x（レガシー）

Copied!
1
2
const objectResult =
    await legacyClient.ontology.objects.legacyObject.fetchPage({ pageSize: 30 });

TypeScript オントロジー SDK 2.0

Copied!
1
2
3
const objectResult = await client(myObject).fetchPage({ $pageSize: 30 });

const object = objectResult.data[0];

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

TypeScript オントロジー SDK 1.x（レガシー）

Copied!
1
2
3
4
5
6
const objects: legacyObject[]= [];

for await (const obj of client.ontology.objects.legacyObject.asyncIter()) {
    objects.push(obj);
}
const object = objects.value[0];

TypeScript オントロジー SDK 2.0

Copied!
1
2
3
4
5
6
const objects: myObject[]= [];

for await(const obj of client(myObject).asyncIter()) {
    objects.push(obj);
}
const object = objects.value[0];

リンク

TypeScript オントロジー SDK 1.x（レガシー）

Copied!
1
2
const object = ...load ontology object with legacy client
const link = object.legacyObjectProperty.fetchPage({ pageSize: 100 });

TypeScript オントロジー SDK 2.0

Copied!
1
2
const object = ...load ontology object with new client
const link = object.$link.myObjectProperty.fetchPage({ $pageSize: 100 });

絞り込む

WHERE 句

TypeScript オントロジー SDK 1.x（レガシー）
legacyClient.ontology.objects.legacyObject
    .where(query => query.legacyProperty.startsWith("foo"))...

TypeScript オントロジー SDK 2.0
client(myObject).where({
        myObjectProperty: { $startsWith: "foo" }
    })...

orderBy 句

並べ替えの句は、別のフィルター句ではなく、fetchPage に渡すオブジェクト内で指定するようになりました。

TypeScript オントロジー SDK 1.x（レガシー）
client.ontology.objects.legacyObject
    .orderBy(sortBy => sortBy.OntologyProperty.asc())
    .fetchPageWithErrors({ pageSize: 30 });

TypeScript オントロジー SDK 2.0
client(myObject).fetchPage({
        $orderBy: { "OntologyProperty": "asc" }
        $pageSize: 30
    });

集計

TypeScript オントロジー SDK 2.0 の構文では、集計の並び順を指定する引数を渡せます。これにより、groupBy 集計を指定する際に、結果が返される順序を制御できます。利用可能な選択肢は unordered、asc（昇順）、desc（降順）です。

オブジェクトの件数を返す

TypeScript オントロジー SDK 1.x（レガシー）
Copied!
1
2
3
4
const aggResults = legacyClient.ontology.objects.legacyObject.where(...).count().compute();
if (isOk(aggResults)) {
    const count: number = aggResults.value;
}

TypeScript オントロジー SDK 2.0
Copied!
1
2
3
4
const aggResults = await client(myObject).where(...).aggregate({
    $select: { $count: "unordered" }
    })
const count: number = aggResults.$count;

グループ化（groupBy）

TypeScript オントロジー SDK 1.x（レガシー）
legacyClient.ontology.objects.legacyObject.where(...)
    .groupBy(legacyObject => legacyObject.imageId.exact)
    .groupBy(legacyObject => legacyObject.objectLabel.exact)
    .count().
    .compute();

TypeScript オントロジー SDK 2.0
client(myObject).where(...).aggregate({ $select: { $count: "unordered" },
    $groupBy: { imageId: "exact", objectLabel: "exact" }});

一般的な集計

TypeScript オントロジー SDK 1.x（レガシー）

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
const aggResults = legacyClient.ontology.objects.legacyObject
    .aggregate(obj => ({
        legacyObject: obj.createdBy.approximateDistinct(),
    }))
    .compute();

//または

const aggResults = legacyClient.ontology.objects.legacyObject
 .approximateDistinct((obj) => obj.legacyProperty)
 .count()
 .compute();

if (isOk(aggResults)) {
    const result = aggregationResults.value;
}

TypeScript オントロジー SDK 2.0

Copied!
1
2
3
4
5
6
const aggregationResults = await client(myObject)
    .aggregate({
        $select: { "ObjectProperty:approximateDistinct": "unordered" },
    });

const result = aggregationResults.ObjectProperty.approximateDistinct;

アクション

単純なアクション

TypeScript オントロジー SDK 2.0 で単純なアクションを適用する構文は、レガシーの TypeScript オントロジー SDK 1.x の構文と非常によく似ています。どちらも applyAction 関数を呼び出します。

TypeScript オントロジー SDK 1.x（レガシー）

await legacyClient.ontology.actions.createObject({ ...params });

TypeScript オントロジー SDK 2.0

await client(createObject).applyAction({ ...params });

バッチアクション

バッチアクションでも、単純なアクションと同様の構文変更が必要です。

TypeScript オントロジー SDK 1.x（レガシー）

await legacyClient.ontology.batchActions.createObject({ ...params });

TypeScript オントロジー SDK 2.0

await client(createObject).batchApplyAction({ ...params });

アクションの検証と編集

オントロジー SDK 1.x で入力を検証したり ActionEdits を受け取ったりしていた場合、これらを Options オブジェクト内の $returnEdits および $validateOnly プロパティで指定できるようになりました。 編集内容の返却と validateOnly を同時に行うことはできません。

TypeScript オントロジー SDK 1.x（レガシー）

await legacyClient.ontology.actions.createObject({ ...params },
    { mode: ActionExecutionMode.VALIDATE_AND_EXECUTE,
    returnEdits: ReturnEditsMode.ALL });

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

TypeScript オントロジー SDK 2.0

// この呼び出しは検証エラーが発生すると例外をスローします
await client(createObject).applyAction({ ...params }, { $returnEdits: true });

await client(createObject).applyAction({ ...params }, { $validateOnly: true });

クエリ

TypeScript オントロジー SDK 1.x と 2.0 のクエリ構文の変更は、アクションの変更と非常によく似ています。TypeScript オントロジー SDK 2.0 では、実行するクエリを渡した後、クライアントで executeFunction オブジェクトを呼び出せます。

TypeScript オントロジー SDK 1.x（レガシー）

await legacyClient.queries.legacyQuery({ ...params });

TypeScript オントロジー SDK 2.0

await client(exampleQuery).executeFunction({ ...params });

その他の相違点

DateTime の扱い

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

オントロジー SDK で DateTime プロパティを使用する場合は、適切な形式の ISO 8601 文字列が必要です。たとえば、DateTime property を指定した where 句を使ってオブジェクトセットを絞り込む場合は、適切な形式の文字列を指定する必要があります。

client(myObject).where({
    "dateTimeProperty": {
        "$gt": "2010-10-01T00:00:00Z",
    }
});

オントロジー SDK のさまざまなメソッドから返される DateTime 値も、この形式になります。たとえば、オブジェクトを読み込むと、オブジェクトの DateTime プロパティは日時文字列として返されます。

共通ユーティリティ

OntologyObject

TypeScript オントロジー SDK V2 には、OntologyObject 型は存在しません。同じ用途に使える型として、@osdk/api パッケージに OsdkBase 型があります。

IsOntologyObject

TypeScript オントロジー SDK V2 には、IsOntologyObject は存在しません。