풀 기반 수집 관리 API

풀 기반 수집 관리 API (Pull-based Ingestion Management API)

3.0에서 도입되었어요. OpenSearch는 풀 기반 수집(pull-based ingestion)을 관리하기 위한 다음 API를 제공해요.

출처: 문서

본문

수집 일시 중지 (Pause ingestion)

하나 이상의 인덱스의 수집을 일시 중지해요. 일시 중지되면 OpenSearch는 지정된 인덱스의 모든 샤드에 대해 스트리밍 소스에서 데이터를 소비하는 것을 멈춰요.

엔드포인트 (Endpoint)

POST /{index}/ingestion/_pause

경로 파라미터 (Path parameters)

다음 표는 사용 가능한 경로 파라미터를 보여줘요.

파라미터	데이터 타입	필수/선택	설명
index	String	필수	일시 중지할 인덱스예요. 여러 인덱스 이름을 쉼표로 구분한 목록일 수 있어요.

쿼리 파라미터 (Query parameters)

다음 표는 사용 가능한 쿼리 파라미터를 보여줘요. 모든 쿼리 파라미터는 선택 사항이에요.

파라미터	데이터 타입	설명
cluster_manager_timeout	Time units	클러스터 매니저 노드에 연결하기 위해 기다리는 시간이에요. 기본값은 `30s`예요.
timeout	Time units	클러스터의 응답을 기다리는 시간이에요. 기본값은 `30s`예요.

예제 요청 (Example request)

수집 재개 (Resume ingestion)

하나 이상의 인덱스의 수집을 재개해요. 재개되면 OpenSearch는 지정된 인덱스의 모든 샤드에 대해 스트리밍 소스에서 데이터를 소비하는 것을 계속해요.

재개 작업의 일부로, 스트림 소비자가 특정 오프셋(offset)이나 타임스탬프부터 읽기 시작하도록 선택적으로 리셋할 수 있어요. 리셋 설정이 지정되면 선택된 샤드의 모든 소비자가 인덱스에 재개 작업이 적용되기 전에 리셋돼요. 소비자를 리셋하면 변경 사항을 유지하기 위해 내부 flush도 함께 트리거돼요.

엔드포인트 (Endpoint)

POST /{index}/ingestion/_resume

경로 파라미터 (Path parameters)

다음 표는 사용 가능한 경로 파라미터를 보여줘요.

파라미터	데이터 타입	필수/선택	설명
index	String	필수	수집을 재개할 인덱스예요. 여러 인덱스 이름을 쉼표로 구분한 목록일 수 있어요.

쿼리 파라미터 (Query parameters)

다음 표는 사용 가능한 쿼리 파라미터를 보여줘요. 모든 쿼리 파라미터는 선택 사항이에요.

파라미터	데이터 타입	설명
cluster_manager_timeout	Time units	클러스터 매니저 노드에 연결하기 위해 기다리는 시간이에요. 기본값은 `30s`예요.
timeout	Time units	클러스터의 응답을 기다리는 시간이에요. 기본값은 `30s`예요.

요청 본문 필드 (Request body fields)

다음 표는 사용 가능한 요청 본문 필드를 보여줘요.

필드	데이터 타입	필수/선택	설명
reset_settings	Array	선택	각 샤드의 리셋 설정 목록이에요. 제공하지 않으면 OpenSearch는 지정된 인덱스의 각 샤드에 대해 현재 위치부터 수집을 재개해요.
reset_settings.shard	Integer	필수	리셋할 샤드예요.
reset_settings.mode	String	필수	리셋 모드예요. 유효한 값은 `offset`(양의 정수 오프셋)과 `timestamp`(밀리초 단위의 Unix 타임스탬프)예요.
reset_settings.value	String	필수	- `offset` : Apache Kafka 오프셋 또는 Amazon Kinesis 시퀀스 번호예요. - `timestamp` : 밀리초 단위의 Unix 타임스탬프예요.

예제 요청 (Example request)

리셋 설정 없이 수집을 재개하려면 다음 요청을 보내요.

수집을 재개할 때 리셋 설정을 제공하려면 다음 요청을 보내요.

수집 상태 조회 (Get ingestion state)

하나 이상의 인덱스의 현재 수집 상태를 반환해요. 이 API는 페이지네이션을 지원해요.

엔드포인트 (Endpoint)

GET /{index}/ingestion/_state

경로 파라미터 (Path parameters)

다음 표는 사용 가능한 경로 파라미터를 보여줘요.

파라미터	데이터 타입	필수/선택	설명
index	String	필수	수집 상태를 반환할 인덱스예요. 여러 인덱스 이름을 쉼표로 구분한 목록일 수 있어요.

쿼리 파라미터 (Query parameters)

다음 표는 사용 가능한 쿼리 파라미터를 보여줘요. 모든 쿼리 파라미터는 선택 사항이에요.

파라미터	데이터 타입	설명
timeout	Time units	클러스터의 응답을 기다리는 시간이에요. 기본값은 `30s`예요.

예제 요청 (Example request)

다음은 기본 설정을 사용한 요청이에요.

다음 예제는 페이지 크기가 20인 요청을 보여줘요.

다음 예제는 다음 페이지 토큰을 사용하는 요청을 보여줘요.

예제 응답 (Example response)

{
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0,
    "failures": [
      {
        "shard": 0,
        "index": "my-index",
        "status": "INTERNAL_SERVER_ERROR",
        "reason": {
          "type": "timeout_exception",
          "reason": "error message"
        }
      }
    ]
  },
  "next_page_token" : "page token if not on last page",
  "ingestion_state": {
    "indexName": [
      {
        "shard": 0,
        "poller_state": "POLLING",
        "error_policy": "DROP",
        "poller_paused": false,
        "write_block_enabled" : false,
        "batch_start_pointer" : "KafkaOffset{offset=2}",
        "is_primary" : true,
        "node" : "node_name"
      }
    ]
  }
}

더 알아보기 (Learn more)

OpenSearch 공식 문서