概要

オントロジーの編集は、オブジェクトを作成、変更、または削除する概念を指します。Functions は Function-backed Action で使用するための オントロジー編集 の返却をサポートします。これらの Functions は @OntologyEditFunction デコレータを使用して作成され、Functions の作成を容易にする特別なセマンティクスを提供します。

Functions はユーザーのコードのボックス分析を提供し、コード内で参照された編集されたオブジェクトタイプを検出します。これらの検出されたオブジェクトタイプは、Action provenance の提供に使用され、Actions サービスによるその権限の強制 に使用される可能性があります。編集されたオブジェクトタイプはコードリポジトリ内の Functions ヘルパーで検査できます。編集されたオブジェクトタイプが参照されているが検出されない場合、@Edits([object type]) デコレータを使用してオブジェクトタイプを 手動で指定 し、Actions 権限の正確な provenance を強制する必要があります。 オントロジー編集 Functions のユニットテストは オントロジー編集の検証 用の API を使用して記述できます。

このドキュメントの残りの部分では、オントロジー編集 Functions がバックエンドでどのように動作するかを説明し、基盤インフラストラクチャの理解を深めます。

編集が適用されるタイミング

オントロジー編集 Functions について一般的な誤解は、それらを実行するかどうかがオントロジー内のオブジェクトを更新するかどうかです。Authoring の Functions ヘルパー内でオントロジー編集 Function を実行すると、実際のオブジェクトには編集が適用されません。Function を使用してオブジェクトを更新する唯一の方法は、Function-backed Actions のドキュメンテーションに記述されているように、Action を設定して Function を使用することです。

これは、様々な入力に対する結果を検証するために、Functions ヘルパーで自由にオントロジー編集 Functions を実行でき、オブジェクト自体が更新されることを心配する必要がないことを意味します。

編集がどのようにキャプチャされるか

オントロジー編集 Function が実行されると、オブジェクトへのすべての更新が Functions インフラストラクチャによってキャプチャされ、Function 実行の終了時に返されます。これには、Objects.create() API を通じた新しいオブジェクトの作成、すべてのプロパティ更新、オブジェクト削除が含まれます。

編集は賢明に折り畳まれ、最小限の編集セットが Action で適用されます。例えば、新しいオブジェクトを作成し、そのプロパティを更新した場合、プロパティ更新を含む単一の オブジェクトの作成 編集が返されます。同様に、既存のオブジェクトの複数のプロパティを更新すると、すべてのプロパティ編集を含む単一の オブジェクトの更新 編集が返されます。オブジェクトを削除すると、削除前に行われた他のプロパティ編集はすべて消去されます。全体の Function が成功する必要があり、その結果、編集のリストが生成され、これが原子トランザクションを実行する Actions サービスに渡されます。

キャプチャされたオントロジー編集は、Function 実行からリストとして返されます。これが、オントロジー編集 Functions の戻りタイプが void または Promise<void> である必要がある理由です：実行された時、Function の真の戻りタイプはオントロジー編集のリストであるため、同時に他の値を返すことはできません。

編集は、単一の Function 実行の全体のライフサイクルにわたって単一の編集ストアでキャプチャされます。これは、オブジェクトを作成、更新、または削除するヘルパー関数を呼び出すことが可能であることを意味します。例えば：

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
30
31
32
export class HelperEditFunctions {
    @Edits(ObjectA, ObjectB)
    @OntologyEditFunction()
    // この関数は、新しいオブジェクトを作成し、それらをリンクします。
    public createAndLink(): void {
        // ObjectAを作成します。
        const objectA = this.createObjectA();
        // ObjectBを作成します。
        const objectB = this.createObjectB();
        // ObjectAをObjectBにリンクします。
        objectA.linkToB.set(objectB);
    }

    /**
     * @OntologyEditFunction()で注釈されていなくても、これらのヘルパー関数は
     * 他の編集関数で使用する新しいオブジェクトを作成することができます。
     */
    // ObjectAを作成するプライベートなメソッドです。
    private createObjectA(): ObjectA {
        const objectA = Objects.create().objectA(generateRandomId());
        objectA.prop1 = "example";
        objectA.prop2 = 42;
        return objectA;
    }

    // ObjectBを作成するプライベートなメソッドです。
    private createObjectB(): ObjectB {
        const objectB = Objects.create.objectB(generateRandomId());
        objectB.prop1 = "another example";
        return objectB;
    }
}

