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

オントロジーの編集

オントロジーからデータを読み取る関数に加えて、オブジェクトを作成し、オブジェクトのプロパティやオブジェクト間のリンクを編集する関数も記述できます。このページでは、関数で利用可能なオブジェクト編集 API について説明します。編集関数の動作の詳細については、概要ページを参照してください。

関数で作成された編集を実際に適用するには、オントロジー編集関数を必ず関数ベースのアクションとして設定する必要があります。このようにアクションを設定すると、追加のメタデータの指定、権限の設定、さまざまな業務用インターフェースからのアクションへのアクセスが可能になります。ドキュメントに記載されているとおり、アクションの外部で編集関数を実行しても、オブジェクトデータは実際には変更されません。

標準のオントロジー編集では、編集バッチを使用します。TypeScript v2 はステージングされた書き込みもサポートしており、関数内で書き込み後の読み取りが保証されます。編集内容は、同じ実行内の後続のクエリですぐに参照でき、ステージングされた書き込みを行う関数のネストされた呼び出しでも共有されます。関数が書き込んだばかりのデータを読み取る必要がある場合は、ステージングされた書き込みを使用します。ステージングされた書き込みは開発ライフサイクルのベータ版段階にあり、お使いのエンロールメントでは利用できない場合があります。

予期しない検索結果は編集バッチに影響しますが、ステージングされた書き込みには影響しません

編集バッチを使用する場合、オブジェクトを編集した直後に検索すると、予期しない結果が返されることがあります。この注意点は、ステージングされた書き込みには適用されません。詳細については、注意事項のセクションを参照してください。

編集関数を定義する

オントロジーを編集する関数では、@osdk/functions パッケージからエクスポートされる Edits 型を使用して、編集するエンティティを明示的に宣言する必要があります。次の例では、Employee および Ticket オブジェクトタイプと、Employee と Ticket の間のリンクタイプに対する編集を表す新しい型を宣言しています。複数のエンティティに対する編集は、| 演算子で結合する必要があります。

Copied!1
2
3
4
import { Employee, Person, Ticket } from "@ontology/sdk";
import { Edits } from "@osdk/functions";

type OntologyEdit = Edits.Object<Employee> | Edits.Interface<Person> | Edits.Object<Ticket> | Edits.Link<Employee, "assignedTickets">;

次に、関数がこの新しい型の編集の配列を返すことを宣言する必要があります。

Copied!1
2
3
export default function createNewTicketAndAssignToEmployee(): OntologyEdit[] {
    // ...
}

オントロジー編集バッチを構築する

TypeScript v2 関数でオントロジーを編集するには、まず @osdk/functions からエクスポートされる createEditBatch 関数を使用し、先ほど宣言した型を型引数として渡して、オントロジー編集バッチを構築します。

Copied!1
2
3
4
5
6
7
8
9
10
11
import { Employee, Ticket } from "@ontology/sdk";
import { Client } from "@osdk/client";
import { createEditBatch, Edits } from "@osdk/functions";

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

export default function createNewTicketAndAssignToEmployee(client: Client): OntologyEdit[] {

    const batch = createEditBatch<OntologyEdit>(client);
    // ...
}

このバッチは、関数内で行われるすべての編集を追跡するために使用されます。

プロパティを更新する

オブジェクトプロパティ

1個以上のオブジェクトプロパティを変更するには、作成したバッチで利用可能な update メソッドを使用します。

Copied!1
batch.update(employee, { lastName: newName });

employee オブジェクトのインスタンスをメモリーに読み込んでいない場合でも、オブジェクトのAPI名と主キーを参照して更新できます。

Copied!1
batch.update({ $apiName: "Employee", $primaryKey: 23 }, { lastName: newName });

同じ関数の実行内で、後から employee の lastName プロパティ値にアクセスしても、編集バッチで update を呼び出したときの変更は反映_されません_。

オブジェクトタイプのあるインスタンスから別のインスタンスへ、すべてのプロパティ値をコピーすると便利な場合があります。次の例では、employee2 のプロパティ値を employee1 に代入しています。

Copied!1
batch.update(employee1, employee2);

既存のオブジェクトの主キープロパティ値は更新できません。

インターフェースプロパティ

update メソッドを使用すると、オントロジーインターフェースを通じてオブジェクトのインターフェースプロパティを変更できます。以下の例では、person の型はオントロジーインターフェースですが、その基になるインスタンスは Person インターフェースを実装するオブジェクトです。

update メソッドは、オブジェクトタイプとインターフェースのどちらの場合も2個の引数を受け取ります。インターフェースの場合は、変更するインターフェースと、変更するインターフェースプロパティを受け取ります。

Copied!1
batch.update(person, { firstName: newFirstName });

基になるオブジェクトの主キープロパティによって実装されているインターフェースプロパティは更新できません。

リンクを更新する

多対多リンクの場合、作成したバッチの link および unlink メソッドを使用して、オブジェクト間のリンクを追加または削除できます。

Copied!1
2
3
4
5
// 従業員をオフィスに割り当てます。
batch.link(employee, "office", office);

// 従業員のオフィスへの割り当てを解除します。
batch.unlink(employee, "office", office);

