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

TypeScript v1 から TypeScript v2 に移行する

このガイドでは、既存の TypeScript 関数を v1 から v2 に移行する際に生じる可能性のある構文と構造の違いについて説明します。v2 の機能強化と各バージョンでサポートされる機能については、機能サポートのドキュメントを参照してください。

関数を宣言する

TypeScript v1 で関数をプラットフォームに公開するには、@foundry/functions-api パッケージの @Function() デコレーターで関数にアノテーションを付ける必要があります。また、関数は、リポジトリのルートにある index.ts ファイルからエクスポートされるクラスのメソッドである必要があります。

Copied!
1 2 3 4 5 6 7 8 9 10 11 // src/index.ts import { Function } from "@foundry/functions-api"; export class MyFunctions { @Function() public reverseStringArray(arr: string[]): string[] { return arr.reverse(); } }

TypeScript v2 で関数をプラットフォームに公開するには、src/functions ディレクトリ内のファイルに関数を記述し、export default を使用してエクスポートする必要があります。各ファイルからエクスポートできる関数は1つです。

Copied!
1 2 3 4 5 6 7 // src/functions/reverseStringArray.ts export default function reverseStringArray( arr: string[] ): string[] { return arr.reverse(); }

リポジトリを整理するために、関連する関数を src/functions ディレクトリ内のサブディレクトリにまとめることを推奨します。たとえば、次のフォルダー構造では、関数を payroll と staffing のサブディレクトリに整理して、責務の分離をより明確にしています。

TypeScript v2 関数のフォルダー構造の例。

詳細については、TypeScript v2 関数をはじめるためのドキュメントを参照してください。

@osdk/functions パッケージを使用する

TypeScript v1 では、Integer や Double などのプリミティブ型をシグネチャで使用するには、@foundry/functions-api パッケージからインポートする必要があります。一方、TypeScript v2 では、代わりに @osdk/functions パッケージを使用する必要があります。

次の例では、@foundry/functions-api パッケージから Integer 型をインポートし、2つの整数の最大公約数を計算する TypeScript v1 関数のシグネチャで使用しています。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 import { Function, Integer } from "@foundry/functions-api"; export class MyFunctions { @Function() public gcd(a: Integer, b: Integer): Integer { if (b === 0) { return a; } return gcd(b, a % b); } }

TypeScript v2 でも TypeScript のコアロジックは同じですが、@osdk/functions パッケージの Integer 型を使用する必要があります。

Copied!
1 2 3 4 5 6 7 8 import { Integer } from "@osdk/functions"; export default function gcd(a: Integer, b: Integer): Integer { if (b === 0) { return a; } return gcd(b, a % b); }

TypeScript v1 と TypeScript v2 の両方の関数で、シグネチャに使用する型をインポートして使用する例については、データ型リファレンスを参照してください。

日付とタイムスタンプ

TypeScript v1 では、日時データを扱うために @foundry/functions-api パッケージの LocalDate 型と Timestamp 型を使用します。TypeScript v2 では、これらの代わりに @osdk/functions パッケージの DateISOString 型と TimestampISOString 型を使用します。これらの型は、日付とタイムスタンプを ISO 8601 ↗ 形式の文字列で表します。

TypeScript v2 関数では、dayjs ↗、date-fns ↗、luxon ↗ など、NPM エコシステムで利用可能な任意の日付およびタイムスタンプのライブラリを使用できます。

オントロジー SDK を生成する

TypeScript v2 関数では、オントロジー SDK を通じたオントロジーのクエリと編集が標準でサポートされています。TypeScript v1 と同様に、TypeScript v2 リポジトリでも、リソースのインポートサイドバーからオントロジーエンティティをインポートできます。オブジェクトタイプとリンクタイプを追加すると、オントロジー SDK の初期バージョンを作成するためのプロンプトが表示されます。

TypeScript コードリポジトリで最初のオントロジー SDK を作成するためのプロンプト。

作成するを選択し、オントロジー SDK の名前を決めます。この名前は、最初のバージョンが生成された後は変更できません。新しいバージョンを作成を選択して、オントロジー SDK を生成します。