編集した値の取得

関数で編集が行われると、関数のインフラストラクチャは編集した値を読み出すときにそれらを返します。例えば、オブジェクトのプロパティを設定し、それを取得すると新しい値が返されます：

airplane.departureTime = newDepartureTime; // 飛行機の出発時間を新しい出発時間に設定します
console.log(airplane.departureTime); // 新しい出発時間をログに出力します

オブジェクトを削除すると、検索結果から削除され、そのプロパティにアクセスできなくなります。

注: 編集とオブジェクト検索

オブジェクトとリンクの変更は、関数の実行が終了した後に Objects.search() API に伝播されます。これは、Objects.search() API が古いオブジェクト、プロパティ、およびリンクを使用することを意味します。その結果、検索、フィルタリング、周辺検索、および集計は、オントロジーへの編集（作成や削除を含む）を反映しない場合があります。関数は、このケースを手動で処理する必要があります。

次の例では、ID 1 の従業員が存在すると仮定します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { OntologyEditFunction } from "@foundry/functions-api";
import { Employee, Objects } from "@foundry/ontology-api";

export class CaveatEditFunctions {
    @OntologyEditFunction()
    public async editAndSearch(): Promise<void> {
        // 従業員の検索
        let employeeOne = Objects.search().employee().filter(e => e.id.exactMatch(1)).all()[0];
        // 従業員の名前を変更
        employeeOne.name = "Bob";
        // "Bob"という名前の従業員の数を検索
        console.log(await Objects.search().employee().filter(e => e.name.exactMatch("Bob").count() ?? -1);
        // 期待値: 1, 実際の値: 0
    }
}

編集されたオブジェクトタイプを手動で指定する

Functions は、編集されたオブジェクトタイプをコードでインテリジェントに分析します。このプロヴェナンスは、権限を強制するために Actions などの他のサービスで使用されることがあります。プロヴェナンスを正しく指定することが重要です。 まれに、コードの静的解析が参照された編集されたオブジェクトタイプの検出に失敗することがあります（例えば、オブジェクトタイプを any としてキャストする場合）。その場合、@Edits([object type]) デコレータを Functions の上に手動で追加し、オブジェクトタイプを指定する必要があります。

例

次の例では、2つのオブジェクトタイプ（Employee と Aircraft）が、次の関数によって編集されます。

Copied!
1
2
3
4
5
6
7
8
9
10
11
import { OntologyEditFunction } from "@foundry/functions-api";
import { Employee, Aircraft, Objects } from "@foundry/ontology-api";
export class ManuallySpecifyingObjectFunction {
    @OntologyEditFunction()
    public myFunction(): void {
        const x = Objects.search().aircraft().all()[0];
        x.businessCapacity = 3; // "Aircraft" オブジェクトタイプのビジネス容量を3に設定します。
        const y = Objects.search().employee().all()[0];
        (y as any).department = ""// 期待: "Employee" と "Aircraft" オブジェクトタイプを検出、実際: "Aircraft" オブジェクトタイプのみを検出
    }
}

コードリポジトリの Functions ヘルパーから、Aircraftという1つのオブジェクトタイプだけが検出されたことがわかります。これは、2つ目のオブジェクトタイプであるEmployeeがanyとしてキャストされ、型が失われたからです。

これは、デコレータ@Edits(Employee)を使用してオブジェクトタイプを手動で指定することで解決できます。import {Edits} from "@foundry/functions-api"を忘れないでください。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
import { OntologyEditFunction, Edits } from "@foundry/functions-api"; // Editsをインポート
import { Employee, Aircraft, Objects } from "@foundry/ontology-api"; 
export class ManuallySpecifyingObjectFunction {
    @Edits(Employee) // このデコレータは手動でオブジェクトタイプ"Employee"を編集済みオブジェクトタイプの由来リストに追加することを指定します。
    @OntologyEditFunction()
    public myFunction(): void {
        const x = Objects.search().aircraft().all()[0]; // 最初の航空機オブジェクトを取得
        x.businessCapacity = 3; // ビジネスキャパシティを3に設定
        const y = Objects.search().employee().all()[0]; // 最初の従業員オブジェクトを取得
        (y as any).department = "" // 部署を空文字列に設定
    }
}

コードリポジトリのFunctionsヘルパーから、すべての編集されたオブジェクトタイプが検出されていることがわかります。