OSDK에서 시나리오 사용

시나리오 범위를 가진 Ontology SDK(OSDK) 클라이언트는 조회, 집계와 액션(Action)을 해당 시나리오의 상태에 적용합니다. 기본 온톨로지에 반영할 때에는 일반 클라이언트로 별도의 병합 액션을 호출합니다.

시나리오 API는 실험 단계이며 플랫폼 인스턴스에서 아직 제공되지 않거나 인터페이스가 바뀔 수 있습니다. TypeScript는 @osdk/client 2.27.0 이상과 그에 맞춰 Developer Console에서 생성한 SDK가 필요합니다. 사용자 정의 위젯도 OSDK로 시나리오를 사용할 수 있습니다.

Python은 OSDK 2.209.0 이상이 필요하고 편집 객체 및 링크 목록에는 2.221.0 이상이 필요합니다. Python 호출은 AllowBetaFeatures 문맥 안에서 수행합니다.

예제의 클라이언트와 생성 SDK

각 함수의 client는 인증, 온톨로지와 필요한 브랜치를 이미 설정한 일반 OSDK 클라이언트입니다. 시나리오 클라이언트를 그 자리에 전달하지 않습니다. 새 시나리오는 기준 클라이언트의 온톨로지와 브랜치를 사용합니다.

TypeScript 예제는 생성 SDK 패키지가 @my-app/sdk이며 Restaurant, addReview와 applyScenario를 제공한다고 가정합니다. Python 예제는 생성 패키지가 osdk이고 ExampleRestaurant, add_review와 apply_scenario를 제공하는 별도의 예입니다. 자신의 생성 SDK 이름, 객체 및 액션 API 이름으로 함께 바꿉니다. Restaurant 계열의 기본 키는 문자열입니다.

리뷰 평점 5와 It was great!는 가상 리뷰 예제입니다. 함수는 호출했을 때만 해당 작업을 수행하며 파일을 가져오기만 해서는 시나리오 생성이나 병합이 실행되지 않습니다.

TypeScript 공통 모듈

아래 TypeScript 코드는 같은 scenario-workflow.ts에 둡니다. 먼저 공통 가져오기를 작성합니다. 실험 API의 가져오기 경로인 unstable-do-not-use도 정확히 사용합니다.

import { Client, Osdk } from "@osdk/client";
import { createScenario, withScenario } from "@osdk/client/unstable-do-not-use";
import { Restaurant, addReview, applyScenario } from "@my-app/sdk";

type ScenarioClient = ReturnType<typeof withScenario>;

생성과 기존 시나리오 연결

createScenario는 플랫폼에 요청하므로 비동기입니다. withScenario는 RID를 가진 클라이언트를 구성하며 동기적으로 반환하고 이 단계에서 네트워크를 호출하지 않습니다.

export async function createScenarioContext(client: Client) {
    const scenario = await createScenario(client);
    return { scenario, rid: scenario.getScenarioReference() };
}

export function attachScenario(client: Client, scenarioRid: string): ScenarioClient {
    return withScenario(client, scenarioRid);
}

scenarioRid에는 실제 시나리오 참조를 전달합니다. 저장 시나리오 객체의 기본 키가 시나리오 참조이므로 해당 객체의 $primaryKey도 attachScenario의 두 번째 입력으로 사용할 수 있습니다. getScenarioReference()로 얻은 RID는 저장이나 공유에 사용할 수 있습니다.

조회, 필터와 집계

시나리오 클라이언트는 일반 클라이언트처럼 호출합니다. 다음 함수는 각각 한 페이지 조회, 리뷰 수 100 이상 필터 및 객체 수 집계입니다.

export function loadRestaurantPage(scenario: ScenarioClient) {
    return scenario(Restaurant).fetchPage();
}

export function loadReviewedRestaurants(scenario: ScenarioClient) {
    return scenario(Restaurant)
        .where({ numberOfReviews: { $gte: 100 } })
        .fetchPage();
}

export function countRestaurants(scenario: ScenarioClient) {
    return scenario(Restaurant).aggregate({ $select: { $count: "unordered" } });
}

시나리오에 액션 적용

restaurantId에는 시나리오에서 편집할 실제 객체의 기본 키를 전달합니다.

export function stageReview(scenario: ScenarioClient, restaurantId: string) {
    return scenario(addReview).applyAction({
        restaurantId,
        reviewRating: 5,
        reviewSummary: "It was great!",
    });
}

이 편집은 시나리오에만 적용합니다. 시나리오 안에서는 배치 액션을 지원하지 않으며 시나리오를 중첩하거나 별도 트랜잭션 문맥과 결합할 수 없습니다.