最初のオントロジー SDK を生成する前に名前を選択します。

オントロジー SDK が作成されると、ワークスペースにインストールするための選択肢が表示されます。インストールを選択すると、オントロジー SDK が package.json ファイルに依存関係として追加され、TypeScript コードで使用できるようになります。

TypeScript コードリポジトリからオントロジー SDK をインストールするためのプロンプト。

TypeScript でオントロジーを扱う包括的な例については、サイドバーのドキュメントタブをご覧ください。

オントロジーをクエリする

TypeScript v1 では、オントロジーに対して検索を実行するには、@foundry/ontology-api パッケージから Objects をインポートする必要があります。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 import { Function, Integer } from "@foundry/functions-api"; import { Objects } from "@foundry/ontology-api"; export class MyFunctions { @Function() public async countAircraft(): Promise<Integer> { const count = await Objects.search().aircraft().count() ?? 0; return count; } }

TypeScript v2 では、関数シグネチャの第1引数にオントロジー SDK クライアントを指定してアクセスする必要があります。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 import { Aircraft } from "@ontology/sdk"; import { Client } from "@osdk/client"; import { Integer } from "@osdk/functions"; export default async function countAircraft(client: Client): Promise<Integer> { const aircraft = await client(Aircraft).aggregate({ $select: { $count: "unordered" } }); return aircraft.$count; }

このセクションの残りの部分では、TypeScript v1 のクエリ構文と、それに対応する TypeScript v2 の構文を示します。TypeScript v2 のクエリ構文全体については、TypeScript OSDK リファレンスを参照してください。

どちらのバージョンでも、絞り込み、並べ替え、集計に使用するすべてのプロパティは、Ontology Manager で検索可能に指定されている必要があります。検索可能の設定はプロパティのインデックス化方法を制御するため、この要件はどちらかの SDK ではなく、オントロジーに属するものです。変わるのは、問題が判明するタイミングです。TypeScript v1 では、コードジェネレーターが指定されていないプロパティの絞り込み、並べ替え、集計のメソッドを生成しないため、それらを使用するとコンパイルに失敗します。一方、オントロジー SDK では、オブジェクトタイプのどのプロパティでも .where()、$orderBy、.aggregate() に指定できます。

移行前に検索可能の設定を確認

移行前に、絞り込み、並べ替え、集計に使用するすべてのプロパティが、Ontology Manager で検索可能に指定されていることを確認してください。TypeScript v2 では、指定されていないプロパティでもコンパイルされるため、問題が現れるのは関数の実行時のみです。$containsAnyTerm などの全文検索述語は、エラーではなく空のページを返すため、フィルターが何にも一致していないのに成功として報告される場合があります。

フィルター演算子の対応

TypeScript v1 では、.filter() メソッドに、絞り込み対象のプロパティのデータ型に応じたフィルター定義を渡します。TypeScript v2 では、これらのメソッド群が、句オブジェクトを受け取る単一の .where() 呼び出しに置き換えられています。次のテーブルは、TypeScript v1 の各フィルターメソッドに対応する TypeScript v2 の where 句のキーと、適用対象のプロパティタイプを示します。

TypeScript v2 の制限は、TypeScript v1 の対応する制限よりも厳しくなっています。地理空間プロパティは $within、$intersects、$isNull のみを受け付け、配列プロパティは $contains と $isNull のみを受け付けます。記載されている各フィルターの形式については、TypeScript OSDK リファレンスの絞り込みを参照してください。$within、$intersects、$interval は記載されていません。

