JSON 조건으로 객체 검색(Search Objects) (V1)

요청 본문의 JSON 조건으로 지정한 온톨로지와 객체 유형을 검색합니다. 검색 조건은 최대 세 단계까지 중첩할 수 있으며 비교, null, 배열, 논리 조합과 문자열 검색을 지원합니다.

위치	이름	자료형	필수 여부	의미
경로	`ontologyRid`	string	필수	온톨로지 RID
경로	`objectType`	string	필수	검색할 객체 유형
본문	`query`	SearchJsonQuery	필수	검색 조건
본문	`orderBy`	SearchOrderBy	선택	속성과 방향을 담은 정렬 객체
본문	`pageSize`	integer	선택	한 페이지에 반환할 객체 수의 최댓값
본문	`pageToken`	string	선택	이전 응답의 다음 페이지 토큰. 첫 요청에서는 생략
본문	`fields`	`list<PropertyApiName>`	선택	응답에 포함할 속성 API 이름

쿼리 매개변수는 없으며 SearchObjectsRequest JSON 본문은 필수입니다. 속성 API 이름은 Get Object Type이나 Ontology Manager에서 확인합니다. 검색 조건의 field는 properties.age 같은 참조를 사용하고, fields 목록은 속성 API 이름을 사용합니다.

orderBy.fields는 선택적인 SearchOrdering 목록입니다. 각 항목의 field는 필수이며 선택적 direction은 asc 또는 desc입니다. 전체 검색 및 정렬 자료형을 확인합니다.

검색과 페이지 처리

기본 용어 구분자는 공백과 ?!,:;-[](){}'"~ 문장부호이며, 단독 마침표는 무시합니다. 용어 필터는 명시된 경우를 제외하면 부분 용어를 일치시키지 않습니다. anyTerm과 allTerms의 fuzzy로 근사 일치를 사용할 수 있습니다. 문자열 eq의 전체 용어 일치에는 속성의 Selectable 설정이 필요합니다.

pageSize는 최댓값입니다. 객체가 커서 내부 메모리 한도에 닿으면 페이지가 더 작아질 수 있으므로 크기만으로 마지막 페이지를 판단하지 않습니다. nextPageToken이 있으면 그 값을 다음 요청의 본문 pageToken에 넣어 계속 조회합니다.

SearchObjectsResponse 필드	자료형	필수 여부	의미
`data`	`list<OntologyObject>`	선택	검색 결과
`nextPageToken`	string	선택	다음 페이지 토큰
`totalCount`	long을 인코딩한 string	필수	전체 페이지의 항목 수

객체 응답과 속성값은 필수 rid 및 선택적인 properties 맵을 사용합니다. 가상 예시는 나이가 21이 아닌 객체를 검색하여 나이가 22인 한 객체를 반환합니다.

HTTP 요청

POST /api/v1/ontologies/{ontologyRid}/objects/{objectType}/search

작업 식별자는 v1.searchObjects입니다. Authorization: Bearer <접근 토큰> 헤더로 인증합니다. OAuth 클라이언트에는 api:ontologies-read 권한 범위가 필요합니다.

JSON 요청 예시

가상 객체 유형에 대한 요청 예시입니다.

{
  "query": {
    "type": "not",
    "value": {
      "type": "eq",
      "field": "properties.age",
      "value": 21
    }
  }
}

JSON 응답 예시

가상 객체 유형의 응답 예시입니다.

{
  "data": [
    {
      "properties": {
        "lastName": "smith",
        "firstName": "john",
        "age": 22
      },
      "rid": "ri.phonograph2-objects.main.object.5b5dbc28-7f05-4e83-a33a-1e5b851ababb"
    }
  ],
  "totalCount": "1"
}

curl -X POST \
	-H "Content-type: application/json" \
	-H "Authorization: Bearer ${FOUNDRY_TOKEN}" \
	"https://${FOUNDRY_HOST}/api/v1/ontologies/ri.ontology.main.ontology.c61d9ab5-2919-4127-a0a1-ac64c0ce6367/objects/employee/search" \
	-d '{"query":{"type":"not","value":{"type":"eq","field":"properties.age","value":21}}}'

Python

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

import os
import requests

HOSTNAME = os.environ["FOUNDRY_HOST"]
TOKEN = os.environ["FOUNDRY_TOKEN"]
headers = {
    "content-type": "application/json",
    "authorization": "Bearer {}".format(TOKEN)
}
request_body = {'query': {'type': 'not',
           'value': {'type': 'eq', 'field': 'properties.age', 'value': 21}}}

response = requests.post('https://{}/api/v1/ontologies/ri.ontology.main.ontology.c61d9ab5-2919-4127-a0a1-ac64c0ce6367/objects/employee/search'.format(HOSTNAME), headers=headers, json=request_body)
print(response)

Java

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

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.entity.ContentType;
import org.apache.http.entity.StringEntity;

public class SearchObjectsExample {
    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()) {
            HttpPost request = new HttpPost("https://" + HOSTNAME + "/api/v1/ontologies/ri.ontology.main.ontology.c61d9ab5-2919-4127-a0a1-ac64c0ce6367/objects/employee/search");
            request.addHeader("content-type", "application/json");
            request.addHeader("authorization", String.format("Bearer %s", TOKEN));
            request.setEntity(new StringEntity("{\"query\":{\"type\":\"not\",\"value\":{\"type\":\"eq\",\"field\":\"properties.age\",\"value\":21}}}", ContentType.APPLICATION_JSON));
            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/v1/ontologies/ri.ontology.main.ontology.c61d9ab5-2919-4127-a0a1-ac64c0ce6367/objects/employee/search`, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${TOKEN}`,
    },
    body: JSON.stringify({
    "query": {
        "type": "not",
        "value": {
            "type": "eq",
            "field": "properties.age",
            "value": 21
        }
    }
})
}).then((response) => {
    console.log(response)
});

PowerShell

$TOKEN = $env:FOUNDRY_TOKEN
$HOSTNAME = $env:FOUNDRY_HOST

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

$response = Invoke-WebRequest -Uri "https://$HOSTNAME/api/v1/ontologies/ri.ontology.main.ontology.c61d9ab5-2919-4127-a0a1-ac64c0ce6367/objects/employee/search" `
	-Method Post `
	-Headers $headers `
	-ContentType application/json `
	-Body '{"query":{"type":"not","value":{"type":"eq","field":"properties.age","value":21}}}'

$response.content

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