기본 온톨로지로 병합

applyScenario는 Apply Scenario 규칙과 scenario라는 매개변수를 가진 예제 액션입니다. 이 규칙이 추가한 매개변수의 자료형은 scenarioReference입니다. OSDK는 전달된 시나리오 클라이언트를 실제 참조로 변환합니다.

export function mergeScenario(client: Client, scenario: ScenarioClient) {
    return client(applyScenario).applyAction({ scenario });
}

이 함수는 기본 온톨로지를 바꾸는 동작입니다. 실제 액션 및 매개변수 이름과 병합 제출 조건에 맞춰 사용합니다. 시나리오 클라이언트가 아닌 일반 client로 실행합니다.

편집된 객체 찾기

getEditedEntityTypes로 변경된 객체 및 링크 유형을 확인합니다. getEditedEntities는 한 페이지를, editedEntitiesAsyncIter는 자동으로 다음 페이지를 읽는 반복자를 제공합니다. 객체 반복자는 기본 키로 중복을 제거합니다.

export function editedTypes(scenario: ScenarioClient) {
    return scenario.getEditedEntityTypes();
}

export function editedRestaurantPage(scenario: ScenarioClient) {
    return scenario.getEditedEntities(Restaurant, { pageSize: 500 });
}

export async function printEditedRestaurants(scenario: ScenarioClient): Promise<void> {
    for await (const object of scenario.editedEntitiesAsyncIter(Restaurant, { pageSize: 500 })) {
        console.log(object.$apiName, object.$primaryKey);
    }
}

편집 목록의 객체에는 $apiName과 $primaryKey만 채워집니다. 속성 값이 필요하면 페이지의 data에서 기본 키를 모아 시나리오 클라이언트로 다시 조회합니다. 다음 함수는 전달된 키의 결과를 페이지 끝까지 읽습니다.

export async function loadEditedRestaurantValues(
    scenario: ScenarioClient,
    primaryKeys: string[],
): Promise<Osdk.Instance<Restaurant>[]> {
    const values: Osdk.Instance<Restaurant>[] = [];
    if (primaryKeys.length === 0) {
        return values;
    }
    const selected = scenario(Restaurant).where({ $primaryKey: { $in: primaryKeys } });
    for await (const object of selected.asyncIter()) {
        values.push(object);
    }
    return values;
}

삭제된 객체는 현재 속성을 다시 읽을 수 없을 수 있습니다. 편집 목록은 식별값 목록이며 전체 속성이나 변경 전후 값의 기록이 아닙니다.

편집된 링크 찾기

getEditedLinkTypes는 지정한 객체 유형의 변경된 다대다 링크 유형을 찾습니다. getEditedLinks와 editedLinksAsyncIter는 source, target과 linkType이 있는 방향성 있는 항목을 반환합니다.

export function editedRestaurantLinkTypes(scenario: ScenarioClient) {
    return scenario.getEditedLinkTypes(Restaurant);
}

export function editedRestaurantLinkPage(scenario: ScenarioClient) {
    return scenario.getEditedLinks(Restaurant, "sisterRestaurants", { pageSize: 200 });
}

export async function printEditedRestaurantLinks(scenario: ScenarioClient): Promise<void> {
    for await (const { source, target, linkType } of scenario.editedLinksAsyncIter(
        Restaurant, "sisterRestaurants",
    )) {
        console.log(source.$primaryKey, target.$primaryKey, linkType);
    }
}

이 목록에는 다대다 링크만 반환됩니다. 일대다 링크의 편집은 외래 키(Foreign key)를 가진 객체 유형의 getEditedEntities 결과에서 확인합니다. pageSize 500과 200은 예제 설정값입니다.

Python 공통 모듈

아래 Python 함수는 같은 scenario_workflow.py에 둡니다. 각 함수가 필요한 베타 문맥을 엽니다.

from foundry_sdk_runtime import AllowBetaFeatures
from foundry_sdk_runtime.types import ActionConfig, ActionMode
from osdk import FoundryClient, ScenarioClient
from osdk.ontology.objects import ExampleRestaurant

생성과 기존 시나리오 연결

def create_scenario_context(client: FoundryClient):
    with AllowBetaFeatures():
        scenario_client = ScenarioClient.create(client)
        return scenario_client, scenario_client.scenario_rid


def attach_scenario(client: FoundryClient, scenario_rid: str):
    with AllowBetaFeatures():
        return ScenarioClient(client, scenario_rid=scenario_rid)

