객체 유형의 객체 목록(List Objects) (V2)

온톨로지와 객체 유형을 지정하여 객체를 페이지 단위로 읽습니다. 기본 페이지 크기는 1,000이며 페이지가 요청한 크기보다 작거나 클 수 있습니다. 결과가 더 남아 있으면 적어도 한 항목을 반환합니다.

기본 snapshot=false에서는 조회 중 데이터가 바뀌면 객체가 중복되거나 누락될 수 있습니다. 일관된 상태로 페이지를 읽으려면 snapshot=true를 지정합니다. null 값 속성은 반환하지 않습니다. 기본 반환 대상에서는 벡터를 제외하며, select로 속성을 고르더라도 기본 키는 반환합니다.

OSv1 기반 객체는 누적 10,000개까지 반환합니다. 그 이후에 결과가 더 있는 상태로 다음 페이지를 요청하면 ObjectsExceededLimit 오류가 발생합니다. OSv2에는 이 누적 10,000개 제한을 적용하지 않습니다.

HTTP 요청

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

작업 식별자는 v2.listObjectsV2입니다. OAuth2로 호출하는 타사 애플리케이션에는 api:ontologies-read 권한 범위가 필요합니다. 각 요청에 Authorization: Bearer <접근 토큰>을 전달합니다.

경로 매개변수

이름	자료형	필수 여부	의미와 조건	예시 값
`ontology`	`string`	필수	온톨로지의 API 이름 또는 RID입니다. List Ontologies 또는 Ontology Manager에서 확인합니다.	`palantir`
`objectType`	`string`	필수	객체 유형의 API 이름입니다. List Object Types 또는 Ontology Manager에서 확인합니다.	`employee`

쿼리 매개변수

쿼리 매개변수는 모두 선택 사항입니다.

이름	자료형	의미와 조건
`pageSize`	`integer`	요청할 페이지 크기입니다. 기본값은 1,000입니다.
`pageToken`	`string`	페이지 조회를 시작할 위치입니다. 첫 요청에서는 생략하고, 다음 요청에서는 직전 응답의 `nextPageToken`을 `pageToken`으로 전달합니다.
`select`	`list<SelectedPropertyApiName>`	반환할 속성 API 이름 목록입니다. 생략하면 기본 반환 대상 속성을 읽습니다.
`orderBy`	`string`	정렬할 속성과 방향을 지정합니다. 여러 속성은 쉼표로 구분합니다.
`sdkPackageRid`	`string`	생성된 SDK 패키지의 RID입니다.
`sdkVersion`	`string`	생성된 SDK의 버전입니다.
`excludeRid`	`boolean`	__rid 속성을 읽지 않도록 합니다. OSv2 객체 유형에서는 성능이 개선될 수 있습니다.
`snapshot`	`boolean`	페이지 조회에 스냅샷 일관성을 사용할지 지정합니다. true이면 페이지 조회를 시작하기 전의 일관된 상태를 읽어 중복과 누락을 방지합니다. false이면 조회 중 추가된 결과가 들어올 수 있고 중복이나 누락도 발생할 수 있습니다. 기본값은 false입니다.
`branch`	`string`	객체를 조회할 Foundry 브랜치입니다. 생략하면 기본 브랜치를 사용합니다. 브랜치는 실험적 기능이며 일부 작업 경로는 지원하지 않습니다.
`loadOntologyDefinedDerivedProperties`	`boolean`	온톨로지 정의 파생 속성(OTDP)을 반환할지 지정합니다. 기본값은 true이며 속성을 명시적으로 선택하지 않았을 때만 적용됩니다. 속성을 선택하면 이 플래그와 관계없이 선택한 속성을 반환합니다. 실험적 기능이며 아직 일반 제공 기능이 아닙니다.

orderBy에서는 각 속성 앞에 properties. 또는 p.를 붙이고, 뒤에 :asc 또는 :desc를 지정합니다. 기본 방향은 오름차순입니다.

orderBy=properties.lastName:asc
orderBy=properties.lastName,properties.firstName,properties.age:desc

properties.lastName:asc를 p.lastName:asc로 줄여 쓸 수도 있습니다.

branch 값의 예는 ri.branch..branch.d827184f-ee0e-4351-8b70-efbe51e07252입니다.

요청 본문

요청 본문을 사용하지 않습니다.

응답

응답 형식은 ListObjectsResponseV2입니다.

