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

オントロジーの編集

オントロジーの編集とは、オブジェクトを作成、変更、または削除することです。関数は、関数ベースのアクションで使用するためにオントロジーの編集を返すことをサポートしています。

TypeScript v1 関数は、コードを簡素化する特別なセマンティクスを提供する @OntologyEditFunction デコレーターを使用して開発します。TypeScript v1 関数では、@Edits デコレーターも使用して、アクションに来歴情報を提供します。アクションは、この情報を権限の適用に使用できます。オントロジーの編集を検証するために利用可能な API を使用して、TypeScript v1 のオントロジー編集関数の単体テストを記述できます。
TypeScript v2 関数は、@osdk/functions パッケージからエクスポートされる createEditBatch 関数を使用して開発します。これらの関数は、Edits データ型を使用してアクションに来歴情報を提供します。
Python 関数は、オントロジー SDK からエクスポートされる FoundryClient を使用して編集コンテナを作成することで開発します。これらの関数は、@function デコレーターの edits パラメーターを使用してアクションに来歴情報を提供します。

リンクタイプの編集

2個のオブジェクト間のリンクを追加または削除することは、オブジェクトの作成やプロパティ値の変更と同様に、オントロジーの編集です。完全な来歴を記録するには、多対多リンクの編集を宣言します。一対一および一対多リンクの場合は、外部キーを保持するオブジェクトタイプへの編集を宣言します。

次の例では、assignedTickets は Employee オブジェクトタイプから Ticket オブジェクトタイプへの多対多リンクタイプです。この関数は、1個のチケットへのリンクを追加し、別のチケットへのリンクを削除します。

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

export class TicketLinkFunctions {
    @Edits(Employee, Ticket)
    @OntologyEditFunction()
    public reassignTicket(employee: Employee, ticketToAssign: Ticket, ticketToUnassign: Ticket): void {
        employee.assignedTickets.add(ticketToAssign);
        employee.assignedTickets.remove(ticketToUnassign);
    }
}

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import { Employee, Ticket } from "@ontology/sdk";
import { Client, Osdk } from "@osdk/client";
import { createEditBatch, Edits } from "@osdk/functions";

type OntologyEdit = Edits.Link<Employee, "assignedTickets">;

export default function reassignTicket(
    client: Client,
    employee: Osdk.Instance<Employee>,
    ticketToAssign: Osdk.Instance<Ticket>,
    ticketToUnassign: Osdk.Instance<Ticket>,
): OntologyEdit[] {
    const batch = createEditBatch<OntologyEdit>(client);

    batch.link(employee, "assignedTickets", ticketToAssign);
    batch.unlink(employee, "assignedTickets", ticketToUnassign);

    return batch.getEdits();
}

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
from functions.api import OntologyEdit, OntologyLinkType, function
from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import Employee, Ticket

@function(edits=[OntologyLinkType(Employee, "assignedTickets")])
def reassign_ticket(
    employee: Employee,
    ticket_to_assign: Ticket,
    ticket_to_unassign: Ticket,
) -> list[OntologyEdit]:
    ontology_edits = FoundryClient().ontology.edits()

    editable_employee = ontology_edits.objects.Employee.edit(employee)
    editable_employee.assigned_tickets.add(ticket_to_assign)
    editable_employee.assigned_tickets.remove(ticket_to_unassign)

    return ontology_edits.get_edits()

このドキュメントの以降の部分では、基盤となるインフラストラクチャをより深く理解できるよう、オントロジー編集関数の内部動作を説明します。

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

オントロジー編集関数についてよくある誤解は、関数を実行するとオントロジー内のオブジェクトが更新されるかどうかという点です。Authoring の関数ヘルパーでオントロジー編集関数を実行しても、実際のオブジェクトには編集が適用されません。関数を使用してオブジェクトを更新する唯一の方法は、関数ベースのアクションのドキュメントに記載されているように、その関数を使用するようアクションを設定することです。

つまり、オブジェクト自体が更新される心配をせずに、関数ヘルパーでオントロジー編集関数を自由に実行し、さまざまな入力に対する結果を検証できます。

結果ペイン

注意事項

編集とオブジェクト検索

オブジェクトとリンクへの変更は、関数の実行が完了した後にオブジェクトセット API に伝播されます。つまり、編集したプロパティやリンクに対するフィルター、関連検索、集計など、結果が編集後の値に依存する Objects.search() クエリは、編集前のオブジェクト、プロパティ、リンクを使用するため、作成や削除を含むオントロジーの編集が反映されない場合があります。この場合、関数内で手動で対応する必要があります。

これは、たとえば主キーを使用して、すでに編集した特定のオブジェクトを取得する場合とは異なります。その場合、関数のインフラストラクチャはオブジェクトの実体化時に保留中の編集を適用するため、編集後のプロパティ値とリンク値が返されます。例については、@Edits デコレーターを参照してください。

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

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

export class CaveatEditFunctions {
    @Edits(Employee)
    @OntologyEditFunction()
    public async editAndSearch(): Promise<void> {
        const employeeOne = Objects.search().employee().filter(e => e.id.exactMatch(1)).all()[0];
        employeeOne.name = "Bob";

        const count = await Objects.search().employee().filter(e => e.name.exactMatch("Bob")).count() ?? -1;
        console.log(count);
        // 期待値: 1、実際の値: 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
30
31
import { Client } from "@osdk/client";
import { Employee } from "@ontology/sdk";
import { Edits, createEditBatch } from "@osdk/functions";

type OntologyEdit = Edits.Object<Employee>;

async function editAndSearch(client: Client): Promise<OntologyEdit[]> {
    const batch = createEditBatch<OntologyEdit>(client);

    const employeeOne = await client(Employee).fetchOne(1);
    batch.update(employeeOne, { name: "Bob" });

    const count = await client(Employee)
        .where({
            name: {
                $eq: "Bob"
            }
        })
        .aggregate({
            $select: {
                $count: "unordered"
            }
        })
        .then(response => response.$count);
    console.log(count);
    // 期待値: 1、実際の値: 0

    return batch.getEdits();
}

export default editAndSearch;

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from functions.api import function, OntologyEdit
from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import Employee

@function(edits=[Employee])
def edit_and_search() -> list[OntologyEdit]:
    client = FoundryClient()
    ontology_edits = client.ontology.edits()

    employee = client.ontology.objects.Employee.get(1)
    editable_employee = ontology_edits.objects.Employee.edit(employee)
    editable_employee.name = "Bob"

    count = client.ontology.objects.Employee.where(Employee.object_type.name == "Bob").count().compute()
    print(count)
    # 期待値: 1、実際の値: 0

    return ontology_edits.get_edits()

Automate でオントロジーの編集を適用する

Automate は、効果として使用される関数が返す編集を適用しません。自動化を通じてオントロジーの編集を適用するには、代わりに関数ベースのアクションを設定します。詳細については、関数の効果を参照してください。

関数ベースのアクションにおける任意の配列

コードリポジトリで @OntologyEditFunction を実行する場合、省略された任意の配列は undefined として扱われますが、アクションを通じて関数を実行する場合は空の配列として渡されます。

←

PREVIOUSパフォーマンスおよび制限 / バージョン範囲の依存関係

NEXTクエリ

→