Point in Time API

Point in Time(PIT) API를 사용해 PIT를 관리해요.

PIT 생성 (Create a PIT)

도입 버전 2.4

PIT를 생성해요. keep_alive 쿼리 파라미터는 필수이며, PIT를 얼마나 오래 유지할지 지정해요.

엔드포인트

POST /{target_indexes}/_search/point_in_time?keep_alive=1h&routing=&expand_wildcards=&preference=

경로 파라미터

파라미터	데이터 타입	설명
target_indexes	String	PIT의 대상 인덱스 이름이에요. 쉼표로 구분된 목록이나 와일드카드 인덱스 패턴을 포함할 수 있어요.

쿼리 파라미터

파라미터	데이터 타입	설명
keep_alive	Time	PIT를 유지할 시간이에요. Search API로 PIT에 접근할 때마다 PIT의 수명이 keep_alive 파라미터 값만큼 연장돼요. 필수예요.
preference	String	검색을 수행할 노드나 샤드예요. 선택 사항이며 기본값은 random 이에요.
routing	String	검색 요청을 특정 샤드로 라우팅하도록 지정해요. 선택 사항이며 기본값은 문서의 _id 예요.
expand_wildcards	String	와일드카드 패턴과 일치할 수 있는 인덱스 유형이에요. 쉼표로 구분된 값을 지원해요. 유효한 값은 다음과 같아요: - all : 숨겨진 것을 포함한 모든 인덱스나 데이터 스트림과 일치. - open : 열려 있고 숨겨지지 않은 인덱스나 데이터 스트림과 일치. - closed : 닫혀 있고 숨겨지지 않은 인덱스나 데이터 스트림과 일치. - hidden : 숨겨진 인덱스나 데이터 스트림과 일치. open , closed 또는 둘 다와 결합해야 해요. - none : 와일드카드 패턴을 허용하지 않아요. 선택 사항이며 기본값은 open 이에요.
allow_partial_pit_creation	Boolean	부분 실패로 PIT를 생성할지 여부를 지정해요. 선택 사항이며 기본값은 true 예요.

예제 요청

POST /my-index-1/_search/point_in_time?keep_alive=100m

예제 응답

{
    "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFnNOWU43ckt3U3IyaFVpbGE1UWEtMncAFjFyeXBsRGJmVFM2RTB6eVg1aVVqQncAAAAAAAAAAAIWcDVrM3ZIX0pRNS1XejE5YXRPRFhzUQEWc05ZTjdyS3dTcjJoVWlsYTVRYS0ydwAA",
    "_shards": {
        "total": 1,
        "successful": 1,
        "skipped": 0,
        "failed": 0
    },
    "creation_time": 1658146050064
}

응답 본문 필드

필드	데이터 타입	설명
pit_id	Base64 인코딩 바이너리	PIT ID예요.
creation_time	long	PIT가 생성된 시각으로, 에포크 이후 경과한 밀리초예요.

PIT 시간 연장

검색을 수행할 때 pit 객체에 keep_alive 파라미터를 제공하면 PIT 시간을 연장할 수 있어요:

GET /_search
{
  "size": 10000,
  "query": {
    "match" : {
      "user.id" : "elkbee"
    }
  },
  "pit": {
    "id":  "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==", 
    "keep_alive": "100m"
  },
  "sort": [ 
    {"@timestamp": {"order": "asc"}}
  ],
  "search_after": [  
    "2021-05-20T05:30:04.832Z"
  ]
}

검색 요청의 keep_alive 파라미터는 선택 사항이에요. PIT를 유지할 시간을 얼마나 연장할지 지정해요.

모든 PIT 나열 (List all PITs)

도입 버전 2.4

OpenSearch 클러스터의 모든 PIT를 반환해요.

크로스 클러스터 동작

List All PITs API는 로컬 PIT 또는 혼합 PIT(로컬 및 원격 클러스터 모두에서 생성된 PIT)만 반환해요. 완전히 원격인 PIT는 반환하지 않아요.

예제 요청

GET /_search/point_in_time/_all

예제 응답

{
    "pits": [
        {
            "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFnNOWU43ckt3U3IyaFVpbGE1UWEtMncAFjFyeXBsRGJmVFM2RTB6eVg1aVVqQncAAAAAAAAAAAEWcDVrM3ZIX0pRNS1XejE5YXRPRFhzUQEWc05ZTjdyS3dTcjJoVWlsYTVRYS0ydwAA",
            "creation_time": 1658146048666,
            "keep_alive": 6000000
        },
        {
            "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFnNOWU43ckt3U3IyaFVpbGE1UWEtMncAFjFyeXBsRGJmVFM2RTB6eVg1aVVqQncAAAAAAAAAAAIWcDVrM3ZIX0pRNS1XejE5YXRPRFhzUQEWc05ZTjdyS3dTcjJoVWlsYTVRYS0ydwAA",
            "creation_time": 1658146050064,
            "keep_alive": 6000000
        }
    ]
}

응답 본문 필드

필드	데이터 타입	설명
pits	JSON 객체 배열	모든 PIT 목록이에요.