이름	자료형	필수 여부	의미와 조건	예시 값
`nextPageToken`	`string`	선택	다음 페이지를 요청할 때 `pageToken`에 전달할 토큰입니다. 다음 토큰이 없으면 마지막 페이지입니다.
`data`	`list<OntologyObjectV2>`	선택	현재 페이지의 객체 목록입니다.
`totalCount`	`long`	필수	모든 페이지에 걸친 전체 항목 수입니다.	`7587`

`data`의 구조

배열 항목은 OntologyObjectV2이며 자료형은 map<PropertyApiName, PropertyValue>입니다.

맵의 키는 PropertyApiName(string), 값은 PropertyValue(any)입니다.

키: 속성의 API 이름입니다. Get Object Type 또는 Ontology Manager에서 확인합니다.

자료형별 JSON 표현은 객체 속성 값을 따릅니다.

객체 목록의 응답 예시입니다.

{
  "nextPageToken": "v1.QnVpbGQgdGhlIEZ1dHVyZTogaHR0cHM6Ly93d3cucGFsYW50aXIuY29tL2NhcmVlcnMvP2xldmVyLXNvdXJjZSU1YiU1ZD1BUElEb2NzI29wZW4tcG9zaXRpb25z",
  "data": [
    {
      "__rid": "ri.phonograph2-objects.main.object.88a6fccb-f333-46d6-a07e-7725c5f18b61",
      "__primaryKey": 50030,
      "__apiName": "Employee",
      "id": 50030,
      "firstName": "John",
      "lastName": "Doe"
    },
    {
      "__rid": "ri.phonograph2-objects.main.object.dcd887d1-c757-4d7a-8619-71e6ec2c25ab",
      "__primaryKey": 20090,
      "__apiName": "Employee",
      "id": 20090,
      "firstName": "John",
      "lastName": "Haymore"
    }
  ],
  "totalCount": 4
}

curl \
	-H "Authorization: Bearer ${FOUNDRY_TOKEN}" \
	"https://${FOUNDRY_HOST}/api/v2/ontologies/palantir/objects/employee?branch=ri.branch..branch.d827184f-ee0e-4351-8b70-efbe51e07252"

Python

Requests 라이브러리가 설치된 Python 환경에서 사용합니다.

import os
import requests

HOSTNAME = os.environ["FOUNDRY_HOST"]
TOKEN = os.environ["FOUNDRY_TOKEN"]
headers = {
    "authorization": "Bearer {}".format(TOKEN)
}

response = requests.get('https://{}/api/v2/ontologies/palantir/objects/employee?branch=ri.branch..branch.d827184f-ee0e-4351-8b70-efbe51e07252'.format(HOSTNAME), headers=headers)
print(response)

Java

Apache HttpClient 4.5 API와 try-with-resources를 사용합니다. 클래스 이름에 맞는 ListObjectsV2Example.java 파일에서 사용합니다.

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClientBuilder;

public class ListObjectsV2Example {
    public static void main(String[] args) throws Exception {
        String HOSTNAME = System.getenv("FOUNDRY_HOST");
        String TOKEN = System.getenv("FOUNDRY_TOKEN");

        try (CloseableHttpClient httpClient = HttpClientBuilder.create().build()) {
            HttpGet request = new HttpGet("https://" + HOSTNAME + "/api/v2/ontologies/palantir/objects/employee?branch=ri.branch..branch.d827184f-ee0e-4351-8b70-efbe51e07252");
            request.addHeader("authorization", String.format("Bearer %s", TOKEN));
            try (CloseableHttpResponse response = httpClient.execute(request)) {
                System.out.println(response);
            }
        }
    }
}

JavaScript

fetch를 제공하는 Node.js 환경에서 사용합니다. 서비스 사용자 토큰을 브라우저로 전달하지 않습니다.

const HOSTNAME = process.env.FOUNDRY_HOST;
const TOKEN = process.env.FOUNDRY_TOKEN;

fetch(`https://${HOSTNAME}/api/v2/ontologies/palantir/objects/employee?branch=ri.branch..branch.d827184f-ee0e-4351-8b70-efbe51e07252`, {
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${TOKEN}`,
    }
}).then((response) => {
    console.log(response)
});

PowerShell

$ErrorActionPreference = 'Stop'
$TOKEN = $env:FOUNDRY_TOKEN
$HOSTNAME = $env:FOUNDRY_HOST

$headers = @{
    "authorization" = "Bearer $TOKEN"
}

$response = Invoke-WebRequest -Uri "https://$HOSTNAME/api/v2/ontologies/palantir/objects/employee?branch=ri.branch..branch.d827184f-ee0e-4351-8b70-efbe51e07252" `
	-Headers $headers

$response.content

팔란티어 플랫폼 한국어 해설