Python OSDK 1.x에서 2.x로 이전

Python OSDK 2.x는 플랫폼 SDK와 클라이언트를 공유하고 객체, 링크와 쿼리 반환값의 타입을 구체화합니다. Developer Console의 /workspace/developer-console/에서 버전 선택기를 2.x로 바꾸면 해당 생성기 문서를 볼 수 있습니다.

생성과 설치

앱의 SDK versions에서 Generate new version을 선택하고 Python OSDK 2.x 생성기로 새 버전을 만듭니다. 생성 패키지와 필요한 의존성을 소비 앱에 설치합니다. 새 앱은 2.x가 기본이며 Start developing 안내를 따릅니다.

공유 클라이언트

2.x에서는 OSDK와 Platform SDK를 같은 클라이언트에서 사용할 수 있습니다. 별도의 인증 클라이언트를 각각 관리할 필요가 없습니다. 환경에 따른 생성 방식은 Python 참조를 따릅니다.

공개 Config로 설정

1.x에서 내부 _session을 수정하던 설정은 2.x의 Config로 전달합니다.

from ontology_sdk import Config, FoundryClient

client = FoundryClient(config=Config(default_headers={"Content-Type": "application/json"}))

이 예제는 Foundry 안에서 런타임 인증을 사용합니다. 독립 앱은 기존 auth와 hostname도 함께 제공합니다. 사용자 지정 인증서가 필요하면 CA 번들 경로를 설정하며 TLS 검증을 끄는 것을 기본 해결 방법으로 사용하지 않습니다.

Beta 기능

2.x의 안정 릴리스에도 Beta 기능을 포함할 수 있습니다. 파생 속성, 최근접 이웃 필터, 보안 표지와 벡터 속성 및 구조체 속성 지원은 해당 Beta 조건을 따라야 합니다.

일반 Python 코드는 AllowBetaFeatures 문맥 또는 데코레이터를 사용하고 Foundry Python 함수는 @function(beta=True)를 사용할 수 있습니다. 다음은 가상 Object.vector_property를 읽는 예제입니다.

from foundry_sdk_runtime import AllowBetaFeatures
from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import Object


@AllowBetaFeatures()
def read_vector(client: FoundryClient, object_id: int):
    obj = client.ontology.objects.Object.get(object_id, properties=[Object.object_type.vector_property])
    if obj is None:
        raise ValueError("대상 객체가 없습니다.")
    return obj.vector_property

같은 읽기 블록을 with AllowBetaFeatures(): 안에 둘 수도 있습니다. 구조체 속성을 편집할 때는 생성된 구조체 클래스를 사용합니다.

파생 속성과 최근접 이웃

with_properties는 객체 집합에 계산 속성을 추가합니다. object_type.derived의 링크와 속성 표현식을 사용하며 연결 속성 그룹화 예제에서 전체 호출을 설명합니다. 파생 속성은 기존 값과 관계에서 실행 시 계산하며 원래 객체의 저장 속성을 새로 쓰는 동작은 아닙니다.

nearest_neighbors는 벡터 또는 검색 텍스트, 이웃 수와 벡터 속성을 받아 가까운 객체 집합을 만듭니다.

from foundry_sdk_runtime import AllowBetaFeatures
from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import Object


def closest_objects(client: FoundryClient, query: str):
    with AllowBetaFeatures():
        return list(client.ontology.objects.Object.nearest_neighbors(
            query=query,
            num_neighbors=3,
            vector_property=Object.object_type.vector_property,
        ))

검색 모델과 벡터 차원은 해당 속성의 계약을 따라야 합니다. Media 속성은 일반 읽기 경로로 사용할 수 있으며 Marking과 Vector는 Beta 문맥에서 읽습니다.

필터 문법

from ontology_sdk.ontology.objects import Object

selected = client.ontology.objects.Object.where(Object.object_type.id.in_([1, 2, 3])).take(1)

예제 Object.id는 Integer 기본 키입니다. client는 앞서 환경에 맞춰 생성한 클라이언트입니다.

링크 반환

1.x는 링크 wrapper에서 get 또는 iterate를 호출했습니다. 2.x는 로드한 객체의 snake_case 링크 메서드를 호출합니다.

가상의 Object.linked_objects 다중 링크와 LinkedObject.id를 사용한 예입니다.

from ontology_sdk.ontology.objects import LinkedObject

