オントロジーの編集

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

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

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

編集関数を定義する

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

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

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

Python 関数でオントロジーを編集するには、まずオントロジー SDK クライアントからオントロジー編集コンテナを構築します。たとえば、次のようにします。

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 パラメーターでリンクタイプを宣言する必要があります。これにより、アクションが完全な来歴情報を受け取れるようになります。OntologyLinkType は、トラバース元のオブジェクトタイプと、そのオブジェクトタイプで定義されているリンクタイプのAPI名を受け取ります。このAPI名は、リンクタイプのオントロジーAPI名であり、編集可能なオブジェクト上でリンクにアクセスするために使用する属性とは異なる場合があります。

リンクの追加と削除の完全な例については、リンクタイプの編集の 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, Array, 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)