TypeScript v1TypeScript v2 の where 句のキー適用対象
.exactMatch(value)$eq、または値のみブール値、日時、数値、文字列
.exactMatch(...values)$in: [...]ブール値、日時、数値、文字列
Filters.not(exactMatch)$neブール値、日時、数値、文字列
.hasProperty()$isNull: false配列、ブール値、日時、Geopoint、Geoshape、数値、文字列
Filters.not(hasProperty())$isNull: true配列、ブール値、日時、Geopoint、Geoshape、数値、文字列
.range().lt(x)$lt日時、数値
.range().lte(x)$lte日時、数値
.range().gt(x)$gt日時、数値
.range().gte(x)$gte日時、数値
.isTrue() / .isFalse()$eq: true / $eq: falseブール値
.matchAnyToken(...)$containsAnyTerm文字列
.matchAllTokens(...)$containsAllTerms文字列
.phrase(...)$containsAllTermsInOrder文字列
.phrasePrefix(), .prefixOnLastToken()$interval。検索文字列を $match に指定し、$prefixOnLastTerm: true を設定文字列
.contains(...)$contains。内部フィルターをちょうど1個受け取る配列
.withinDistanceOf(), .withinPolygon(), .withinBoundingBox()$withinGeopoint、Geoshape
.intersectsPolygon(), .intersectsBoundingBox()$intersectsGeoshape
.doesNotIntersectPolygon(), .doesNotIntersectBoundingBox()$intersects をラップする $notGeoshape
.isPresent()対応する where 句のキーなしリンク

変換後のフィルターの形式は、3つの動作の違いによって変わります。TSv2 の句の形式に関するルール自体については、絞り込みを参照してください。

  • 上下限のある範囲は2つの句になります。 TypeScript v1 の .range().gte(a).lte(b) チェーンは1回の呼び出しですが、TypeScript v2 ではプロパティごとに1個の演算子キーしか受け付けないため、同じフィルターは $and: [{ p: { $gte: a } }, { p: { $lte: b } }] になります。
  • 複数の値を指定した .contains() は $or になります。 TypeScript v1 の .contains() は複数の値を受け取り、そのいずれかに一致しますが、TypeScript v2 の $contains は内部フィルターをちょうど1個受け取ります。
  • 日時の比較には ISO 8601 文字列を指定します。 例:{ $gt: "2010-10-01T00:00:00Z" }。

リンク走査の対応

TypeScript v1 では、各オブジェクトインターフェースにリンクタイプごとのフィールドが生成され、さらにオブジェクトセットにリンクタイプごとの searchAround メソッドが生成されます。TypeScript v2 では、リンクごとのアクセサーが $link の下にネストされ、searchAround メソッド群全体が単一の pivotTo() メソッドに置き換えられています。

TypeScript v1TypeScript v2
.get() または .getAsync() で読み取る SingleLink フィールド$link.{linkApiName}.fetchOne()。例外をスローする代わりに { value } / { error } ラッパーを使用する場合は fetchOneWithErrors()。存在しない場合の動作の違いに注意してください。.get() は undefined を返しますが、fetchOne() は例外をスローし、fetchOneWithErrors() はほかの失敗と区別できない { error } を返します
.all() または .allAsync() で読み取る MultiLink フィールド$link.{linkApiName}。すでに ObjectSet であり、asyncIter() で反復処理します
オブジェクトセットの searchAround<LinkApiName>()pivotTo("<linkApiName>")

searchAround メソッド名からリンクのAPI名を導き出さないでください。メソッド名にAPI名が正確に保持されているとは限りません。代わりに、リンクのAPI名を確認してください。生成された TypeScript v2 SDK では、オブジェクトタイプの $link コンテナのキーが、リンクのAPI名そのものです。pivotTo() には、その値をそのまま渡します。たとえば、API名が toOtherObjectType のリンクは、pivotTo("toOtherObjectType") で走査します。

TypeScript v1 では、単一のオブジェクトのインスタンスから到達したリンクに対して実行できる操作にも制限があります。MultiLink はオブジェクトセットに変換できないため、まずそのオブジェクトからオブジェクトセットを再構築する必要があります。TypeScript v2 では、多重度が多の $link エントリはすでに ObjectSet であり、pivotTo() も ObjectSet を返すため、直接チェーンできます。TSv2 の API 自体については、TypeScript OSDK リファレンスのリンクを参照してください。

グループ化戦略の対応付け

