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

オントロジー SDK でシナリオを使用する

試験的

オントロジー SDK のシナリオ対応は試験的であり、お使いのエンロールメントでは利用できない場合があります。このページで説明する API は現在も活発に開発が進められており、変更される可能性があることにご注意ください。

オントロジー SDK を使用すると、アプリケーションコードから直接オントロジーシナリオを作成して操作できます。シナリオをスコープとするクライアントは、通常のオントロジー SDK クライアントと同じように動作します。読み取るすべてのオブジェクト、実行するすべての集計、適用するすべてのアクションは、メインのオントロジーではなく、シナリオの分離されたサンドボックスに対して自動的に評価されます。

シナリオ機能は、TypeScript と Python の両方のオントロジー SDK で利用可能です。以下のセクションでは、それぞれの言語で次の操作を実行する方法を説明します。

新しいシナリオを作成するか、既存のシナリオにアタッチします。
シナリオのコンテキストでオブジェクトを読み取り、クエリを実行します。
シナリオ内でアクションと編集を適用します。
シナリオをメインのオントロジーにマージします。
シナリオ内で編集されたエンティティを一覧表示します。

TypeScript オントロジー SDK

シナリオ機能は、@osdk/client のバージョン 2.27.0 以降で利用可能です。Developer Console で、対応するバージョンの SDK を生成してください。

カスタムウィジェットはオントロジー SDK を使用しており、シナリオを作成して操作することもできます。詳細については、ウィジェットセットでオントロジー SDK を使用するを参照してください。

シナリオを作成する、またはシナリオにアタッチする

新しいシナリオを作成するには createScenario を使用し、RID を指定して既存のシナリオにアタッチするには withScenario を使用します。どちらの関数も、シナリオをスコープとするクライアントを返します。

Copied!1
2
3
4
5
6
7
8
9
10
import { createScenario, withScenario } from "@osdk/client/unstable-do-not-use";

// 新しいシナリオを作成します。プラットフォームを呼び出すため、非同期処理です。
const scenario = await createScenario(client);

// または、RID を指定して既存のシナリオにアタッチします。これは同期処理で、ネットワーク呼び出しは行いません。
const existingScenario = withScenario(client, "ri.actions..scenario.0000-...");

// 永続化または共有するために、シナリオの参照（RID）を取得します。
const scenarioRid: string = scenario.getScenarioReference();

ベースとなる client にブランチが設定されている場合、createScenario で作成される新しいシナリオは、そのブランチをベースとして使用します。

保存されたシナリオオブジェクトとして格納されているシナリオにアタッチすることもできます。保存されたシナリオオブジェクトの主キーはシナリオ参照なので、オブジェクトの $primaryKey を withScenario に渡します。

Copied!1
2
3
// `scenarioObject` は、たとえばオブジェクトセットのクエリから取得した、すでに手元にある永続化済みのシナリオオブジェクトです。
// シナリオオブジェクトの主キーは、シナリオの参照（RID）です。
const scenario = withScenario(client, scenarioObject.$primaryKey);

シナリオ内のオブジェクトをクエリする

シナリオクライアントは、通常のオントロジー SDK クライアントとまったく同じように呼び出せます。すべての読み取りのスコープは、自動的にシナリオに限定されます。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
import { Restaurant } from "@my-app/sdk";

// シナリオ内での状態を反映したオブジェクトを1ページ分読み込みます。
const page = await scenario(Restaurant).fetchPage();

// フィルターと集計もシナリオに対して評価されます。
const filtered = await scenario(Restaurant)
  .where({ numberOfReviews: { $gte: 100 } })
  .fetchPage();

const counts = await scenario(Restaurant).aggregate({
  $select: { $count: "unordered" },
});

シナリオ内でアクションを適用する

シナリオクライアントを通じてアクションを適用して、シナリオのサンドボックス内で編集をステージングします。これらの編集は、シナリオがマージされるまでメインのオントロジーに影響しません。

Copied!1
2
3
4
5
6
7
import { addReview } from "@my-app/sdk";

