Python でのステージング書き込み [ベータ版]

ステージング書き込みは、オントロジー内のオブジェクトを編集する Python 関数に追加の実行モデルを提供します。通常の Python オントロジー編集関数とは異なり、ステージング書き込み関数には次の特徴があります。

• 関数内で適用されたオントロジー編集について、書き込み後の読み取りを保証します。関数内で適用されたすべての編集がステージングされ、関数内でその後に実行されるオントロジークエリや集計に反映されます。
• オントロジーを編集するほかのステージング書き込み関数をネストして呼び出せます。

このページでは、Python でステージング書き込み関数を記述する方法と、その固有の特性を説明します。TypeScript v2 については、TypeScript v2 関数でのステージング書き込みを参照してください。編集関数の仕組みについて詳しくは、オントロジー編集の概要を参照してください。

通常のオントロジー編集関数との主な違い

ステージング書き込み関数は、いくつかの重要な点で通常の編集関数と異なります。

書き込み後の読み取りの保証

ステージング書き込み関数内で読み取るオントロジーデータには、その関数内でそれまでに行われたすべての編集と、同じアクション実行内で呼び出し元のステージング書き込み関数が行ったすべての編集が反映されます。これらの編集はステージングされるだけであり、実行コンテキスト外のほかのユーザーや関数からは参照できません。関数内から検索リクエストや集計を使用してオントロジーをクエリでき、その結果には、それまでにステージングされたすべての編集が反映されます。

編集を返す必要がない

通常の Python オントロジー編集関数では、編集を適用するために、オントロジー編集のバッチを返す必要があります。ステージング書き込み関数では、編集が自動的にステージングされ、アクションの完了時にオントロジーに適用されます。関数は編集を返す代わりに、サポートされている任意の関数の戻り値のデータ型を返すことができます。

アトミックな実行

ステージング書き込み関数内のすべての操作は、クエリ、関数呼び出し、AIP Logic の実行を含め、編集をまとめてステージングします。関数が正常に完了すると、編集がオントロジーにコミットされます。関数でエラーが発生した場合、オントロジーは変更されず、アクションが関数を再試行する前に、ステージングされたすべての編集が破棄されます。

WriteableClient

Python のステージング書き込み関数では、標準の FoundryClient の代わりに、生成された WriteableClient を使用します。WriteableClient を使用して、ステージング書き込みコンテナを構築します。このコンテナは、通常の Python 編集コンテナと同じオブジェクト編集 API とリンク編集 API を提供しますが、コンテナの編集を関数から返す必要はありません。

ステージング書き込み関数を定義する

Python のステージング書き込み関数を定義するには、次のようにします。

• @function デコレーターで beta=True を設定します。
• デコレーターの edits パラメーターを使用して、ネストされた関数呼び出しによる編集も含め、関数が編集できるすべてのオブジェクトタイプとリンクタイプを宣言します。リンク編集を宣言するには、OntologyLinkType(SourceObjectType, "linkApiName") を使用します。
• 最初のパラメーターに、生成された WriteableClient データ型のアノテーションを付けます。関数ランタイムが、アクション実行のトランザクションコンテキストを持つクライアントを注入するため、関数内でクライアントを構築しないでください。
• サポートされている任意の関数の戻り値のデータ型を返します。

次の関数は、Employee オブジェクトタイプに対する編集を宣言して適用します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
from functions.api import Integer, function
from ontology_sdk import WriteableClient
from ontology_sdk.ontology.objects import Employee

@function(beta=True, edits=[Employee])
def update_employee_last_name(
    client: WriteableClient,
    employee_id: Integer,
    new_last_name: str,
) -> Integer:
    staged_writes = client.ontology.staged_writes()
    editable_employee = staged_writes.objects.Employee.edit(employee_id)
    editable_employee.last_name = new_last_name
    return employee_id

編集を適用するには、ステージング書き込み関数を関数ベースのアクションとして設定します。

オブジェクトを作成する

ステージング書き込みコンテナで、オブジェクトタイプの create メソッドを使用します。オブジェクトの主キーを指定する必要があり、同じ呼び出しでほかのプロパティも初期化できます。

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

@function(beta=True, edits=[Employee])
def create_employee(
    client: WriteableClient,
    employee_id: str,
    first_name: str,
    last_name: str,
) -> str:
    staged_writes = client.ontology.staged_writes()
    staged_writes.objects.Employee.create(
        employee_id=employee_id,
        first_name=first_name,
        last_name=last_name,
    )
    return employee_id

生成された ID でオブジェクトを作成する

主キーを生成してオブジェクトを作成し、同じ実行内で後からそのキーを返したり使用したりできます。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from uuid import uuid4

from functions.api import function
from ontology_sdk import WriteableClient
from ontology_sdk.ontology.objects import Ticket

@function(beta=True, edits=[Ticket])
def create_ticket(client: WriteableClient, title: str) -> str:
    ticket_id = str(uuid4())
    staged_writes = client.ontology.staged_writes()
    staged_writes.objects.Ticket.create(
        ticket_id=ticket_id,
        title=title,
        status="open",
    )
    return ticket_id

