Code Workspaces에서 온톨로지 사용

JupyterLab과 RStudio에서 생성 OSDK로 객체, 링크와 액션을 사용할 수 있습니다. 제한 뷰를 기반으로 하는 온톨로지 엔터티와 Query function은 Code Workspaces에서 아직 지원하지 않습니다. 객체 검색과 집계는 Query function 호출과 구분합니다.

작업공간의 SDK 만들기

Ontology 사이드 패널에서 Create new SDK를 선택합니다. 작업공간마다 SDK 하나를 둘 수 있고 그 SDK의 여러 버전을 생성할 수 있습니다.

패키지 이름과 연결할 온톨로지를 지정합니다. 패키지 이름은 문자, 숫자와 하이픈만 포함하며 하이픈으로 끝날 수 없습니다. 게시한 뒤 이름을 변경할 수 없습니다. 예를 들어 패키지 이름 example은 코드에서 example_sdk로 가져옵니다. 실제 import 이름은 생성한 스니펫을 사용합니다.

Save selection으로 설정을 저장합니다.

데이터 엔터티 선택

Ontology 패널의 Data entities는 SDK에 포함할 객체 및 액션을 정하고, SDK generation은 버전 상태와 설치 코드를 제공합니다.

Data entities > Add에서 유형을 고르고 자원을 선택한 뒤 아래 Save를 누릅니다. 선택한 엔터티를 포함하는 새 SDK 버전을 생성합니다.

액션이 특정 객체 유형을 편집하거나 그 유형의 객체를 매개변수로 받으면 관련 객체 유형도 자동으로 추가합니다. 선택 객체의 기반 데이터 소스가 작업공간 프로젝트 범위에 없으면 소스 가져오기를 확인하라는 안내가 나타납니다.

온톨로지 변경

Data entities의 온톨로지 선택기에서 다른 온톨로지를 고른 뒤 Save합니다. SDK 데이터 범위를 초기화하므로 기존 객체, 액션과 링크 유형 선택이 지워지고 새 버전을 생성합니다.

SDK 버전 생성과 설치

패널 아래 Generate new version으로 새 버전을 생성합니다. SDK generation에서 대기 중인 버전과 게시한 버전을 확인할 수 있습니다.

상태가 Published가 되기 전에는 사용할 수 없습니다. 액션에 필요한 객체 유형이 선택되지 않았거나, 객체의 기반 데이터 소스가 프로젝트 범위에 없으면 게시가 실패할 수 있습니다.

Published 버전의 카드를 펼치면 IDE 언어에 맞는 Install package와 Initialize client 스니펫이 나옵니다. 선택해 복사하고 실제 버전에 맞춰 설치 및 초기화합니다.

Jupyter 관리형 환경에서는 선택한 버전의 Conda 패키지 사양을 OSDK_PACKAGE_SPEC으로 준비하고 작업공간 터미널에서 설치할 수 있습니다.

: "${OSDK_PACKAGE_SPEC:?Use the package specification from the selected SDK version}"
maestro env conda install "$OSDK_PACKAGE_SPEC"

Python 클라이언트

아래 예제는 Python OSDK 2.x API를 사용합니다. my_sdk_package는 가상 생성 패키지이며 실제 이름으로 바꿉니다. Code Workspaces 런타임이 호스트와 인증을 제공하므로 별도 토큰을 넣지 않고 초기화합니다.

from my_sdk_package import FoundryClient

client = FoundryClient()

생성 패키지의 버전과 Python OSDK API 세대는 구분합니다. 기존 1.x 코드는 Python OSDK 이전, 일반 API는 Python OSDK 참조를 사용합니다. 작업공간의 Query function 및 제한 뷰 기반 엔터티 제한은 그대로 적용됩니다.

객체 조회, 집계와 필터

가상 Aircraft 스키마의 id는 Integer 기본 키이며 type은 문자열, date_of_manufacture는 Date, current_location은 위치 속성이라고 가정합니다. 이 객체 유형이 설치한 SDK에 포함되어 있어야 합니다.

from my_sdk_package.ontology.objects import Aircraft

aircraft_objects = client.ontology.objects.Aircraft
my_aircraft = aircraft_objects.get(1)
if my_aircraft is None:
    raise LookupError("Aircraft 1 is not accessible")
manufacture_date = my_aircraft.date_of_manufacture

locations = [aircraft.current_location for aircraft in aircraft_objects.take(2)]

id_range = aircraft_objects.aggregate({
    "min_id": Aircraft.object_type.id.min(),
    "max_id": Aircraft.object_type.id.max(),
}).compute()
aircraft_count = aircraft_objects.count().compute()

my_a330s = aircraft_objects.where(
    (Aircraft.object_type.type == "A330") | (Aircraft.object_type.id == 160)
).take(1)

get은 기본 키로 조회하고 take는 지정한 수만큼 가져옵니다. 범위 집계와 개수 조회는 위 예제에서 각각 요청합니다. 필터 속성은 object_type에서 참조합니다.

