객체 조회 API: Get Object

기능과 요청 경로

Get Object는 특정 온톨로지에서 객체 유형과 기본 키(primary key)로 지정한 객체 한 건을 조회합니다. 호출하는 작업은 조회이며, 객체의 값을 변경하려면 별도의 액션이나 쓰기 기능을 사용해야 합니다.

GET /api/v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}

전체 요청 주소는 이 경로 앞에 Foundry 호스트를 붙인 형태입니다.

https://<Foundry 호스트>/api/v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}

요청 본문은 사용하지 않습니다. 조회 대상은 경로 매개변수(path parameter)로 지정하고, 반환할 속성이나 조회 맥락은 쿼리 매개변수(query parameter)로 조정합니다.

객체를 여러 건 검색하거나 조건에 따라 목록을 가져오는 작업과는 용도가 다릅니다. 이 엔드포인트에는 pageSize나 pageToken을 전달하지 않습니다.

호출 전에 준비할 정보

객체 조회에는 다음 세 가지 식별 정보가 필요합니다.

1. 어느 온톨로지를 조회할지 지정하는 API 이름 또는 리소스 식별자(RID).
2. 그 온톨로지 안에서 조회할 객체 유형(Object type)의 API 이름.
3. 해당 객체 유형 안에서 특정 객체를 식별하는 기본 키 값.

온톨로지 식별자는 Ontology Manager나 List Ontologies로 확인할 수 있습니다. 객체 유형의 API 이름은 Ontology Manager나 List object types로 확인합니다. 기본 키로 어느 속성을 사용하는지는 Get object type 또는 Ontology Manager에서 확인합니다.

화면의 표시 이름(display name)을 API 이름(API name) 대신 사용하지 않도록 주의해야 합니다. 예를 들어 표시 이름이 직원인 유형의 API 이름을 Employee로 정의했다면 요청 경로에는 Employee를 사용합니다. 기본 키가 직원 번호라면 특정 직원의 직원 번호가 마지막 경로 값이 됩니다.

객체 유형의 정의를 조회할 수 있는 권한과 그 유형의 실제 객체 데이터를 볼 수 있는 권한은 다릅니다. 객체를 읽으려면 객체 유형에 대한 접근과 해당 데이터에 적용되는 보안 조건을 충족해야 합니다. 속성 선택 옵션으로 요청 범위를 줄이더라도 접근 권한이 추가되지는 않습니다.

인증과 OAuth 권한 범위

API 호출에는 Bearer 토큰을 다음 헤더로 전달합니다.

Authorization: Bearer <접근 토큰>

OAuth 2.0으로 이 엔드포인트를 사용하는 외부 애플리케이션은 api:ontologies-read 권한 범위(scope)를 요청해야 합니다. 실제 허용 범위는 애플리케이션이 요청한 범위와 실행 사용자 또는 서비스 사용자가 이미 가진 권한의 교집합입니다.

개발 중에는 계정 설정의 Tokens에서 생성한 사용자 토큰을 사용할 수 있습니다. 이 토큰은 생성한 사용자의 권한을 가지므로 공개 저장소에 넣거나 운영 애플리케이션에 고정하여 사용하지 않습니다. 필요하지 않은 토큰은 폐기합니다.

운영 애플리케이션에서는 실행 주체에 맞는 OAuth 흐름을 구성합니다.

• 인가 코드 방식(Authorization code grant)은 사용자를 대신하여 동작하는 애플리케이션에 사용합니다.
• 클라이언트 인증 정보 방식(Client credentials grant)은 서비스 사용자로 동작하는 애플리케이션에 사용합니다. 클라이언트 비밀값을 안전하게 보관해야 합니다.

뒤의 코드 예제는 인증 구성이 끝나 유효한 토큰을 사용할 수 있다는 전제에서 조회 요청을 만드는 부분을 보여 줍니다.

경로 매개변수

세 항목은 모두 필수이며, HTTP 경로에서는 문자열로 전달합니다.

예제는 palantir 온톨로지에 API 이름이 Employee인 객체 유형이 있고, 기본 키 50030에 해당하는 객체가 있다고 가정합니다. 실제 환경의 이름과 키를 그대로 사용해야 합니다. 이름의 대소문자를 임의로 바꾸거나 표시 이름에서 API 이름을 추정하지 않습니다.