オブジェクトを更新する

ステージング書き込みコンテナで、オブジェクトタイプの edit メソッドを使用します。オブジェクトまたはその主キーを渡し、編集可能なオブジェクトに新しいプロパティ値を代入できます。

Copied!
1
2
3
4
5
6
staged_writes = client.ontology.staged_writes()
editable_employee = staged_writes.objects.Employee.edit(employee)
editable_employee.last_name = new_name

editable_employee = staged_writes.objects.Employee.edit(23)
editable_employee.last_name = new_name

ステージング書き込み関数はインターフェースの編集に対応していません。

オブジェクトを削除する

オブジェクトまたはその主キーを指定して、オブジェクトタイプの delete メソッドを呼び出します。

Copied!
1
2
3
staged_writes = client.ontology.staged_writes()
staged_writes.objects.Ticket.delete(ticket)
staged_writes.objects.Ticket.delete(12)

リンクを作成または削除する

ステージング書き込みコンテナを通じてオブジェクトを編集し、リンクプロパティの add メソッドまたは remove メソッドを使用して、多対多のリンクを編集します。

Copied!
1
2
3
4
staged_writes = client.ontology.staged_writes()
editable_employee = staged_writes.objects.Employee.edit(employee)
editable_employee.assigned_tickets.add(ticket)
editable_employee.assigned_tickets.remove(ticket)

一対多のリンクを編集するには、オブジェクトの作成または更新の編集を使用して、外部キープロパティを編集します。

ステージング書き込み関数内での書き込み後の読み取り

WriteableClient を通じた読み取りには、同じ実行内でそれまでに書き込まれたデータが反映されます。オントロジーの読み取り前に、クライアントが保留中の編集をステージングされたトランザクションに送信するため、クエリや集計にそれらの編集が含まれます。

次の関数は、チケットを作成した後、未完了のチケットの件数を集計します。結果には、新しく作成されたチケットが含まれます。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
from functions.api import Integer, function
from ontology_sdk import WriteableClient
from ontology_sdk.ontology.objects import Ticket

@function(beta=True, edits=[Ticket])
def create_ticket_and_count_open(
    client: WriteableClient,
    ticket_id: str,
    title: str,
) -> Integer:
    staged_writes = client.ontology.staged_writes()
    staged_writes.objects.Ticket.create(
        ticket_id=ticket_id,
        title=title,
        status="open",
    )
    return (
        client.ontology.objects.Ticket.where(
            Ticket.object_type.status == "open"
        )
        .count()
        .compute()
    )

ステージング書き込み関数からほかの関数を呼び出す

WriteableClient を通じて別の関数やクエリを呼び出すと、それらの操作は同じステージングされた編集に加わります。呼び出された関数内の読み取りには、その実行内でそれまでにステージングされた編集が反映され、呼び出された関数による編集も同じステージングされた編集に加わります。これは、次のものに適用されます。

• ほかの Python または TypeScript v2 のステージング書き込み関数
• AIP Logic 関数
• オントロジークエリ

最上位の関数が正常に完了すると、ネストされた呼び出し全体でステージングされたすべての編集がまとめてコミットされます。いずれかの呼び出しでエラーが発生すると、編集全体が破棄されます。

次の例では、assign_ticket は同じリポジトリから公開された別のステージング書き込み関数です。bulk_assign_tickets は、オントロジー SDK によって生成されたクエリ API を通じてこの関数を呼び出し、呼び出しのたびに、その編集が同じステージングされた編集に追加されます。

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

@function(
    beta=True,
    edits=[Ticket, OntologyLinkType(Employee, "assignedTickets")],
)
def bulk_assign_tickets(
    client: WriteableClient,
    employee_id: Integer,
    ticket_ids: list[str],
) -> Integer:
    for ticket_id in ticket_ids:
        client.ontology.queries.assign_ticket(
            employee_id=employee_id,
            ticket_id=ticket_id,
        )
    return len(ticket_ids)

実行ライフサイクル

ステージング書き込み関数では、次の実行ライフサイクルを使用します。

1. 関数の実行： 作成、更新、削除、読み取り、ネストされた関数呼び出しは、同じステージングされたトランザクションに加わります。編集は、その関数とネストされた関数から参照できますが、コミットされるまでは実行の外部には反映されません。
2. コミット： 関数が正常に完了すると、アクションが終了する前に、ステージングされたすべての編集がコミットされます。
3. エラー時のロールバック： 関数でエラーが発生した場合、オントロジーは変更されず、ステージングされたすべての編集が破棄されます。その後、アクションは関数を再試行できます。

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

@function(beta=True, edits=[Employee])
def update_employee_with_validation(
    client: WriteableClient,
    employee_id: Integer,
    new_salary: float,
) -> Integer:
    if new_salary < 0:
        raise ValueError("Salary cannot be negative")
    staged_writes = client.ontology.staged_writes()
    editable_employee = staged_writes.objects.Employee.edit(employee_id)
    editable_employee.salary = new_salary
    return employee_id