공통 REST 파라미터
공통 REST 파라미터 (Common REST parameters)
모든 OpenSearch REST 작업에서 공통으로 지원하는 파라미터들이 있어요. API를 사용하다 보면 출력 단위를 사람이 읽기 좋게 바꾸고 싶거나, 응답을 예쁘게 정렬하고 싶을 때가 생기는데요. 이런 공통 파라미터를 알면 여러 API에서 일관되게 활용할 수 있어요.
출처: 문서
본문
1.0에서 도입
모든 REST 작업에서 다음 파라미터들을 지원해요.
사람이 읽기 좋은 출력 (Human-readable output)
출력 단위를 사람이 읽기 좋은 값(예: 1시간은 1h, 1,024 바이트는 1kb)으로 바꾸려면 요청 URL에 ?human=true를 추가해요.
예시 요청
다음 요청은 응답 값을 사람이 읽기 좋은 형식으로 요구해요.
GET {index_name}/_search?human=true
예쁜 결과 (Pretty result)
JSON 응답을 읽기 좋은 형식으로 받으려면 요청 URL에 ?pretty=true를 추가해요.
예시 요청
다음 요청은 응답을 pretty JSON 형식으로 표시하도록 요구해요.
GET {index_name}/_search?pretty=true
콘텐츠 유형 (Content type)
요청 본문의 콘텐츠 유형을 지정하려면 요청 헤더에 Content-Type 키 이름을 사용해요. 대부분의 작업이 JSON, YAML, CBOR 형식을 지원해요.
예시 요청
다음 요청은 요청 본문에 JSON 형식을 지정해요.
curl -H "Content-type: application/json" -XGET localhost:9200/_scripts/<template_name>
쿼리 문자열의 요청 본문 (Request body in query string)
POST가 아닌 요청에 클라이언트 라이브러리가 요청 본문을 받아들이지 않는다면, source 쿼리 문자열 파라미터로 요청 본문을 전달해요. 또한 application/json 같은 지원되는 미디어 유형으로 source_content_type 파라미터도 지정해야 해요.
예시 요청
다음 요청은 shakespeare 인덱스의 문서 중 특정 필드와 값을 검색해요.
GET shakespeare/search?source={"query":{"exists":{"field":"speaker"}}}&source_content_type=application/json
스택 트레이스 (Stack traces)
예외가 발생할 때 응답에 오류 스택 트레이스를 포함하려면 요청 URL에 error_trace=true를 추가해요.
예시 요청
다음 요청은 응답이 예외로 인해 발생한 오류를 반환하도록 error_trace를 true로 설정해요.
GET {index_name}/_search?error_trace=true
필터링된 응답 (Filtered responses)
응답 크기를 줄이려면 filter_path 파라미터로 반환되는 필드를 필터링해요. 이 파라미터는 쉼표로 구분된 필터 목록을 받아요. 어떤 필드나 필드 이름의 일부를 매칭하는 와일드카드도 지원하고, -로 특정 필드를 제외할 수도 있어요.
예시 요청
다음 요청은 응답에 반환되는 필드를 제한하는 필터를 지정해요.
GET _search?filter_path={field_name}.*,-{field_name}
단위 (Units)
OpenSearch API는 다음 단위들을 지원해요.
시간 단위 (Time units)
지원되는 모든 시간 단위는 다음과 같아요.
| Units | Specify as |
|---|---|
| Days | d |
| Hours | h |
| Minutes | m |
| Seconds | s |
| Milliseconds | ms |
| Microseconds | micros |
| Nanoseconds | nanos |
거리 단위 (Distance units)
지원되는 모든 거리 단위는 다음과 같아요.
| Units | Specify as |
|---|---|
| Miles | mi or miles |
| Yards | yd or yards |
| Feet | ft or feet |
| Inches | in or inch |
| Kilometers | km or kilometers |
| Meters | m or meters |
| Centimeters | cm or centimeters |
| Millimeters | mm or millimeters |
| Nautical miles | NM, nmi, or nauticalmiles |
Cron 표현식 (Cron expressions)
여러 OpenSearch 기능은 Index State Management, alerting, anomaly detection을 포함해 스케줄링에 cron 표현식을 받아요. OpenSearch는 표준 UNIX cron 문법을 사용하며, 모든 스케줄 시간은 UTC 기준이에요.
cron 표현식의 형식은 다음과 같아요.
<minutes> <hours> <day_of_month> <month> <day_of_week>
각 필드의 설명은 다음 표와 같아요.
| Field | Values | Special characters |
|---|---|---|
| Minutes | 0–59 | , - * / |
| Hours | 0–23 | , - * / |
| Day of month | 1–31 | , - * / |
| Month | 1–12 or JAN–DEC (case-insensitive) | , - * / |
| Day of week | 0–7 (0 and 7 are both Sunday) or SUN–SAT (case-insensitive) | , - * / |
특수 문자의 설명은 다음 표와 같아요.
| Character | Description |
|---|---|
| * | 모든 값을 매칭해요. 예를 들어 hours 필드의 *는 매시간을 의미해요. |
| - | 범위를 나타내요. 예를 들어 hours의 9-17은 UTC 9:00부터 17:00까지 매시간을 의미해요. |
| , | 여러 값을 나타내요. 예를 들어 day_of_week의 1,3,5는 월요일, 수요일, 금요일을 의미해요. |
| / | 증가분을 나타내요. 예를 들어 minutes의 0/15는 0분부터 15분마다를 의미해요. |
날짜를 지정하는 필드는 day_of_month와 day_of_week 두 가지예요. 두 필드 모두에 와일드카드가 아닌 값을 쓰면, 스케줄은 두 필드 중 하나라도 시간과 일치할 때마다 실행돼요. 예를 들어 15 2 1,15 * 1은 매월 1일, 매월 15일, 그리고 매주 월요일의 UTC 오전 2:15에 실행돼요. 단일 날짜로 스케줄을 잡으려면 한 필드를 설정하고 다른 필드는 *로 남겨 두면 돼요.
예시
| Expression | Description |
|---|---|
| 5 9 * * * | 매일 UTC 오전 9:05 |
| 0/15 9 * * * | UTC 오전 9:00부터 9:45까지 15분마다 |
| 5 9 * * 1-5 | 월요일부터 금요일까지 UTC 오전 9:05 |
| 5 9 * * MON-FRI | 월요일부터 금요일까지 UTC 오전 9:05 (요일 이름 사용) |
| 45 13 1-31/2 * * | 격일로 UTC 오후 1:45 |
| 0/10 * * * 6-7 | 토요일과 일요일 10분마다 |
| 0 0-23/3 1 1-12/2 * | 격월의 첫째 날 3시간마다 |
X-Opaque-Id 헤더
X-Opaque-Id 헤더로 어떤 요청에든 불투명(opaque) 식별자를 지정할 수 있어요. 이 식별자는 작업을 추적하고 서버 측 로그에서 deprecated 경고를 중복 제거하는 데 사용돼요. 이 식별자는 OpenSearch 클러스터에 요청을 보내는 호출자를 구분하는 데도 쓰여요. 요청마다 고유한 값을 지정하지 마세요.
예시 요청
다음 요청은 요청에 opaque ID를 추가해요.
curl -H "X-Opaque-Id: my-curl-client-1" -XGET localhost:9200/_tasks
X-Request-Id 헤더
X-Request-Id 헤더로 검색 요청에 고유 식별자를 지정할 수 있어요. 이 식별자는 개별 검색 요청을 추적하는 데 사용되며, slow log 같은 로그에서 문제 해결과 분석을 위해 참조할 수 있어요. 값은 32자리 16진수 문자열이어야 해요.
예시 요청
다음 요청은 검색 요청에 request ID를 추가해요.
curl -X GET "http://localhost:9200/_search" \
-H "Content-Type: application/json" \
-H "X-Request-Id: 19d538d7c42d09240be001d1e4ff6201" \
-d '{"query": {"match_all": {}}}'
더 알아보기 (Learn more)
filter_path,human,pretty파라미터는 대부분의 검색·문서 API에서 그대로 활용할 수 있어요.- cron 표현식은 ISM, alerting, anomaly detection 등 스케줄링 기능에서 공통으로 사용돼요.