const result = await scenario(addReview).applyAction({
  restaurantId: "restaurantId",
  reviewRating: 5,
  reviewSummary: "It was great!",
});

シナリオ内でアクションを適用する場合、バッチアクションには対応していません。また、シナリオを別のシナリオ内にネストしたり、トランザクションと組み合わせたりすることはできません。

シナリオをマージする

シナリオをマージするには、シナリオの適用ルールが設定された任意のアクションタイプを適用します。このルールをアクションに追加すると、scenarioReference 型のシナリオパラメーターが自動的に公開されます。そのパラメーターの値としてシナリオクライアントを直接渡します。オントロジー SDK が自動的にシナリオ参照に解決します。

Copied!1
2
3
4
5
import { applyScenario } from "@my-app/sdk";

// `applyScenario` は Apply Scenario ルールで設定されたアクションで、
// `scenario` という名前のシナリオパラメーターを公開します。
await client(applyScenario).applyAction({ scenario });

アクション名とパラメーター名は、お使いのオントロジー固有のものです。アクションタイプにシナリオの適用ルールを設定する方法については、シナリオをマージするを参照してください。

シナリオ内で編集されたエンティティを一覧表示する

シナリオクライアントには、シナリオ内でどのオブジェクトとリンクが編集されたかを確認するメソッドが用意されています。結果として返される識別子には、$apiName と $primaryKey フィールドのみが設定されています。プロパティ値をすべて読み込むには、シナリオクライアントに主キーを渡して再取得します。

編集されたオブジェクト

getEditedEntityTypes を使用して、どのオブジェクトタイプとリンクタイプが変更されたかを確認します。次に、getEditedEntities を使用して指定したタイプの編集済みオブジェクトをページ単位で取得するか、editedEntitiesAsyncIter を使用してストリーミングで取得します。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import { Restaurant } from "@my-app/sdk";

// シナリオ内で編集されたオブジェクトタイプとリンクタイプを確認します。
const { objectTypes, linkTypes } = await scenario.getEditedEntityTypes();

// 指定したオブジェクトタイプの編集済みオブジェクトをページ単位で取得します。
const editedPage = await scenario.getEditedEntities(Restaurant, { pageSize: 500 });
for (const obj of editedPage.data) {
  console.log(obj.$apiName, obj.$primaryKey);
}

// または、指定したオブジェクトタイプの編集済みオブジェクトをすべてストリーミングします。イテレーターは自動でページ分割し、主キーに基づいて重複を排除します。
for await (
  const obj of scenario.editedEntitiesAsyncIter(Restaurant, { pageSize: 500 })
) {
  console.log(obj.$primaryKey);
}

編集されたオブジェクトのプロパティ値をすべて読み込むには、シナリオクライアントを通じて再取得します。

Copied!1
2
3
4
const keys = editedPage.data.map((obj) => obj.$primaryKey);
const full = await scenario(Restaurant)
  .where({ $primaryKey: { $in: keys } })
  .fetchPage();

編集されたリンク

getEditedLinkTypes、getEditedLinks、editedLinksAsyncIter を使用して、編集されたリンクを確認します。編集されたリンクはそれぞれ、source、target、linkType の有向の3つ組として返されます。返されるのは多対多のリンクのみです。編集された一対多のリンクは、外部キーを持つオブジェクトタイプに対する getEditedEntities を通じて確認できます。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { Restaurant } from "@my-app/sdk";

// 指定したオブジェクトタイプについて、編集された多対多のリンクタイプを確認します。
const editedLinkTypes = await scenario.getEditedLinkTypes(Restaurant);

// 指定したリンクタイプの編集済みリンクをページ単位で取得します。
const linksPage = await scenario.getEditedLinks(Restaurant, "sisterRestaurants", {
  pageSize: 200,
});
for (const { source, target, linkType } of linksPage.data) {
  console.log(source.$primaryKey, "->", target.$primaryKey, `(${linkType})`);
}

// または、指定したリンクタイプの編集済みリンクをすべてストリーミングします。
for await (
  const { source, target } of scenario.editedLinksAsyncIter(
    Restaurant,
    "sisterRestaurants",
  )
) {
  console.log(source.$primaryKey, "->", target.$primaryKey);
}