obj = client.ontology.objects.Object.get("primary-key-example")
if obj is None:
    raise ValueError("출발 객체가 없습니다.")
linked_objects = obj.linked_objects()
count = linked_objects.where(LinkedObject.object_type.id > 5).count().compute()

이 예제의 Object는 String 기본 키를 가진 별도 가상 유형입니다. 자신의 실제 기본 키 타입에 맞춥니다. 다중 링크 결과에 page, take, where와 group_by 등 객체 집합 메서드를 사용할 수 있습니다. 집합 자체에서는 search_around_<link_name>()으로 탐색합니다.

쿼리 반환형과 인수

2.x의 생성 쿼리는 모든 입력을 키워드 인수로 받습니다. query_object_output(object_id=1)처럼 이름을 명시합니다.

2차원 집계는 groups, 3차원 집계는 바깥과 안쪽에 groups를 사용합니다. Python 쿼리 반환에서 상세 형태를 확인합니다.

집계 결과

복수 지표나 그룹 집계는 1.x의 dict[str, Any]에서 AggregateObjectsResponse로 바뀝니다. accuracy, excluded_items 및 data의 그룹과 지표를 속성으로 읽을 수 있으며 to_dict()는 기존 사전 모양을 제공합니다.

from ontology_sdk.ontology.objects import Object

result = client.ontology.objects.Object.aggregate({
    "min_id": Object.object_type.id.min(),
    "max_id": Object.object_type.id.max(),
}).compute()
result_as_dict = result.to_dict()

단일 count나 sum의 스칼라 반환까지 AggregateObjectsResponse로 바뀌었다고 해석하지 않습니다. 집계 정확도와 제외 항목은 실제 응답을 확인합니다.

범위 그룹과 지리공간 이름

1.x의 범위는 start_value와 end_value를 가진 사전 목록으로 전달했습니다. 2.x는 시작과 끝의 튜플 집합을 사용합니다.

from ontology_sdk.ontology.objects import Object

ranges = client.ontology.objects.Object.group_by(
    Object.object_type.int_property.ranges({(1, 2), (3, 4)})
)

GeoTypes의 Point는 GeoPoint로 이름이 바뀝니다.

첨부 업로드 반환

upload는 1.x의 AttachmentMetadata 대신 2.x의 Attachment를 반환합니다. 메타데이터는 get_metadata(), 내용은 read()에서 얻습니다.

from ontology_sdk import FoundryClient


def upload_and_read_metadata(client: FoundryClient, file_path: str, attachment_name: str):
    attachment = client.ontology.attachments.upload(file_path=file_path, attachment_name=attachment_name)
    return attachment, attachment.get_metadata()

객체에 액션으로 연결하지 않은 업로드는 1시간 후 삭제됩니다. 연결 전에는 업로더만 읽을 수 있습니다.

요청 예외

PalantirRPCException, NotAuthenticated와 EnvironmentNotConfigured는 foundry_sdk_runtime.errors 대신 foundry_sdk에서 가져옵니다.

from foundry_sdk import PalantirRPCException, NotAuthenticated, EnvironmentNotConfigured

이 변경은 해당 요청 예외의 import에 관한 것입니다. 미디어 변환 등 다른 라이브러리 전용 예외까지 모두 같은 경로로 바꾼다는 뜻은 아닙니다.

액션 반환과 설정

response.validation.validation_result나 ValidationResult.VALID 대신 response.validation.result == "VALID"를 검사합니다.

from foundry_sdk_runtime.types import ActionConfig, ActionMode, ReturnEditsMode
from ontology_sdk import FoundryClient


def apply_example(client: FoundryClient, value: str):
    response = client.ontology.actions.action_example(
        action_config=ActionConfig(mode=ActionMode.VALIDATE_AND_EXECUTE, return_edits=ReturnEditsMode.ALL),
        parameter_example=value,
    )
    if response.validation.result != "VALID":
        raise ValueError("액션 제출 조건을 충족하지 못했습니다.")
    return response.edits

배치는 생성된 ActionExampleBatchRequest 객체 목록을 requests로 전달하고 BatchActionConfig(return_edits=ReturnEditsMode.ALL)를 사용합니다. 결과는 BatchApplyActionResponse이며 같은 배치의 온톨로지 변경은 전부 적용하거나 전부 적용하지 않습니다. 액션과 배치 참조의 전체 구현을 따릅니다.