기본 키의 자료형이 정수여도 URL에는 문자열로 표현됩니다. 응답의 기본 키 값은 JSON 숫자일 수 있으므로, 경로의 문자열 표현과 응답 데이터의 자료형을 같은 것으로 취급하지 않습니다. 이름이나 키에 특수 문자가 있으면 각 경로 값을 URL에 적합하게 인코딩해야 합니다.

쿼리 매개변수

다음 항목은 모두 선택 사항입니다.

반환할 속성 선택

select에는 속성의 표시 이름이 아니라 API 이름을 사용합니다. 속성 API 이름은 Get object type이나 Ontology Manager에서 확인할 수 있습니다. 생성된 Python Platform SDK의 OntologyObject.get을 사용할 때에는 select 인자로 문자열 목록을 전달합니다.

속성을 명시적으로 선택하지 않으면 기본적으로 속성들이 반환되지만 Vector 형식의 속성은 기본 반환 대상에서 제외됩니다. 벡터 값이 필요하다면 해당 속성을 선택 대상에 포함해야 합니다.

객체의 기본 키는 속성 선택 목록에 넣지 않아도 반환됩니다. 존재하지 않는 속성 이름을 선택하면 PropertiesNotFound 오류가 발생할 수 있습니다. 화면에 보이는 속성 제목과 API 이름이 다를 수 있으므로, 선택 목록을 구성할 때에는 스키마의 API 이름을 기준으로 합니다.

이 엔드포인트의 속성 선택 매개변수는 select입니다.

파생 속성 로딩과 명시적 선택의 관계

loadOntologyDefinedDerivedProperties는 온톨로지에 정의된 파생 속성(Ontology-defined derived properties, OTDPs)을 응답에 불러올지 정합니다. 이 옵션은 정식 제공 단계에 도달하지 않은 실험적 기능입니다.

select에 파생 속성을 넣어 놓고 loadOntologyDefinedDerivedProperties=false로 그 속성의 반환을 취소하는 방식은 사용할 수 없습니다. 어떤 속성을 반환할지 명시적으로 정한 요청에서는 선택 목록이 기준입니다.

조회 맥락 지정

branch, transactionId, scenarioRid는 어느 맥락의 객체 상태를 읽을지 지정합니다. 객체의 기본 키는 바꾸지 않습니다.

• branch는 특정 브랜치를 대상으로 합니다. 기본 브랜치의 이름을 항상 main이라고 가정하지 않습니다.
• transactionId는 온톨로지 트랜잭션을 가리킵니다. 데이터셋의 파일 트랜잭션 식별자를 대신 넣는 입력이 아닙니다.
• scenarioRid는 온톨로지 시나리오에서 객체를 읽도록 지정합니다.

다음은 브랜치와 시나리오를 함께 지정한 주소의 형태입니다. 식별자는 설명용 예시이며, 요청에 사용할 브랜치와 시나리오가 실제 환경에 존재하고 해당 작업을 지원해야 합니다.

https://<Foundry 호스트>/api/v2/ontologies/palantir/objects/Employee/50030?branch=ri.branch..branch.d827184f-ee0e-4351-8b70-efbe51e07252&scenarioRid=ri.actions..scenario.a1b2c3d4-e5f6-7890-abcd-ef1234567890

실험적 기능의 지원 여부와 필요한 조합은 사용하는 환경 및 워크플로에 따라 확인해야 합니다. 특정 브랜치나 시나리오를 지정할 필요가 없다면 이 매개변수들을 생략하고 기본 조회부터 구성합니다.

성공 응답의 구조

성공 응답의 형식은 OntologyObjectV2이며, 속성 API 이름을 키로 하고 속성값을 값으로 하는 맵입니다.

map<PropertyApiName, PropertyValue>

PropertyApiName은 속성의 API 이름을 나타내는 문자열입니다. PropertyValue의 JSON 표현은 각 속성의 자료형에 따라 달라집니다.

다음은 직원 객체의 성공 응답 예시입니다.

{
  "__rid": "ri.phonograph2-objects.main.object.88a6fccb-f333-46d6-a07e-7725c5f18b61",
  "__primaryKey": 50030,
  "__apiName": "Employee",
  "id": 50030,
  "firstName": "John",
  "lastName": "Doe"
}

