컴포넌트 템플릿 API
컴포넌트 템플릿 API (Component Template APIs)
1.0에서 도입되었어요. 컴포넌트 템플릿 API로 컴포넌트 템플릿을 만들고, 조회하고, 업데이트하고, 삭제할 수 있어요. 컴포넌트 템플릿은 설정, 매핑, 별칭을 정의하는 재사용 가능한 구성 요소로, 여러 인덱스 템플릿에서 공유할 수 있어요.
인덱스 템플릿은 여러 컴포넌트 템플릿으로 구성할 수 있어요. 컴포넌트 템플릿을 인덱스 템플릿에 포함하려면 인덱스 템플릿의 composed_of 섹션에 그 이름을 나열해야 해요. 컴포넌트 템플릿은 인덱스 템플릿에 지정된 기준과 일치하는 새로 생성된 데이터 스트림과 인덱스에만 적용돼요.
인덱스 템플릿이나 인덱스 생성 요청에 직접 정의된 설정이나 매핑이 있다면, 그 설정은 컴포넌트 템플릿에 지정된 설정이나 매핑보다 우선해요.
컴포넌트 템플릿은 오직 인덱스 생성 과정에서만 사용돼요. 데이터 스트림의 경우 여기에는 데이터 스트림 자체의 생성과 스트림을 지원하는 backing index의 생성이 포함돼요. 컴포넌트 템플릿에 가한 수정은 기존 인덱스에는 영향을 주지 않아요. 데이터 스트림의 backing index도 마찬가지예요.
출처: 문서
본문
엔드포인트 (Endpoints)
PUT _component_template/{component-template-name}
GET _component_template/{component-template-name}
DELETE _component_template/{component-template-name}
HEAD _component_template/{component-template-name}
- PUT: 컴포넌트 템플릿을 만들거나 업데이트해요. 쿼리 파라미터와 요청 본문을 모두 받아요.
- GET: 기존 컴포넌트 템플릿에 대한 정보를 조회해요. 쿼리 파라미터만 받아요.
- DELETE: 기존 컴포넌트 템플릿을 삭제해요. 쿼리 파라미터만 받아요.
- HEAD: 컴포넌트 템플릿이 존재하는지 반환해요. HTTP 상태 코드만 반환해요.
경로 파라미터 (Path parameters)
다음 표는 사용 가능한 경로 파라미터를 보여줘요.
| 파라미터 | 데이터 타입 | 설명 |
|---|---|---|
| component-template-name | String | 컴포넌트 템플릿의 이름이에요. PUT, HEAD, DELETE 작업에는 필수예요. GET 작업에는 선택 사항이에요. |
쿼리 파라미터 (Query parameters)
다음 표는 사용 가능한 쿼리 파라미터를 보여줘요. 모든 쿼리 파라미터는 선택 사항이에요.
| 파라미터 | 데이터 타입 | 설명 | 지원 작업 |
|---|---|---|---|
| create | Boolean | true이면 API가 기존 컴포넌트 템플릿을 교체하거나 업데이트할 수 없어요. 기본값은 false예요. |
PUT |
| cluster_manager_timeout | Time | 클러스터 매니저 노드에 연결하기 위해 기다리는 시간이에요. 기본값은 30s예요. |
PUT, GET, DELETE |
컴포넌트 템플릿 만들기 또는 업데이트 (Create or update a component template)
PUT 작업으로 새 컴포넌트 템플릿을 만들거나 기존 템플릿을 업데이트해요.
엔드포인트 (Endpoints)
PUT _component_template/{component-template-name}
요청 본문 필드 (Request body fields)
다음 표는 사용 가능한 요청 본문 필드를 보여줘요.
| 파라미터 | 데이터 타입 | 설명 |
|---|---|---|
| template | Object | 인덱스의 aliases, mappings, 또는 settings를 포함하는 템플릿이에요. 자세한 내용은 템플릿을 참고하세요. 필수예요. |
| version | Integer | 인덱스 템플릿을 관리하는 데 사용하는 버전 번호예요. 버전 번호는 OpenSearch가 자동으로 설정하지 않아요. 선택 사항이에요. |
| _meta | Object | 인덱스 템플릿에 대한 세부 정보를 제공하는 메타데이터예요. 선택 사항이에요. |
| allow_auto_create | Boolean | true이면 actions.auto_create_index가 비활성화되어 있어도 이 템플릿으로 인덱스를 자동 생성할 수 있어요. false이면 템플릿과 일치하는 인덱스와 데이터 스트림을 자동 생성할 수 없어요. 선택 사항이에요. |
| deprecated | Boolean | true이면 컴포넌트 템플릿이 deprecated 처리돼요. deprecated되면 OpenSearch가 템플릿을 참조할 때마다 경고를 출력해요. |
템플릿 (Template)
요청 본문의 template 옵션과 함께 다음 객체를 사용할 수 있어요.
alias
템플릿과 연결할 별칭을 키로 하는 이름이에요. 요청 본문에 template 옵션이 있으면 필수예요. 이 옵션은 여러 별칭을 지원해요.
객체 본문에는 다음 선택 별칭 파라미터가 들어 있어요.
| 파라미터 | 데이터 타입 | 설명 |
|---|---|---|
| filter | Query DSL object | 별칭이 접근할 수 있는 문서 수를 제한하는 쿼리예요. |
| index_routing | String | 인덱싱 작업을 특정 샤드로 라우팅하는 값이에요. 지정하면 인덱싱 작업의 라우팅 값을 덮어써요. |
| is_hidden | Boolean | true이면 별칭이 숨겨져요. 기본값은 false예요. 모든 별칭 인덱스는 이 설정에 대해 일치하는 값을 가져야 해요. |
| is_write_index | Boolean | true이면 인덱스가 별칭의 쓰기 인덱스예요. 기본값은 false예요. |
| routing | String | 인덱스와 검색 작업을 특정 샤드로 라우팅하는 데 사용하는 값이에요. |
| search_routing | String | 검색 작업을 특정 샤드로 쓰기 위해 사용하는 값이에요. 지정하면 검색 작업의 라우팅 값을 덮어써요. |
mappings
인덱스에 존재하는 필드 매핑이에요. 자세한 내용은 Mappings and field types를 참고하세요. 선택 사항이에요.
settings
인덱스의 모든 구성 옵션이에요. 자세한 내용은 Index settings를 참고하세요.
예제 요청: 인덱스 별칭이 있는 컴포넌트 템플릿 만들기 (Example request: Create a component template with index aliases)
다음 예제 요청은 인덱스 별칭을 포함한 컴포넌트 템플릿을 만들어요.
예제 요청: 컴포넌트 버전 지정 추가 (Example request: Add component versioning)
다음 예제는 컴포넌트 템플릿에 버전 번호를 추가해서 외부 시스템이 템플릿을 더 쉽게 관리하도록 해요.
예제 요청: 템플릿 메타데이터 추가 (Example request: Add template metadata)
다음 예제 요청은 _meta 파라미터로 컴포넌트 템플릿에 메타데이터를 추가해요. 모든 메타데이터는 클러스터 상태에 저장돼요.
컴포넌트 템플릿 조회 (Retrieve component template)
GET 작업으로 하나 이상의 컴포넌트 템플릿과 그 정보를 조회해요.
엔드포인트 (Endpoints)
GET /_component_template/{component-template-name}
GET /_component_template
경로 파라미터 (Path parameters)
다음 표는 사용 가능한 경로 파라미터를 보여줘요. 모든 경로 파라미터는 선택 사항이에요.
| 파라미터 | 데이터 타입 | 설명 |
|---|---|---|
| component-template-name | String | 조회할 컴포넌트 템플릿의 이름이에요. 와일드카드 표현(*)을 지원해요. 지정하지 않으면 모든 컴포넌트 템플릿을 반환해요. |
예제 요청: 이름으로 컴포넌트 템플릿 조회 (Example request: Retrieve a component template by name)
예제 요청: 와일드카드 패턴으로 컴포넌트 템플릿 조회 (Example request: Retrieve component templates using a wildcard pattern)
예제 요청: 모든 컴포넌트 템플릿 조회 (Example request: Retrieve all component templates)
컴포넌트 템플릿 삭제 (Delete component template)
DELETE 작업으로 클러스터에서 컴포넌트 템플릿을 제거해요.
중요한 고려 사항:
- 컴포넌트 템플릿을 삭제해도 템플릿으로 만든 기존 인덱스에는 영향이 없어요.
- 인덱스 템플릿이 현재 참조하고 있는 컴포넌트 템플릿은 삭제할 수 없어요.
- 이 작업은 되돌릴 수 없어요.
엔드포인트 (Endpoints)
DELETE _component_template/{component-template-name}
예제 요청 (Example request)
컴포넌트 템플릿 존재 여부 확인 (Check whether a component template exists)
HEAD 작업으로 내용을 조회하지 않고 컴포넌트 템플릿이 존재하는지 확인해요. 이 작업은 응답 본문 없이 HTTP 상태 코드와 헤더만 반환해요.
엔드포인트 (Endpoints)
HEAD _component_template/{component-template-name}
예제 요청 (Example request)
응답 코드 (Response codes)
- 200: 컴포넌트 템플릿이 존재해요.
- 404: 컴포넌트 템플릿이 존재하지 않아요.
필요한 권한 (Required permissions)
Security plugin을 사용한다면 적절한 권한이 있는지 확인하세요. 이 API에 필요한 권한은 다음과 같아요.
cluster:admin/component_template/get: 컴포넌트 템플릿 조회에 필요해요.cluster:admin/component_template/put: 컴포넌트 템플릿 생성 또는 업데이트에 필요해요.cluster:admin/component_template/delete: 컴포넌트 템플릿 삭제에 필요해요.