V1 객체 조회와 필터
객체(Object)는 객체 유형의 한 인스턴스에 해당하는 데이터를 담습니다. 예를 들어 Employee 객체 유형에 속한 직원 한 명을 하나의 객체로 표현합니다. API 응답은 객체 RID와 속성값 맵으로 구성됩니다.
| 작업 | 기능 |
|---|---|
| List Objects | 객체 유형의 객체를 나열하고 URL 필터를 적용합니다. |
| Get Object | 기본 키로 한 객체를 조회합니다. |
| List Linked Objects | 기준 객체에서 특정 링크로 연결된 객체를 나열합니다. |
| Get Linked Object | 기준 객체와의 링크를 통해 특정 객체를 조회합니다. |
| Search Objects | JSON 검색 조건으로 객체를 조회합니다. |
| Aggregate Objects | 객체 속성의 집계와 그룹화를 수행합니다. |
| 집계 유형과 예시 | 집계 함수, 구간, null 처리와 그룹 한도를 확인합니다. |
| 속성값 자료형 | 객체 응답의 값 인코딩을 확인합니다. |
URL 필터
List Objects와 List Linked Objects에서 다음 형태의 쿼리 매개변수를 사용합니다. 값에는 URL 인코딩을 적용합니다.
properties.{propertyApiName}.{propertyFilter}={propertyValueEscapedString}
속성 이름의 대소문자는 구분하지 않으며 properties.를 p.로 줄일 수 있습니다. 다음 두 조건은 firstName이 John인 객체를 찾습니다.
properties.firstName.eq=John
p.firstname.eq=John
| 필터 | 의미 | 지원 속성 유형 | 예시 |
|---|---|---|---|
contains | 배열에 값 포함 | 배열 | properties.names.contains=John |
eq | 정확히 같은 값 | 배열과 첨부 파일을 제외한 모든 유형 | properties.firstName.eq=John |
neq | 같지 않은 값 | 배열과 첨부 파일을 제외한 모든 유형 | properties.firstName.neq=John |
lt | 미만 | date, timestamp, byte, integer, long, double, decimal | properties.age.lt=40 |
lte | 이하 | date, timestamp, byte, integer, long, double, decimal | properties.age.lte=40 |
gt | 초과 | date, timestamp, byte, integer, long, double, decimal | properties.age.gt=40 |
gte | 이상 | date, timestamp, byte, integer, long, double, decimal | properties.age.gte=40 |
isNull | null 여부 | 첨부 파일을 제외한 모든 유형 | properties.firstName.isNull=false |
같은 속성에 eq 또는 contains 필터를 여러 번 적용하면 주어진 값 중 하나에 해당하는 객체를 찾습니다. 같은 속성에 lt와 gte 같은 범위 필터를 함께 적용하면 두 조건을 모두 충족해야 합니다.
다음은 이름이 John 또는 Anna이고, 1980년대에 태어났으며, 관심사에 tennis나 golf가 있고, 주소가 null이 아닌 사람을 찾는 가상 예시입니다. URL의 쿼리 부분을 줄별로 표시했습니다.
?p.firstName.eq=John
&p.firstName.eq=Anna
&p.birthDate.gte=1980-01-01
&p.birthDate.lt=1990-01-01
&p.interests.contains=tennis
&p.interests.contains=golf
&p.streetAddress.isNull=false
JSON 본문으로 검색하는 Search Objects에서는 별도의 검색 조건 형식을 사용합니다.
GET 조회의 반환 속성 선택
위의 네 GET 조회 작업은 properties 쿼리 매개변수로 반환할 속성을 선택합니다. 기본 반환 대상은 Vector를 제외한 모든 속성입니다. Vector 속성을 포함하려면 해당 속성을 명시적으로 선택합니다.
속성 API 이름을 쉼표로 구분하거나 매개변수를 반복할 수 있습니다.
properties=firstName,lastName
properties=firstName&properties=lastName
객체의 기본 키는 선택 목록에 없어도 항상 반환됩니다. 존재하지 않는 속성을 지정하면 PropertiesNotFound 오류가 발생합니다. 속성 API 이름은 Get Object Type 또는 Ontology Manager에서 확인합니다. 객체 집합 API에서는 이 선택 매개변수를 select라고 부르므로 엔드포인트별 이름을 사용합니다.
정렬
List Objects와 List Linked Objects의 orderBy는 속성별 정렬 방향을 쉼표로 연결한 문자열입니다. 기본 방향은 오름차순이며 :asc 또는 :desc를 붙일 수 있습니다.
orderBy=properties.lastName:asc
orderBy=properties.lastName,properties.firstName,properties.age:desc
orderBy=p.lastName:asc
목록의 일관성과 한도
두 목록 GET 작업은 페이지 간 일관성을 보장하지 않습니다. 조회 도중 데이터가 바뀌면 객체가 누락되거나 반복될 수 있습니다. Object Storage V1 기반 객체는 최대 10,000개까지 반환하며, 결과가 더 있는 상태에서 다음 페이지를 요청하면 ObjectsExceededLimit 오류가 발생합니다. Object Storage V2 기반 객체에는 이 총반환 한도가 없습니다.
페이지 크기는 요청값보다 작거나 클 수 있습니다. 결과가 더 남아 있으면 현재 응답에는 최소 한 객체가 포함됩니다. 이 두 목록 작업은 null 값 속성을 반환하지 않습니다.