액션의 검증과 적용

가상 액션의 Python 호출 이름은 change_manufacture_date이며 Aircraft 객체 참조와 Date 입력을 받습니다. 이 예제의 REST 매개변수 ID는 aircraft와 date_of_manufacture로 정합니다. 실제 액션에서는 정의에 지정된 매개변수 ID와 생성 Python 이름의 대응을 확인합니다. ActionMode는 SDK 실행 모드 설정이며 온톨로지 액션 유형 이름이 아닙니다.

검증만 할 때는 공개 Apply Action REST API의 options.mode를 "VALIDATE_ONLY"로 지정합니다. 이 요청은 입력과 제출 조건을 검증하며 온톨로지 편집을 적용하지 않습니다. mode를 생략하면 기본이 "VALIDATE_AND_EXECUTE"이므로 검증 전용 요청에는 값을 명시해야 합니다.

아래는 REST 요청 계약입니다. ontology에는 같은 온톨로지의 API 이름 또는 RID를, action에는 해당 액션의 실제 API 이름을 사용합니다. REST 경로의 액션 API 이름과 생성 Python 메서드 이름은 구분합니다.

POST /api/v2/ontologies/{ontology}/actions/{action}/apply
Content-Type: application/json

{
  "parameters": {
    "aircraft": 1,
    "date_of_manufacture": "2023-05-26"
  },
  "options": {
    "mode": "VALIDATE_ONLY"
  }
}

REST 검증은 이 API를 사용할 권한이 있는 클라이언트에서 수행합니다. 온톨로지 읽기/쓰기 작업 범위와 자원 권한이 필요하며, 신규 고급 API 보안 앱과 기존 앱의 범위 설정은 Developer Console 권한 모델을 따릅니다. 이것은 작업공간 세션 자격 증명을 임의의 REST 호출에 재사용하는 절차가 아닙니다.

HTTP 200만으로 검증 통과를 판단하지 않습니다. 응답의 validation.result가 "VALID"인지 확인하고 validation.submissionCriteria와 validation.parameters에서 조건별 결과를 봅니다. "INVALID"이면 적용하지 않고 입력 또는 권한 및 제출 조건을 해결합니다. 검증 전용 응답이 VALID여도 편집이 적용된 상태는 아닙니다.

다음 별도 Python 셀은 실제 적용 요청입니다. REST에서 검증한 것과 같은 온톨로지 및 대상 범위를 사용하고, 기본 키 1인 my_aircraft와 같은 날짜를 전달합니다. Python OSDK 2.x에서는 객체 참조를 객체 인스턴스로, Date를 datetime.date로 전달합니다.

import datetime
from foundry_sdk_runtime.types import ActionConfig, ActionMode, ReturnEditsMode

action_parameters = {
    "aircraft": my_aircraft,
    "date_of_manufacture": datetime.date(2023, 5, 26),
}
apply_response = client.ontology.actions.change_manufacture_date(
    action_config=ActionConfig(
        mode=ActionMode.VALIDATE_AND_EXECUTE,
        return_edits=ReturnEditsMode.ALL,
    ),
    **action_parameters,
)
if apply_response.validation.result != "VALID":
    raise ValueError("The action inputs did not satisfy execution-time validation")
applied_edits = apply_response.edits

사전 검증 뒤 상태가 달라질 수 있으므로 실제 적용도 다시 검증하며 이전의 유효 판정만으로 이후 편집 성공을 보장하지 않습니다.

시계열 속성

시계열 속성을 포함하는 SDK를 생성하여 설치한 뒤 foundryTS의 TimeSeries.from_osdk로 변환합니다. 다음 가상 City 스키마는 문자열 기본 키 Denver와 시계열 속성 electricity_price를 사용합니다.

from my_sdk_package import FoundryClient
from foundryts import TimeSeries

client = FoundryClient()
denver = client.ontology.objects.City.get("Denver")
if denver is None:
    raise LookupError("City Denver is not accessible")
series = TimeSeries.from_osdk(denver.electricity_price)
node = series.node()
df = series.to_pandas()

node는 foundryTS 연산에, pandas 결과는 작업공간의 데이터 분석에 사용할 수 있습니다. 가져올 데이터가 작업공간의 메모리 범위에 들어오는지 확인합니다.

R에서 Python OSDK 호출

RStudio에서는 reticulate로 설치한 Python SDK를 사용합니다.

library(reticulate)

osdk <- import("my_sdk_package")
client <- osdk$FoundryClient()
aircraft_objects <- client$ontology$objects$Aircraft
first_aircraft <- aircraft_objects$take(1L)
aircraft <- aircraft_objects$get(1L)
if (is.null(aircraft)) {
  stop("Aircraft 1 is not accessible")
}

R의 기본 숫자는 부동소수점이므로 Python API가 정수를 요구할 때는 1L처럼 L을 붙입니다. 위 스키마의 기본 키도 Integer이므로 get(1L)을 사용합니다. 기본 키가 String인 다른 유형에서는 문자열을 전달합니다.