API 페이지 나누기

여러 결과를 반환하는 페이지형 엔드포인트는 응답의 nextPageToken으로 다음 조회 위치를 알려 줍니다. 첫 요청에서는 pageToken을 생략하고, 다음 요청에서는 이전 응답의 nextPageToken을 pageToken으로 전달합니다. 나머지 조회 조건은 유지합니다.

다음 토큰이 없거나 null이면 마지막 페이지입니다. 페이지 토큰은 수명이 짧고 바로 이어서 순차 조회하는 용도입니다.

데이터 일관성

기본 페이징은 최신 결과를 반환합니다. 페이지를 가져오는 사이 데이터가 바뀌면 이미 본 항목이 반복되거나 일부 항목이 빠질 수 있습니다.

스냅샷 페이징(Snapshot pagination)은 조회를 시작하기 전 특정 시점의 데이터를 기준으로 결과를 고정합니다. 페이지 전체에서 중복과 누락 없이 일관된 결과를 얻지만 이후 변경을 반영하지 않은 데이터일 수 있습니다.

snapshot 매개변수를 지원하는 작업에는 다음이 있습니다.

• Load Object Set
• Load Object Set Multiple Object Types
• Load Object Set Objects Or Interfaces
• V2 List Objects

해당 매개변수를 제공하는 엔드포인트에서만 사용합니다. V2 List Objects의 snapshot 기본값은 false이며 true로 지정하면 스냅샷 일관성을 요청합니다. 다른 엔드포인트에 같은 이름의 매개변수를 임의로 추가하지 않습니다.

요청 크기와 실제 페이지 크기

pageSize를 지원하면 원하는 결과 수를 지정할 수 있습니다. 요청한 수는 제안값이므로 실제 페이지에는 더 적거나 더 많은 결과가 들어올 수 있습니다. 다음 결과가 남아 있으면 페이지에 최소 한 건이 있으며 nextPageToken이 존재하는지로 조회를 계속할지 판단합니다.

기본 페이지 크기는 엔드포인트마다 다릅니다. 별도 설명이 없으면 기본값이 최대 크기이기도 하며, 최대값보다 크게 요청하면 최대 크기로 줄입니다.

전체 페이지 합산 한도

한 페이지의 크기와 모든 페이지에서 가져올 수 있는 총건수는 다른 제한입니다. 예를 들어 V2 List Objects는 Object Storage V1 기반 객체에 대해 총 10,000개까지 반환하고, 더 남은 상태에서 다음 페이지를 요청하면 ObjectsExceededLimit을 반환합니다. Object Storage V2 기반 객체에는 이 10,000개 합산 한도가 없습니다.

다른 작업의 합산 한도는 해당 엔드포인트에서 확인해야 합니다. 페이지 크기를 줄여도 전체 조회 한도가 늘어나지는 않습니다.

세 페이지 조회 예시

다음은 employee 객체 세 건을 한 건씩 가져오는 가상 응답입니다. 호스트, 온톨로지 RID와 토큰은 예시이며 실제 응답의 토큰을 수정하지 않고 다음 요청에 사용합니다. V2 객체의 속성은 properties 하위 객체가 아니라 각 객체의 최상위에 있습니다.

첫 요청:

GET /api/v2/ontologies/ri.ontology.main.ontology.00000000-0000-0000-0000-000000000000/objects/employee?pageSize=1

첫 응답:

{
  "nextPageToken": "v1.QnVpbGQgdGhlIEZ1dHVyZTogaHR0cHM6Ly93d3cucGFsYW50aXIuY29tL2NhcmVlcnMvP2xldmVyLXNvdXJjZSU1YiU1ZD1BUElEb2NzI29wZW4tcG9zaXRpb25z",
  "totalCount": "3",
  "data": [
    {"id": 50030, "firstName": "John", "lastName": "Doe"}
  ]
}

두 번째 요청:

GET /api/v2/ontologies/ri.ontology.main.ontology.00000000-0000-0000-0000-000000000000/objects/employee?pageSize=1&pageToken=v1.QnVpbGQgdGhlIEZ1dHVyZTogaHR0cHM6Ly93d3cucGFsYW50aXIuY29tL2NhcmVlcnMvP2xldmVyLXNvdXJjZSU1YiU1ZD1BUElEb2NzI29wZW4tcG9zaXRpb25z

두 번째 응답:

{
  "nextPageToken": "v1.VGhlcmUncyBhIHJvbGUgaGVyZSBmb3IgeW91IC0gcGFsYW50aXIuY29tL2NhcmVlcnMv",
  "totalCount": "3",
  "data": [
    {"id": 80060, "firstName": "Anna", "lastName": "Smith"}
  ]
}

세 번째 요청:

GET /api/v2/ontologies/ri.ontology.main.ontology.00000000-0000-0000-0000-000000000000/objects/employee?pageSize=1&pageToken=v1.VGhlcmUncyBhIHJvbGUgaGVyZSBmb3IgeW91IC0gcGFsYW50aXIuY29tL2NhcmVlcnMv

세 번째 응답:

{
  "nextPageToken": null,
  "totalCount": "3",
  "data": [
    {"id": 40040, "firstName": "Silvia", "lastName": "Sindoni"}
  ]
}

세 번째 응답에는 다음 토큰이 없으므로 조회를 끝냅니다. 페이지 크기와 관계없이 종료 조건은 다음 토큰입니다.