Python オントロジー SDK

シナリオ機能は、Python オントロジー SDK のバージョン 2.209.0 以降で利用可能です。編集されたオブジェクトとリンクを一覧表示するには、バージョン 2.221.0 以降が必要です。シナリオ対応はベータ機能です。シナリオのコードは AllowBetaFeatures コンテキスト内で実行する必要があります。

シナリオを作成する、またはシナリオにアタッチする

新しいシナリオを作成するには ScenarioClient.create を使用し、RID を指定して既存のシナリオにアタッチするには ScenarioClient コンストラクターを使用します。どちらも、シナリオをスコープとするクライアントを返します。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
from foundry_sdk_runtime import AllowBetaFeatures
from osdk import FoundryClient, ScenarioClient, UserTokenAuth

with AllowBetaFeatures():
    # 新しいシナリオを作成します。プラットフォームを呼び出してシナリオを発行します。
    scenario_client = ScenarioClient.create(client)

    # または、RID を指定して既存のシナリオにアタッチします。
    scenario_client = ScenarioClient(
        client, scenario_rid="ri.actions..scenario.0000-..."
    )

    # 永続化または共有するために、シナリオの参照（RID）を取得します。
    scenario_rid = scenario_client.scenario_rid

ScenarioClient.create で作成される新しいシナリオは、ベースとなる client のオントロジーとブランチを継承します。ScenarioClient に渡すベースクライアント自体がシナリオクライアントであってはなりません。

保存されたシナリオオブジェクトとして格納されているシナリオにアタッチすることもできます。保存されたシナリオオブジェクトの主キーはシナリオ参照なので、オブジェクトの主キーを ScenarioClient コンストラクターに渡します。

Copied!1
2
3
4
5
6
with AllowBetaFeatures():
    # `scenario_object` は、たとえばクエリから取得した、すでに手元にある永続化済みのシナリオオブジェクトです。
    # シナリオオブジェクトの主キーは、シナリオの参照（RID）です。
    scenario_client = ScenarioClient(
        client, scenario_rid=scenario_object.get_primary_key()
    )

シナリオ内のオブジェクトをクエリする

scenario_client.ontology.objects を通じてオブジェクトを読み取り、クエリを実行します。すべての読み取りのスコープは、自動的にシナリオに限定されます。

Copied!1
2
3
4
5
6
with AllowBetaFeatures():
    # シナリオ内での状態を反映したオブジェクトを1個読み込みます。
    restaurant = scenario_client.ontology.objects.ExampleRestaurant.get("primaryKey")

    # シナリオ内からオブジェクトを1ページ分読み込みます。
    page = scenario_client.ontology.objects.ExampleRestaurant.page(page_size=30)

シナリオ内でアクションを適用する

Copied!1
2
3
4
5
6
7
8
9
from foundry_sdk_runtime.types import ActionConfig, ActionMode

with AllowBetaFeatures():
    scenario_client.ontology.actions.add_review(
        action_config=ActionConfig(mode=ActionMode.VALIDATE_AND_EXECUTE),
        restaurant_id="restaurantId",
        review_rating=5,
        review_summary="It was great!",
    )

シナリオをマージする

シナリオをマージするには、シナリオの適用ルールが設定された任意のアクションタイプを適用します。このルールをアクションに追加すると、scenarioReference 型のシナリオパラメーターが自動的に公開されます。そのパラメーターの値として、シナリオクライアント（またはその scenario_rid 文字列）を渡します。

Copied!1
2
3
4
5
6
7
8
9
10
from foundry_sdk_runtime.types import ActionConfig, ActionMode

with AllowBetaFeatures():
    # `apply_scenario` は Apply Scenario ルールで設定されたアクションで、
    # `scenario` という名前のシナリオパラメーターを公開します。アクション名とパラメーター名は
    # お使いのオントロジーに固有です。
    client.ontology.actions.apply_scenario(
        action_config=ActionConfig(mode=ActionMode.VALIDATE_AND_EXECUTE),
        scenario=scenario_client,  # または scenario=scenario_client.scenario_rid
    )