각 PIT 객체는 다음 필드를 포함해요.

필드	데이터 타입	설명
pit_id	Base64 인코딩 바이너리	PIT ID예요.
creation_time	long	PIT가 생성된 시각으로, 에포크 이후 경과한 밀리초예요.
keep_alive	long	PIT를 유지할 시간(밀리초)이에요.

PIT 삭제 (Delete PITs)

도입 버전 2.4

하나, 여러 개 또는 모든 PIT를 삭제해요. PIT는 keep_alive 시간이 경과하면 자동으로 삭제돼요. 하지만 리소스를 해제하려면 Delete PIT API로 PIT를 삭제할 수 있어요. Delete PIT API는 ID로 PIT 목록을 삭제하거나 모든 PIT를 한 번에 삭제하는 것을 지원해요.

크로스 클러스터 동작

Delete PITs by ID API는 크로스 클러스터 PIT 삭제를 완전히 지원해요.

Delete All PITs API는 로컬 PIT 또는 혼합 PIT(로컬 및 원격 클러스터 모두에서 생성된 PIT)만 삭제해요. 완전히 원격인 PIT는 삭제하지 않아요.

예제 요청: 모든 PIT 삭제

DELETE /_search/point_in_time/_all

하나 또는 여러 PIT를 삭제하려면 요청 본문에 PIT ID를 지정하세요.

요청 본문 필드

필드	데이터 타입	설명
pit_id	Base64 인코딩 바이너리 또는 바이너리 배열	삭제할 PIT의 PIT ID예요. 필수예요.

예제 요청: ID로 PIT 삭제

DELETE /_search/point_in_time
{
  "pit_id": [
    "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAEWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA",
    "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAIWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA"
  ]
}

예제 응답

각 PIT에 대해 응답은 PIT ID와 삭제가 성공했는지를 나타내는 successful 필드를 가진 JSON 객체를 포함해요. 부분 실패는 실패로 간주돼요.

{
    "pits": [
        {
            "successful": true,
            "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAEWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA"
        },
        {
            "successful": false,
            "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAIWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA"
        }
    ]
}

응답 본문 필드

필드	데이터 타입	설명
successful	Boolean	삭제 작업이 성공했는지 여부예요.
pit_id	Base64 인코딩 바이너리	삭제할 PIT의 PIT ID예요.

보안 모델 (Security model)

이 섹션은 Security 플러그인을 활성화한 상태로 OpenSearch를 실행할 때 PIT API 작업을 사용하기 위해 필요한 권한을 설명해요.

point_in_time_full_access 역할을 사용하면 모든 PIT API 작업에 접근할 수 있어요. 이 역할이 요구 사항에 맞지 않으면 개별 PIT 권한을 조합해 사용 사례에 맞게 쓸 수 있어요. 각 작업(action)은 REST API의 작업(operation)과 일치해요. 예를 들어 indices:data/read/point_in_time/create 권한으로 PIT를 생성할 수 있어요. 가능한 권한은 다음과 같아요:

indices:data/read/point_in_time/create – Create API
indices:data/read/point_in_time/delete – Delete API
indices:data/read/point_in_time/readall – List All PITs API
indices:data/read/search – Search API
indices:monitor/point_in_time/segments – PIT Segments API

list all, delete all 같은 all API 작업에는 모든 인덱스(*) 권한이 필요해요. search, create PIT, delete list 같은 API 작업에는 개별 인덱스 권한만 있으면 돼요.

PIT ID는 저장될 때 항상 기본(확인된) 인덱스를 포함해요. 다음 섹션은 별칭과 데이터 스트림에 필요한 권한을 설명해요.

별칭 권한 (Alias permissions)

별칭의 경우 사용자는 모든 PIT 작업에 인덱스 또는 별칭 권한을 가져야 해요.

데이터 스트림 권한 (Data stream permissions)

데이터 스트림의 경우 사용자는 모든 PIT 작업에 데이터 스트림 및 데이터 스트림의 백킹 인덱스(backing index) 권한을 모두 가져야 해요. 예를 들어 사용자는 data-stream-11 데이터 스트림과 해당 백킹 인덱스 .ds-my-data-stream11-000001에 대한 권한이 있어야 해요.

사용자가 데이터 스트림 권한만 있다면 PIT를 생성할 수는 있지만, 백킹 인덱스 권한 없이는 검색 같은 다른 작업에 PIT ID를 사용할 수 없어요.

필요한 권한

Security 플러그인을 사용한다면 적절한 권한이 있는지 확인하세요. 이 API에 필요한 권한은 다음과 같아요:

indices:data/read/point_in_time/create: PIT 생성에 필요
indices:data/read/point_in_time/delete: PIT 삭제에 필요
indices:data/read/search: PIT로 검색하는 데 필요

사용자가 데이터 스트림 권한만 있다면 PIT를 생성할 수는 있지만, 백킹 인덱스 권한 없이는 검색 같은 다른 작업에 PIT ID를 사용할 수 없어요.

출처: 문서