이 응답에서 업무 속성인 id, firstName, lastName은 JSON 객체의 최상위에 있으며, 별도의 properties 객체로 감싸지 않습니다.

예시에 함께 나타난 메타데이터는 다음과 같이 읽습니다.

객체의 RID와 기본 키는 서로 다른 식별 정보입니다. 요청 경로의 {primaryKey} 자리에는 기본 키를 넣습니다. __rid를 제외하는 옵션도 객체의 기본 키를 없애는 옵션으로 해석하지 않습니다.

속성 자료형별 JSON 표현

속성값은 모두 같은 JSON 형식으로 반환되지 않습니다. 특히 숫자처럼 보이는 값도 자료형에 따라 문자열로 전달될 수 있습니다.

하위 호환성을 위해 Boolean, Byte, Double, Float, Integer, Short도 JSON 문자열로 인코딩될 수 있습니다. 수신한 값은 온톨로지 스키마의 자료형과 함께 해석해야 합니다.

Long이나 Decimal을 일반 부동소수점 숫자로 무조건 변환하면 값에 따라 정밀도가 손실될 수 있습니다. 문자열로 전달되는 표현을 보존하거나 해당 자료형에 맞는 처리 방식을 사용합니다. Date의 날짜와 Timestamp의 UTC 시각도 구분합니다.

미디어 참조

미디어 참조는 미디어의 MIME 유형과 해당 미디어 항목을 찾을 수 있는 참조 구조를 포함합니다.

{
  "mimeType": "application/pdf",
  "reference": {
    "type": "mediaSetViewItem",
    "mediaSetViewItem": {
      "mediaSetRid": "ri.mio.main.media-set.4153d42f-ca4b-4e42-8ca5-8e6aa7edb642",
      "mediaSetViewRid": "ri.mio.main.view.82a798ad-d637-4595-acc6-987bcf16629b",
      "mediaItemRid": "ri.mio.main.media-item.001ec98b-1620-4814-9e17-8e9c4e536225"
    }
  }
}

이 객체는 PDF 파일의 본문이 아닙니다. 어느 미디어 집합과 뷰의 어떤 항목을 참조하는지 나타냅니다. 첨부 파일의 rid도 같은 이유로 파일 바이트와 구분해야 합니다.

시계열 표현

시계열 속성은 다음과 같은 형태로 표현될 수 있습니다.

{
  "seriesId": "wellPressureSeriesId",
  "syncRid": "ri.time-series-catalog.main.sync.04f5ac1f-91bf-44f9-a51f-4f34e06e42df"
}

템플릿을 가리키는 형태도 있습니다.

{
  "templateRid": "ri.codex-emu.main.template.367cac64-e53b-4653-b111-f61856a63df9",
  "templateVersion": "0.0.0"
}

또는 다음처럼 시계열 ID 문자열로 표현될 수 있습니다.

"wellPressureSeriesId"

객체 조회에서 받은 시계열 속성값이 실제 관측 데이터인지, 그 데이터를 찾기 위한 참조인지를 확인한 뒤 해당 형식에 맞게 처리합니다.

요청 예제

다음 예제는 기본 조회를 수행합니다. branch, transactionId, scenarioRid는 생략합니다. 속성 선택과 같은 추가 옵션이 필요하면 쿼리 매개변수를 별도로 구성합니다.

실행 환경에는 두 값을 준비합니다.

• FOUNDRY_HOST: https://를 제외한 Foundry 호스트 이름.
• FOUNDRY_TOKEN: 조회 권한이 있는 유효한 토큰.

예제의 palantir, Employee, 50030은 앞에서 정한 가상의 식별 정보입니다. 실제 호출 대상의 값으로 바꿔 사용합니다. 토큰을 코드나 공유 문서에 직접 입력하지 않습니다.

cURL

curl \
  -H "Authorization: Bearer ${FOUNDRY_TOKEN}" \
  "https://${FOUNDRY_HOST}/api/v2/ontologies/palantir/objects/Employee/50030"

응답 본문이 표준 출력으로 전달됩니다. Bearer 토큰은 헤더에 들어가고, 조회할 객체의 식별 정보는 경로에 들어갑니다.