TypeScript v1 では、プロパティタイプに応じて選択したバケット化メソッドで .groupBy() を呼び出し、集計をバケットに分けます。TypeScript v2 では、1回の .aggregate() 呼び出しの $groupBy オブジェクト内の値として同じ情報を指定します。次のテーブルは、TypeScript v1 の各バケット化メソッドと TypeScript v2 の $groupBy 値の対応を示しています。

$ranges は2要素のタプルの配列を受け取り、$duration は [value, unit] タプルを受け取ります。範囲は開始値を含み、終了値を含みません。これは TypeScript v1 と同じです。任意の値を受け取るのは "seconds"、"minutes"、"hours"、"days" のみで、それより大きい単位は 1 のみを受け取ります。グループ化戦略自体については、グループ化の種類を参照してください。

TypeScript v1TypeScript v2 の $groupBy 値
.exactValues()"exact"
.exactValues({ maxBuckets: n }){ $exactWithLimit: n }
.topValues()"exact"
.byFixedWidth(50){ $fixedWidth: 50 }
.byRanges({ min: 0, max: 50 }, { min: 50, max: 100 }){ $ranges: [[0, 50], [50, 100]] }
.byYear(){ $duration: [1, "years"] }
.byQuarter(){ $duration: [1, "quarters"] }
.byMonth(){ $duration: [1, "months"] }
.byWeek(){ $duration: [1, "weeks"] }
.byDays(n){ $duration: [n, "days"] }
.byHours(n), .byMinutes(n), .bySeconds(n){ $duration: [n, "hours"] }, { $duration: [n, "minutes"] }, { $duration: [n, "seconds"] }
.segmentBy(...)同じ $groupBy オブジェクト内の2個目のキー

完全一致の値によるグループ化リクエストには、必ず最大バケット数が設定されます。デフォルトはバージョンによって異なり、TypeScript v1 の .topValues() のデフォルトは1,000、TypeScript v2 の "exact" のデフォルトは10,000です。結果が正確になるのは、プロパティの一意の値の数がこのバケット数以内に収まる場合のみです。この数を超えると、返されるグループからオブジェクトが除かれ、集計は近似になります。プラットフォームは、結果が正確か近似かをすべてのレスポンスで報告しますが、TypeScript OSDK はそのフィールドを公開しません。そのため、TypeScript v2 の関数内では、近似結果と正確な結果を区別できません。カーディナリティが高いプロパティの場合は、{ $exactWithLimit: n } でバケット数を増やすか、先に .where() でオブジェクトセットを絞り込みます。ブールプロパティの一意の値は最大2個なので、ブールプロパティに対する "exact" は常に正確です。

集計メトリクスの対応付け

オブジェクトセットをグループ化した後、TypeScript v1 では .count() や .average() などの集計メソッドを呼び出してメトリクスを計算します。TypeScript v2 では、1回の .aggregate() 呼び出しの $select オブジェクトでメトリクスを選択します。次のテーブルは、TypeScript v1 の各集計メソッドと TypeScript v2 の $select キーの対応を示しています。

件数以外のキーはすべて "<propertyApiName>:<metric>" という形式の文字列で、値はすべて並べ替えの指定("unordered"、"asc"、または "desc")です。数値型のプロパティはすべての接尾辞を受け取ります。日時およびタイムスタンプのプロパティは min、max、approximateDistinct、exactDistinct のみを受け取り、その他のデータ型はすべて、一意の値の件数を表す2種類の接尾辞のみを受け取ります。集計の概念については、TypeScript OSDK リファレンスの集計を参照してください。

TypeScript v1TypeScript v2 の $select キー
.count()$count: "unordered"
.average(e => e.p)"p:avg": "unordered"
.max(e => e.p)"p:max": "unordered"
.min(e => e.p)"p:min": "unordered"
.sum(e => e.p)"p:sum": "unordered"
.cardinality(e => e.p)"p:approximateDistinct": "unordered"
TypeScript v1 に相当するものなし"p:exactDistinct": "unordered"