ScenarioClient.create는 플랫폼을 호출하여 시나리오를 만듭니다. 기준 client가 이미 시나리오 클라이언트이면 사용할 수 없습니다. 저장 객체에서 연결할 때에는 해당 객체의 get_primary_key() 결과를 scenario_rid로 전달합니다.

객체 조회

def load_restaurant(scenario_client: ScenarioClient, primary_key: str):
    with AllowBetaFeatures():
        return scenario_client.ontology.objects.ExampleRestaurant.get(primary_key)


def load_restaurant_page(scenario_client: ScenarioClient):
    with AllowBetaFeatures():
        return scenario_client.ontology.objects.ExampleRestaurant.page(page_size=30)

액션 적용과 병합

VALIDATE_AND_EXECUTE 모드로 액션을 검증하고 실행합니다. stage_review는 시나리오를 바꾸고 merge_scenario는 일반 client로 병합 액션을 실행하여 기본 온톨로지를 바꿉니다.

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


def merge_scenario(client: FoundryClient, scenario_client: ScenarioClient):
    with AllowBetaFeatures():
        return client.ontology.actions.apply_scenario(
            action_config=ActionConfig(mode=ActionMode.VALIDATE_AND_EXECUTE),
            scenario=scenario_client,
        )

병합의 scenario에는 시나리오 클라이언트 대신 scenario_client.scenario_rid 문자열을 전달할 수도 있습니다. 액션과 매개변수 이름은 자신의 생성 SDK를 따릅니다.

편집 객체의 페이지와 반복자

get_edited_entity_types의 object_types와 link_types로 변경 유형을 확인합니다. 편집 객체에는 object_api_name과 primary_key만 포함됩니다.

def edited_types(scenario_client: ScenarioClient):
    with AllowBetaFeatures():
        return scenario_client.get_edited_entity_types()


def edited_restaurant_page(scenario_client: ScenarioClient):
    with AllowBetaFeatures():
        return scenario_client.get_edited_objects(ExampleRestaurant, page_size=500)


def print_edited_restaurants(scenario_client: ScenarioClient):
    with AllowBetaFeatures():
        for obj in scenario_client.iterate_edited_objects(ExampleRestaurant, page_size=500):
            print(obj.object_api_name, obj.primary_key)


async def print_edited_restaurants_async(scenario_client: ScenarioClient):
    with AllowBetaFeatures():
        async for obj in scenario_client.async_iterate_edited_objects(
            ExampleRestaurant, page_size=500
        ):
            print(obj.object_api_name, obj.primary_key)

반복자는 자동 페이지 처리와 기본 키 중복 제거를 수행합니다. 전체 속성은 시나리오 클라이언트에서 다시 읽습니다. 편집 페이지의 data에 있는 primary_key를 다음 함수에 전달합니다. 삭제된 객체의 조회 결과는 None일 수 있습니다.

def load_edited_restaurant_values(scenario_client: ScenarioClient, primary_keys: list[str]):
    with AllowBetaFeatures():
        return [
            scenario_client.ontology.objects.ExampleRestaurant.get(key)
            for key in primary_keys
        ]

편집 링크의 페이지와 반복자

source, target과 link_type으로 이루어진 방향성 있는 항목을 반환합니다. 원본과 대상도 식별값으로 표현합니다.

def edited_restaurant_link_types(scenario_client: ScenarioClient):
    with AllowBetaFeatures():
        return scenario_client.get_edited_link_types(ExampleRestaurant)


def edited_restaurant_link_page(scenario_client: ScenarioClient):
    with AllowBetaFeatures():
        return scenario_client.get_edited_links(
            ExampleRestaurant, "sisterRestaurants", page_size=200
        )


def print_edited_restaurant_links(scenario_client: ScenarioClient):
    with AllowBetaFeatures():
        for link in scenario_client.iterate_edited_links(ExampleRestaurant, "sisterRestaurants"):
            print(link.source.primary_key, link.target.primary_key, link.link_type)


async def print_edited_restaurant_links_async(scenario_client: ScenarioClient):
    with AllowBetaFeatures():
        async for link in scenario_client.async_iterate_edited_links(
            ExampleRestaurant, "sisterRestaurants"
        ):
            print(link.source.primary_key, link.target.primary_key, link.link_type)

Python도 링크 목록에서는 다대다 링크만 제공합니다. 일대다 링크는 외래 키를 보유한 객체 유형의 get_edited_objects로 확인합니다. 시나리오와 일반 클라이언트를 혼용하지 않도록 조회와 편집의 적용 범위를 호출 지점에서 구분합니다.