アクションタイプにシナリオの適用ルールを設定する方法については、シナリオをマージするを参照してください。

シナリオ内で編集されたエンティティを一覧表示する

シナリオクライアントには、シナリオ内でどのオブジェクトとリンクが編集されたかを確認するメソッドが用意されています。結果として返される識別子には、object_api_name と primary_key フィールドのみが設定されています。プロパティ値をすべて読み込むには、シナリオクライアントに主キーを渡して再取得します。

編集されたオブジェクト

get_edited_entity_types を使用して、どのオブジェクトタイプとリンクタイプが変更されたかを確認します。次に、get_edited_objects を使用して指定したタイプの編集済みオブジェクトをページ単位で取得するか、iterate_edited_objects を使用してストリーミングで取得します。

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
from osdk.ontology.objects import ExampleRestaurant

with AllowBetaFeatures():
    # シナリオ内で編集されたオブジェクトタイプとリンクタイプを確認します。
    edited_types = scenario_client.get_edited_entity_types()
    print(edited_types.object_types)
    print(edited_types.link_types)

    # 指定したオブジェクトタイプの編集済みオブジェクトを1ページ分読み込みます。
    edited_page = scenario_client.get_edited_objects(
        ExampleRestaurant, page_size=500
    )
    for obj in edited_page.data:
        print(obj.object_api_name, obj.primary_key)

    # または、指定したオブジェクトタイプの編集済みオブジェクトをすべてストリーミングします。イテレーターは
    # 自動でページ分割し、主キーに基づいて重複を排除します。
    for obj in scenario_client.iterate_edited_objects(
        ExampleRestaurant, page_size=500
    ):
        print(obj.primary_key)

    # または、指定したオブジェクトタイプの編集済みオブジェクトをすべて非同期でストリーミングします。
    async for obj in scenario_client.async_iterate_edited_objects(
        ExampleRestaurant, page_size=500
    ):
        print(obj.primary_key)

編集されたオブジェクトのプロパティ値をすべて読み込むには、シナリオクライアントを通じて再取得します。削除されたオブジェクトは None を返す場合があります。

Copied!1
2
3
4
5
with AllowBetaFeatures():
    full = [
        scenario_client.ontology.objects.ExampleRestaurant.get(obj.primary_key)
        for obj in edited_page.data
    ]

編集されたリンク

get_edited_link_types、get_edited_links、iterate_edited_links を使用して、編集されたリンクを確認します。編集されたリンクはそれぞれ、source、target、link_type の有向の3つ組として返されます。返されるのは多対多のリンクのみです。編集された一対多のリンクは、外部キーを持つオブジェクトタイプに対する get_edited_objects を通じて確認できます。

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
from osdk.ontology.objects import ExampleRestaurant

with AllowBetaFeatures():
    # 指定したオブジェクトタイプについて、編集された多対多のリンクタイプを確認します。
    edited_link_types = scenario_client.get_edited_link_types(ExampleRestaurant)

    # 指定したリンクタイプの編集済みリンクを1ページ分読み込みます。
    links_page = scenario_client.get_edited_links(
        ExampleRestaurant, "sisterRestaurants", page_size=200
    )
    for link in links_page.data:
        print(
            link.source.primary_key,
            "->",
            link.target.primary_key,
            f"({link.link_type})",
        )

    # または、指定したリンクタイプの編集済みリンクをすべてストリーミングします。
    for link in scenario_client.iterate_edited_links(
        ExampleRestaurant, "sisterRestaurants"
    ):
        print(link.source.primary_key, "->", link.target.primary_key)

    # または、指定したリンクタイプの編集済みリンクをすべて非同期でストリーミングします。
    async for link in scenario_client.async_iterate_edited_links(
        ExampleRestaurant, "sisterRestaurants"
    ):
        print(link.source.primary_key, "->", link.target.primary_key)

←

PREVIOUSシナリオをマージする

NEXTOntology search / 概要

→