変換後の呼び出しの形式に影響する差異が1つあります。.aggregate() は、必須の $select と任意の $groupBy という2個のキーだけを持つ単一のリクエストオブジェクトを受け取ります。where キーはないため、.aggregate() を呼び出す前に、チェーンした .where() でオブジェクトセットを絞り込みます。

結果の形式も変わるため、変換後の関数では自身の出力の読み取り方を変更する必要があります。$select の指定、並べ替えの制限、グループ化された結果の読み取り方については、集計を参照してください。

TypeScript v2 に相当するものがない機能

TypeScript v1 のクエリ機能の一部には TypeScript v2 に対応するものがないため、検索や集計を変換する前に対処方法を検討してください。

フィルタリング

  • リンクの有無によるフィルタリングに対応する where 句のキーはありません。 TypeScript v1 では、.isPresent() によって、指定したタイプのリンクされたオブジェクトが1つ以上あるオブジェクトにオブジェクトセットを絞り込みます。否定した場合は、そのようなオブジェクトがないものに絞り込みます。TypeScript v2 には、これを行う $ キーがありません。最も近い方法は派生プロパティです。リンクされたオブジェクトの数を数える派生プロパティを定義し、その数が0より大きいという条件で絞り込みます。これはサポートされている同等の機能ではなく回避策なので、利用する前にご自身のデータでテストしてください。
  • Fuzziness の編集距離に対応する形式は TypeScript v2 にありません。 TypeScript v2 の語句演算子 $containsAnyTerm と $containsAllTerms は、単純な fuzzySearch ブール値を受け入れ、編集距離を制御する機能を提供しないため、Fuzziness.LEVENSHTEIN_ONE と Fuzziness.LEVENSHTEIN_TWO に直接対応する形式は TypeScript v2 にありません。$containsAllTermsInOrder はあいまい検索のオプションを一切受け入れません。$interval キーには編集距離を指定する $fuzzy と $fuzziness サブキーがあるため、この構文を利用する前にご自身のデータでテストしてください。

グループ化

  • 上限または下限のない範囲バケットはなくなりました。 TypeScript v1 では、min または max を省略することで、負の無限大から max まで、または min から無限大までのバケットを作成できます。TypeScript v2 の $ranges タプルでは両端の値が必要です。
  • TypeScript v2 では Long プロパティでグループ化できません。 TypeScript v1 では、グループ化に利用可能な数値型に Long が含まれていますが、TypeScript v2 の型には Long プロパティ用の $groupBy の値がありません。
  • TypeScript v2 では配列プロパティによるグループ化はサポートされていません。 TypeScript v1 では、配列プロパティでその要素のデータ型と同じバケット化メソッドを使用できます。TypeScript v2 の型では $groupBy に配列プロパティを指定できるため、誤ったコードでもコンパイルされますが、結果は保証されません。代わりにスカラープロパティでグループ化してください。
  • TypeScript v2 には segmentBy がありません。 TypeScript v1 では、.groupBy() の後に .segmentBy() を呼び出すことで、2個のプロパティによってバケット化された3次元の集計を計算します。TypeScript v2 でこれに相当するのは、同じ $groupBy オブジェクト内の2個目のキーですが、返される形式は同じではありません。TypeScript v1 はネストされたバケットを生成しますが、TypeScript v2 は行のフラットな配列を返します。各行には、すべてのグループ化キーの値を保持する $group オブジェクトが含まれます。そのため、3次元の集計を返す必要がある関数では、ネスト構造を自ら再構築する必要があります。各バージョンで想定される形式については、集計の型を参照してください。

集計メトリクス

  • 日付またはタイムスタンプの平均を計算できるのは TypeScript v1 のみです。 TypeScript v1 の .average() は、タイムスタンプおよび日付プロパティを受け入れます。TypeScript v2 では、日付またはタイムスタンププロパティに対して利用できるのは min、max、approximateDistinct、exactDistinct のみで、avg と sum はどちらも利用できません。
  • TypeScript v2 にはメトリクスのエイリアス機能がありません。 結果のキーは常にプロパティとメトリクスから派生するため、$count または "property:metric" 形式の文字列以外の $select キーは型エラーになります。