この方法で編集するすべてのリンクタイプを Edits.Link で宣言します。最初の型引数はトラバースの起点となるオブジェクトタイプで、2番目はそのオブジェクトタイプで定義されているリンクタイプのAPI名です。リンクの追加と削除の完全な例については、リンクタイプの編集の TypeScript v2 タブを参照してください。

リンクタイプが複数の対象を持つことができる場合は、link と unlink に配列を渡すことで、複数のリンクを一度に編集できます。配列の各要素から、個別のリンク編集が生成されます。

一対一および一対多リンクの場合は、作成したバッチで利用可能な update メソッドを使用して、ソースオブジェクトの外部キープロパティを変更します。以下の例では、一対多リンクは Ticket オブジェクトタイプの assignedEmployeeId 外部キープロパティに基づいているため、リンクの編集はオブジェクトの編集になります。この場合、宣言する必要があるのは Edits.Object<Ticket> のみです。

Copied!1
2
3
4
5
// チケットを従業員に割り当てます。
batch.update({ $apiName: "Ticket", $primaryKey: 13 }, { assignedEmployeeId: 52 });

// チケットの割り当てを解除します。
batch.update({ $apiName: "Ticket", $primaryKey: 13 }, { assignedEmployeeId: undefined });

プロパティを更新する場合と同様に、オブジェクトタイプの具体的なインスタンスを事前に読み込んでいない場合でも、API名と主キーを使用してリンクのいずれの側も参照できます。

Copied!1
2
3
4
5
// チケットを従業員に割り当てます。
batch.link({ $apiName: "Employee", $primaryKey: 23 }, "assignedTickets", { $apiName: "Ticket", $primaryKey: 12 });

// チケットの従業員への割り当てを解除します。
batch.unlink({ $apiName: "Employee", $primaryKey: 23 }, "assignedTickets", { $apiName: "Ticket", $primaryKey: 12 });

オブジェクトを作成する

オブジェクト

編集バッチの create メソッドを使用して、新しいオブジェクトを作成できます。新しいオブジェクトを作成するときは、主キーの値を指定する必要があり、ほかのプロパティも任意で初期化できます。

この例では、指定された ID を持つ新しい Ticket オブジェクトを作成し、その dueDate プロパティを設定して、assignedTickets リンクを変更することで指定された Employee に割り当てています。dueDate の新しい値の計算を簡単にするために、luxon ライブラリーを使用しています。

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
import { Employee, Ticket } from "@ontology/sdk";
import { Client, Osdk } from "@osdk/client";
import { createEditBatch, Edits, Integer } from "@osdk/functions";
import { DateTime } from "luxon";

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

export default function createNewTicketAndAssignToEmployee(
    client: Client,
    employee: Osdk.Instance<Employee>,
    ticketId: Integer,
): OntologyEdit[] {
    const batch = createEditBatch<OntologyEdit>(client);

    batch.create(Ticket, {
        ticketId,
        dueDate: DateTime.now().plus({ days: 7 }).toFormat('yyyy-MM-dd'),
    });

    // 新しいチケットはオントロジー内に具体的なインスタンスとして存在しませんが、
    // そのAPI名と主キーを参照することでリンクできます。
    batch.link(employee, "assignedTickets", { $apiName: "Ticket", $primaryKey: ticketId });

    return batch.getEdits();
}

インターフェース

create メソッドを呼び出し、インターフェース、基になるオブジェクトタイプ、インターフェースプロパティを指定することで、インターフェースを通じて新しいオブジェクトのインスタンスを作成できます。指定するインターフェースプロパティのうち1個は、基になるオブジェクトタイプの主キープロパティによって実装されている必要があります。

Copied!1
2
3
4
5
editBatch.create(Person, {
    $objectType: "Employee",
    firstName: "John",
    lastName: "Doe",
});

オブジェクトを削除する

オブジェクト

編集バッチの delete メソッドを呼び出すことで、オブジェクトを削除できます。

この例では、指定された従業員に割り当てられているすべてのチケットを削除しています。

Copied!1
2
3
for await (const ticket of employee.$link.assignedTickets.asyncIter()) {
    batch.delete(ticket);
}

インスタンスの代わりに主キーを使用してオブジェクトを削除することもできます。

Copied!1
batch.delete({ $apiName: "Ticket", $primaryKey: 12 });

インターフェース

delete メソッドを呼び出すことで、インターフェースを通じてオブジェクトを削除できます。

Copied!1
batch.delete(person);

構造体プロパティの編集

オブジェクトタイプとインターフェースタイプのどちらでも、オントロジーの構造体プロパティは TypeScript v2 関数で編集できます。TypeScript v2 の構造体型は、TypeScript インターフェースを使用して定義されます。関数内の構造体型は、構造体プロパティと同じフィールドを含み、フィールド名がオントロジーの構造体プロパティのフィールドのAPI名と一致していれば、オントロジーの構造体プロパティの編集に使用できます。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
interface Address {
    street: string,
    city: string,
    state: string,
    country: string,
    zipcode: string,
}

export default function updateEmployeeAddress(
    client: Client,
    employee: Osdk.Instance<Employee>,
    newAddress: Address
): OntologyEdit[] {
    const batch = createEditBatch<OntologyEdit>(client);
    batch.update(employee, { address: newAddress });
    return batch.getEdits();
}

←

PREVIOUSTypeScript v1 から TypeScript v2 へ移行する

NEXTステージングされた書き込み

→