Python

Python 표준 라이브러리로 요청을 만들고 JSON 응답을 읽습니다.

import json
import os
from urllib.request import Request, urlopen

host = os.environ["FOUNDRY_HOST"]
token = os.environ["FOUNDRY_TOKEN"]
url = f"https://{host}/api/v2/ontologies/palantir/objects/Employee/50030"

request = Request(
    url,
    headers={"Authorization": f"Bearer {token}"},
    method="GET",
)

with urlopen(request, timeout=30) as response:
    employee = json.load(response)

print(employee)

employee는 응답의 JSON 객체를 변환한 딕셔너리입니다. HTTP 오류는 예외로 전달됩니다. 운영 코드에서는 오류 응답과 네트워크 오류를 목적에 맞게 처리해야 합니다.

Java

JDK 11 이상의 HTTP 클라이언트를 사용하는 예제입니다. 파일 이름을 GetEmployee.java로 사용할 수 있습니다.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class GetEmployee {
    public static void main(String[] args) throws Exception {
        String host = System.getenv("FOUNDRY_HOST");
        String token = System.getenv("FOUNDRY_TOKEN");
        String url = "https://" + host
            + "/api/v2/ontologies/palantir/objects/Employee/50030";

        HttpRequest request = HttpRequest.newBuilder(URI.create(url))
            .header("Authorization", "Bearer " + token)
            .timeout(Duration.ofSeconds(30))
            .GET()
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient().send(
            request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

이 예제는 HTTP 상태 코드와 문자열로 받은 본문을 출력합니다. 애플리케이션에서 속성을 사용할 때에는 JSON 파서를 통해 본문을 해석합니다.

JavaScript

Node.js 18 이상의 ES 모듈에서 사용할 수 있는 예제입니다. 예를 들어 .mjs 파일에서 실행할 수 있습니다.

const host = process.env.FOUNDRY_HOST;
const token = process.env.FOUNDRY_TOKEN;
const url = `https://${host}/api/v2/ontologies/palantir/objects/Employee/50030`;

const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}

const employee = await response.json();
console.log(employee);

fetch로 받은 응답의 상태를 확인하고, 요청이 성공한 경우 본문을 해석합니다.

PowerShell

$headers = @{
    Authorization = "Bearer $env:FOUNDRY_TOKEN"
}

$uri = "https://$env:FOUNDRY_HOST/api/v2/ontologies/palantir/objects/Employee/50030"
$response = Invoke-WebRequest -Uri $uri -Method Get -Headers $headers
$response.Content

Content는 응답 본문입니다. 속성별 값을 사용하려면 이 내용을 JSON으로 해석합니다.

오류 응답을 읽는 방법

Foundry API의 오류 응답은 오류 코드, 오류 이름, 개별 발생 건의 ID와 추가 매개변수를 포함하는 JSON 형식입니다. 오류 응답은 4xx 또는 5xx HTTP 상태 코드와 함께 반환됩니다.

다음은 요청한 직원 객체를 찾을 수 없는 경우의 오류 형식을 설명하는 예시입니다.

{
  "errorCode": "NOT_FOUND",
  "errorName": "ObjectNotFound",
  "errorInstanceId": "00813215-0844-4716-be7b-a3fe0fce9e42",
  "parameters": {
    "objectType": "Employee",
    "primaryKey": {
      "id": 50030
    }
  }
}

객체 조회와 관련하여 확인할 수 있는 오류에는 ObjectNotFound, ObjectTypeNotFound, OntologyNotFound, PropertiesNotFound 등이 있습니다. 그 밖의 네트워크 오류나 플랫폼 오류도 발생할 수 있습니다.

ObjectNotFound, ObjectTypeNotFound, OntologyNotFound는 대상이 존재하지 않을 때뿐 아니라 토큰으로 대상에 접근할 수 없을 때에도 나타날 수 있습니다. 온톨로지 식별자, 객체 유형의 API 이름, 기본 키, 실행 사용자의 접근 조건을 함께 확인합니다.

선택한 속성의 이름이 문제라면 객체 유형의 속성 API 이름을 확인합니다. 접근 권한 문제라면 해당 리소스에 필요한 접근 조건과 애플리케이션의 허용 범위를 확인해야 합니다.