並べ替えと読み込み

  • TypeScript v2 には .take() も .limit() もありません。 並べ替えは、fetchPage() または asyncIter() のオプションの $orderBy として渡します。fetchPage() では、$pageSize によって1ページあたりの結果の最大件数を設定でき、上限は10,000件です。さらに結果がある場合でも、ページに含まれる結果が指定件数より少なくなることがあります。並べ替えられた n 個のオブジェクトを取得するには、n 個のオブジェクトを取得するか、次のページがなくなるまで、ページを順次取得します。asyncIter() はページリクエストを自ら管理し、オブジェクトセットをすべて処理するまで継続します。

    例:

    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 { ExampleDataAircraft } from "@ontology/sdk"; import { Client, Osdk } from "@osdk/client"; import { Integer } from "@osdk/functions"; export default async function loadFirstNAircraft( client: Client, n: Integer, ): Promise<Osdk.Instance<ExampleDataAircraft, never, "tailNumber">[]> { const aircraft: Osdk.Instance<ExampleDataAircraft, never, "tailNumber">[] = []; let nextPageToken: string | undefined; while (aircraft.length < n) { const page = await client(ExampleDataAircraft).fetchPage({ $select: ["tailNumber"], $orderBy: { tailNumber: "asc" }, $pageSize: Math.min(n - aircraft.length, 10_000), $nextPageToken: nextPageToken, }); aircraft.push(...page.data); nextPageToken = page.nextPageToken; // 次のページがない場合は、最初からやり直しません if (nextPageToken == null) { break; } } return aircraft; }
  • TypeScript v2 には .all() がありません。 TypeScript v1 の .all() と .allAsync() は、オブジェクトセット全体を一度に実体化します。TypeScript v2 では、オブジェクトをメモリーに読み込むで説明しているように、asyncIter() で反復処理するか、fetchPage() で1ページを読み込みます。

  • 最近傍の上限が拡大されました。 TypeScript v1 では k の値が 0 < K <= 100 に制限されていますが、TypeScript v2 の nearestNeighbors() メソッドは1から500までの numNeighbors を受け入れます。そのため、TypeScript v1 で範囲の上限を指定している検索は、移行後には5倍の数の近傍をリクエストできます。

  • 関連度による並べ替えは最近傍検索でのみ機能します。 TypeScript v2 では、$orderBy: "relevance" は nearestNeighbors() 検索に適用されます。この検索では numNeighbors によって結果の件数が制限され、返される各オブジェクトには $score が含まれます。トークン一致の where 句には効果がないため、.matchAnyToken() で絞り込み、関連度で並べ替えてから最初の N 件の結果を取得するという TypeScript v1 のパターンに相当するものは、TypeScript v2 にはありません。

オブジェクトを識別する

TypeScript v1 では、rid、primaryKey、typeId フィールドを通じてオブジェクトを識別できます。TypeScript v2 では、組み込みの識別子フィールドすべてに接頭辞 $ を付けてオブジェクト自体のプロパティと区別し、さらに、オブジェクトタイプと主キーの両方をエンコードした単一の文字列である $objectSpecifier を追加しています。$rid は、読み込み時に $includeRid: true で明示的に指定した場合にのみ存在するため、TypeScript v2 の識別ロジックでは $rid ではなく $objectSpecifier を基準にしてください。

識別子リファレンス

次のテーブルは、TypeScript v1 の各識別子および型と、それに相当する TypeScript v2 の識別子および型の対応を示しています。

TypeScript v1TypeScript v2注記
obj.ridobj.$rid読み込み時に $includeRid: true を渡した場合にのみ存在します。
obj.primaryKeyobj.$primaryKey常に存在します。
obj.typeIdobj.$apiName または obj.$objectType常に存在します。どちらもオブジェクトタイプのAPI名を保持しますが、リテラル型なのは $apiName のみです。
利用不可obj.$objectSpecifier常に存在します。文字列 "<apiName>:<primaryKey>" です。
EmployeeOsdk.Instance<Employee>読み込まれたオブジェクトのインスタンスの型です。
OntologyObject相当するものなし@osdk/api の OsdkBase が最も近い型です。
IsOntologyObject相当するものなし削除されており、直接の代替はありません。
オブジェクトをキーとする FunctionsMap<T, V>Record<ObjectSpecifier<T>, V>スカラーをキーとする FunctionsMap は、通常の Record<K, V> になります。オブジェクトのマッピングを参照してください。

2個のオブジェクトの等価性の比較は、移行によって簡単になります。TypeScript v1 では、主キーは単一のオブジェクトタイプ内でのみ一意であるため、typeId と primaryKey の両方を比較する必要があります。TypeScript v2 では両方の値が $objectSpecifier にエンコードされるため、同等のチェックを単一の文字列比較で行えます。この比較は、2個のオブジェクトのオブジェクトタイプが異なる場合でも正しく機能します。

Copied!
1 2 3 function isEqual(o1: { $objectSpecifier: string }, o2: { $objectSpecifier: string }): boolean { return o1.$objectSpecifier === o2.$objectSpecifier; }

両方のバージョンでオブジェクトをキーとするマップを使用する具体例については、型リファレンスのマップを参照してください。両方の例の TypeScript v1 形式と、オブジェクトの等価性に注意が必要な理由に関する概念的な背景については、オブジェクト識別子を参照してください。

オントロジーを編集する

TypeScript v1 でオントロジー編集関数を記述するには、@foundry/functions-api パッケージの @OntologyEditFunction() デコレーターで関数にアノテーションを付け、戻り値の型を void にする必要があります。また、@Edits デコレーターを適用して、編集するすべてのオブジェクトタイプを事前に宣言する必要があります。これにより、関数ベースのアクションが呼び出される前に、それらのオブジェクトタイプに対する権限を適用できます。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 import { Edits, OntologyEditFunction } from "@foundry/functions-api"; import { Aircraft, Employee } from "@foundry/ontology-api"; export class MyOntologyEditFunctions { @Edits(Aircraft, Employee) @OntologyEditFunction() public myFunction(aircraft: Aircraft, employee: Employee): void { aircraft.businessCapacity = 3; employee.department = "HR"; } }

TypeScript v2 では、@osdk/functions パッケージから createEditBatch 関数をインポートして、実行中に使用する編集の格納先を構築する必要があります。関数による編集が許可されるエンティティを宣言するには、Edits 型を使用する必要があります。これにより、コンパイル時の型安全性が確保されます。Edits 型で指定されていないタイプのオブジェクトやリンクを編集しようとすると、TypeScript コンパイラーはエラーを返します。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 import { createEditBatch, Edits } from "@osdk/functions"; import { Aircraft, Employee } from "@ontology/sdk"; import { Client, Osdk } from "@osdk/client"; type OntologyEdit = Edits.Object<Aircraft> | Edits.Object<Employee>; export default function myFunction( client: Client, aircraft: Osdk.Instance<Aircraft>, employee: Osdk.Instance<Employee> ): OntologyEdit[] { const batch = createEditBatch<OntologyEdit>(client); batch.update(aircraft, { businessCapacity: 3 }); batch.update(employee, { department: "HR" }); return batch.getEdits(); }

TypeScript v2 では、Edits.Interface<MyInterface> を使用して、オントロジーインターフェースのプロパティを通じてオブジェクトを作成、更新、削除します。詳しくは、オントロジーの編集を参照してください。

TypeScript v1 では、関数の実行中に編集がオントロジーに適用されることは_ありません_。編集とオブジェクト検索のドキュメントで説明しているとおり、オブジェクトとリンクへの変更は、関数の実行が完了した後にのみ伝播され、関数ベースのアクション内で呼び出された場合に限られます。

TypeScript v2 では、この動作がより明示的になっています。編集を暗黙的に蓄積するのではなく、関数で編集バッチを使用して編集を追跡し、完了時に返す必要があります。

サポートされている操作の全一覧については、TypeScript v2 ドキュメントのオントロジーの編集セクションを参照してください。

TypeScript v2 は、書き込み後の読み取りを保証する別の実行モデルであるステージング書き込みもサポートしています。ステージング書き込み関数は、createEditBatch の代わりに WriteableClient を使用し、編集を明示的に返す必要はありません。

オブジェクトの一意の ID を生成する

TypeScript v1 で新しく作成したオブジェクトの一意の ID を生成するには、@foundry/functions-utils パッケージの Uuid ユーティリティを使用します。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 import { Edits, OntologyEditFunction } from "@foundry/functions-api"; import { Uuid } from "@foundry/functions-utils"; import { FlightScenario, Objects } from "@foundry/ontology-api"; export class ExampleEditFunctions { @Edits(FlightScenario) @OntologyEditFunction() public createFlightScenario(): void { const scenario = Objects.create().flightScenarios(Uuid.random()); scenario.scenarioName = "New scenario"; } }

TypeScript v2 は完全な Node.js 環境で実行されるため、代わりに node:crypto コアモジュールを使用できます。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 import { FlightScenario } from "@ontology/sdk"; import { Client } from "@osdk/client"; import { createEditBatch, Edits } from "@osdk/functions"; import { randomUUID } from "node:crypto"; type OntologyEdit = Edits.Object<FlightScenario>; export default function createFlightScenario(client: Client): OntologyEdit[] { const batch = createEditBatch<OntologyEdit>(client); batch.create(FlightScenario, { id: randomUUID(), scenarioName: "New scenario", }); return batch.getEdits(); }

関数本体の外にあるモジュールのトップレベルで、randomUUID やその他の乱数生成器を呼び出すことは避けてください。TypeScript v2 関数はウォーム呼び出しを使用します。この場合、すべてのモジュールレベルのコードは初期化中に1回評価され、その後の呼び出しで再利用されます。つまり、モジュールレベルの randomUUID 呼び出しは1回だけ評価され、ウォーム呼び出しのたびに同じ値を生成します。一意性を確保するため、ランダムな値は必ず関数本体内で生成してください。

オブジェクトをメモリーに読み込む

TypeScript v1 関数は、特定のタイプのすべてのオブジェクトをメモリーに読み込んで処理するための .all() および .allAsync() API を提供します。ただし、この方法では、オントロジー内のオブジェクト数が増えるにつれて、メモリー使用量が増大し、パフォーマンスが低下する可能性があります。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 import { Edits, OntologyEditFunction } from "@foundry/functions-api"; import { Aircraft, Objects } from "@foundry/ontology-api"; export class MyFunctions { @Edits(Aircraft) @OntologyEditFunction() public editAircraft(): void { const aircraft = Objects.search().aircraft().all(); aircraft.forEach(a => { a.arrived = true; }); } }

TypeScript v2 関数は、オントロジー SDK を介したオブジェクトのストリーミング処理をサポートしているため、すべてのオブジェクトを一度にメモリーに保持する必要がありません。可能な場合は、この方法を推奨します。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 import { Aircraft } from "@ontology/sdk"; import { Client } from "@osdk/client"; import { createEditBatch, Edits } from "@osdk/functions"; type OntologyEdit = Edits.Object<Aircraft>; export default async function editAircraft(client: Client): Promise<OntologyEdit[]> { const batch = createEditBatch<OntologyEdit>(client); for await (const a of client(Aircraft).asyncIter()) { batch.update(a, { arrived: true }); } return batch.getEdits(); }

データ規模が問題にならない場合は、次の代替方法で特定のタイプのすべてのオブジェクトを読み込めます。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 import { Aircraft } from "@ontology/sdk"; import { Client } from "@osdk/client"; import { createEditBatch, Edits } from "@osdk/functions"; type OntologyEdit = Edits.Object<Aircraft>; export default async function editAircraft(client: Client): Promise<OntologyEdit[]> { const batch = createEditBatch<OntologyEdit>(client); const aircraft = await Array.fromAsync(client(Aircraft).asyncIter()); aircraft.forEach(a => { batch.update(a, { arrived: true }); }); return batch.getEdits(); }