オントロジーの編集

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

Python は、書き込み後の読み取りを保証し、ほかのステージング書き込み関数へのネストされた呼び出しを可能にするステージング書き込みもサポートしています。関数で編集直後のデータをクエリする必要がある場合は、ステージング書き込みを使用します。

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

編集関数を定義する

オントロジーを編集する関数は、次の要件を満たす必要があります。

• 編集するオブジェクトタイプを指定するために、functions.api からインポートした @function(edits=[MyObjectType]) デコレーターで修飾します。
• 編集する多対多のリンクタイプを、同じく functions.api からインポートした OntologyLinkType(SourceObjectType, "linkApiName") で宣言します。詳細については、編集するリンクタイプを宣言するを参照してください。
• functions.api からインポートした list[OntologyEdit] を、戻り値の型ヒントとして明示します。

オントロジー編集コンテナを構築する

Python 関数でオントロジーを編集するには、まず OSDK クライアントからオントロジー編集コンテナを構築します。例：

Copied!
1
ontology_edits = FoundryClient().ontology.edits()

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

プロパティを更新する

Python 関数内のオントロジーオブジェクトは、デフォルトで読み取り専用です。プロパティを変更しようとすると、例外が発生します。

オブジェクトを編集するには、まずオントロジー編集コンテナを使用して、そのオブジェクトの編集可能なビューを取得します。既存のオブジェクトのインスタンスから取得する方法：

Copied!
1
editable_object = ontology_edits.objects.MyObjectType.edit(my_object)

または、オブジェクトの主キーを指定して取得する方法があります。

Copied!
1
editable_object = ontology_edits.objects.MyObjectType.edit(object_primary_key)

編集可能なオブジェクトを取得したら、オブジェクトのプロパティ値を再代入して編集できます。例：

Copied!
1
editable_employee.last_name = new_name

同じ関数の実行中に、その後 editable_employee の last_name プロパティ値にアクセスすると、直前に設定した新しい値が返されます。ただし、元の編集不可のオブジェクトには変更が_反映されません_。

編集可能なオブジェクトの配列プロパティは、変更可能な list 値ですが、編集が記録されるのはプロパティに代入したときのみです。そのため、リストを直接変更しても、通知なく破棄されます。配列を変更するには、コピーを作成し、そのコピーを変更してからプロパティを更新します。

Copied!
1
2
3
4
5
6
# 新しい配列にコピーします
array_copy = list(editable_object.my_array_property)
# コピーした配列を変更できるようになります
array_copy.append(new_item)
# 次にプロパティ値を上書きします
editable_object.my_array_property = array_copy

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

構造体プロパティを編集する

オブジェクトを作成する際は、まず create() を呼び出し、返された編集可能なオブジェクトの構造体プロパティに代入します。構造体プロパティをキーワード引数として create() に直接渡すことはできません。

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

@function(beta=True, edits=[MyObjectType])
def create_object(primary_key: str) -> list[OntologyEdit]:
    ontology_edits = FoundryClient().ontology.edits()

    new_object = ontology_edits.objects.MyObjectType.create(primary_key)
    new_object.my_struct_property = MyStructPropertyClass(
        first_field="Example value",
        second_field=True,
    )

    return ontology_edits.get_edits()

生成された構造体プロパティクラスは、Python のフィールド名を対応するオントロジーのAPI名に変換します。ユーザー定義クラスや dataclass を代わりに使用することはできません。

既存の構造体プロパティ内のフィールドを更新するには、フィールドを変更した後、構造体プロパティ全体を編集可能なオブジェクトに再代入します。

Copied!
1
2
3
4
5
editable_object = ontology_edits.objects.MyObjectType.edit(my_object)

struct_property = editable_object.my_struct_property
struct_property.first_field = "Updated value"
editable_object.my_struct_property = struct_property

editable_object.my_struct_property.first_field = "Updated value" のようにフィールドを直接変更しても、オントロジーの編集は登録されません。

リンクを更新する

単一リンクプロパティと複数リンクプロパティには、リンクを更新するためのさまざまなメソッドがあります。

Copied!
1
2
3
4
5
6
7
8
9
10
11
# Employee の上司を設定します
editable_employee.supervisor.set(new_supervisor)

# Employee の上司をクリアします
editable_employee.supervisor.clear()

# 指定された従業員に新しい部下を追加します
editable_employee.reports.add(new_report)

# 指定された従業員に関連付けられた以前の部下を外します
editable_employee.reports.remove(new_report)

プロパティの更新と同様に、更新後に editable_employee のリンクにアクセスすると、行った更新が反映されます。

編集するリンクタイプを宣言する

多対多のリンクを編集する関数では、アクションが完全な来歴情報を受け取れるように、OntologyLinkType を使用して @function デコレーターの edits パラメーターにリンクタイプを宣言する必要があります。

functions.api から OntologyLinkType をインポートし、リンクをたどる起点のオブジェクトタイプと、リンクタイプの正確なAPI名を指定します。API名は、生成された Python の snake_case 属性名と異なる場合があります。たとえば、Python で editable_employee.assigned_tickets としてアクセスするリンクを宣言するには、OntologyLinkType(Employee, "assignedTickets") を使用します。

リンクタイプを宣言すると、関数を Marketplace 製品にパッケージ化する際に、そのリンクタイプを依存関係として識別するために Marketplace が使用する情報が提供されます。

リンクの追加と削除の完全な例については、リンクタイプの編集の Python タブを参照してください。

一対一および一対多のリンクは、2つのオブジェクトタイプのいずれかにある外部キープロパティに基づいているため、設定またはクリアすると、リンクの編集ではなくオブジェクトの編集が作成されます。これらのリンクタイプでは、リンクタイプを宣言する代わりに、外部キーを保持するオブジェクトタイプを宣言します。

オブジェクトを作成する

オントロジー編集コンテナの MyObjectType.create() メソッドを使用して、新しいオブジェクトを作成できます。新しいオブジェクトを作成する際は、主キーの値を指定する必要があります。

この例では、指定された ID を持つ新しい Ticket オブジェクトを作成し、due_date プロパティを設定し、assigned_tickets リンクを変更して、指定された Employee に割り当てます。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
from datetime import datetime, timedelta

from functions.api import function, Integer, OntologyEdit, OntologyLinkType
from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import Employee, Ticket

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

    new_ticket = ontology_edits.objects.Ticket.create(ticket_id)
    new_ticket.due_date = datetime.now() + timedelta(days=7)

    editable_employee = ontology_edits.objects.Employee.edit(employee)
    editable_employee.assigned_tickets.add(new_ticket)

    return ontology_edits.get_edits()

主キーに加えて、構造体以外のプロパティ値も create メソッドに直接渡すことができます。例：

Copied!
1
2
new_due_date = datetime.now() + timedelta(days=7)
new_ticket = ontology_edits.objects.Ticket.create(ticket_id, due_date=new_due_date)

オブジェクトを削除する

オントロジー編集コンテナの MyObjectType.delete() メソッドを呼び出すと、オブジェクトを削除できます。

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

Copied!
1
2
for ticket in employee.tickets:
    ontology_edits.objects.Ticket.delete(ticket)

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

Copied!
1
ontology_edits.objects.Ticket.delete(ticket_id)