# REST API에서 읽기
<a name="rest-api-reading"></a>

 REST API ConnectionType을 등록하고 AWS Glue 연결을 생성한 후 AWS Glue ETL 작업에서 REST API로부터 데이터를 읽을 수 있습니다. 이 연결을 사용하면 동일한 작업에서 다른 소스와 함께 외부 REST API 데이터를 처리할 수 있습니다. 데이터를 읽으려면 연결 이름과 엔터티 이름이 필요합니다.

다음 예제에서는 Python을 사용하여 REST API 데이터 소스에서 읽는 방법을 보여줍니다.

```
rest_read = glueContext.create_dynamic_frame.from_options(
    connection_type="rest",
    connection_options={
        "connectionName": "{{connection-name}}",
        "ENTITY_NAME": "{{entity-name}}",
        "CONNECTION_TYPE": "{{REST-connection-type}}"
    }
)
```

## 데이터 필터링
<a name="rest-api-filtering"></a>

 필터 조건자를 소스 REST API로 푸시다운하여 전송되는 데이터의 양을 줄일 수 있습니다. REST API 커넥터는 두 가지 필터 모드를 지원합니다.
+ **QUERY\_PARAMS** – 각 필터가 별도의 URL 쿼리 파라미터가 됩니다. 예: `?created[gte]=1704067200&created[lte]=1717200000`
+ **FILTER\_STRING** – 모든 필터가 단일 쿼리 파라미터로 결합됩니다. 예: `?search=status eq "ACTIVE" and lastUpdated gt "2024-01-01"`

 AWS Glue ETL 작업에 필터 조건자를 적용하려면 `FILTER_PREDICATE` 연결 옵션을 사용합니다.

```
rest_read = glueContext.create_dynamic_frame.from_options(
    connection_type="rest",
    connection_options={
        "connectionName": "{{connection-name}}",
        "ENTITY_NAME": "{{entity-name}}",
        "CONNECTION_TYPE": "{{REST-connection-type}}",
        "FILTER_PREDICATE": "status = \"ACTIVE\" AND lastUpdated >= \"2024-01-01T00:00:00.000Z\""
    }
)
```

**FilterConfiguration 속성**  
 `FilterConfiguration` 객체를 사용하여 ConnectionType 등록에서 필터링 동작을 구성합니다. 다음 표에서는 사용 가능한 속성을 설명합니다.


| 속성 | 유형 | 설명 | 
| --- | --- | --- | 
| `FilterMode` | 문자열 | 필수 사항. `QUERY_PARAMS` 또는 `FILTER_STRING`. | 
| `OperatorMappings` | 맵 | 논리적 연산자를 API별 구문에 매핑합니다. | 
| `DateTimeFormat` | 문자열 | DateTime 형식 패턴 또는 `EPOCH_SECONDS`/`EPOCH_MILLIS`. | 
| `StripQuotes` | 부울 | 입력 값에서 묶는 따옴표를 제거할지 여부를 지정합니다. 기본값: `true`. | 
| `BetweenConfiguration` | 객체 | 기본 BETWEEN 처리 구성입니다. | 
| `FilterStringConfiguration` | 객체 | `FILTER_STRING` 모드별 설정입니다. | 

**FilterStringConfiguration 속성**  
다음 표에서는 `FILTER_STRING` 모드의 속성을 설명합니다.


| 속성 | 유형 | 설명 | 
| --- | --- | --- | 
| `FilterStringKey` | 문자열 | 필수입니다. 쿼리 파라미터 키(예: 'search' 또는 'filter')입니다. | 
| `QuoteStringValues` | 부울 | 문자열 및 DateTime 값을 따옴표로 묶을지 여부를 지정합니다. | 
| `QuoteCharacter` | 문자열 | 인용 문자입니다. 기본값: `"` | 

**BetweenConfiguration 속성**  
다음 표에서는 BETWEEN 처리 속성을 설명합니다.


| 속성 | Mode | 설명 | 
| --- | --- | --- | 
| `LowBoundKey` | QUERY\_PARAMS | 하한에 대한 키 템플릿입니다. `{FIELD}` 자리 표시자를 지원합니다. | 
| `HighBoundKey` | QUERY\_PARAMS | 상한에 대한 키 템플릿입니다. 상한을 삭제하려면 생략합니다. | 
| `Template` | FILTER\_STRING | `{FIELD}`, `{LOW}`, `{HIGH}` 자리 표시자가 있는 템플릿입니다. | 

**지원되는 연산자**  
 필터 조건자에서 다음 연산자가 지원됩니다. `EQUAL_TO`, `GREATER_THAN`, `LESS_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN_OR_EQUAL_TO`, `NOT_EQUAL_TO`, `CONTAINS`, `BETWEEN`, `AND`, `OR`.

**필드 수준 재정의**  
 스키마 정의에서 `FilterOverrides`를 사용하여 필드별 필터 동작을 구성할 수 있습니다. 다음 재정의 속성들을 사용할 수 있습니다.
+ `FieldName` – 필터 출력에 사용되는 필드 이름을 재정의합니다.
+ `OperatorMappings` – 필드 수준 연산자 재정의.
+ `BetweenConfiguration` – 필드별 BETWEEN 재정의.
+ `DateTimeFormat` – 필드별 DateTime 형식 재정의.

**예: QUERY\_PARAMS 모드**  
 다음 예제에서는 연산자에 대한 대괄호 표기법, 날짜 값에 대한 에포크 타임스탬프와 함께 쿼리 파라미터를 사용하는 REST API의 `FilterConfiguration`을 보여줍니다.

```
"FilterConfiguration": {
    "FilterMode": "QUERY_PARAMS",
    "OperatorMappings": {
        "EQUAL_TO": "{FIELD}",
        "GREATER_THAN_OR_EQUAL_TO": "{FIELD}[gte]",
        "LESS_THAN_OR_EQUAL_TO": "{FIELD}[lte]"
    },
    "DateTimeFormat": "EPOCH_SECONDS",
    "BetweenConfiguration": {
        "LowBoundKey": "{FIELD}[gte]",
        "HighBoundKey": "{FIELD}[lte]"
    }
}
```

 이 구성을 사용하면 `created >= 2024-01-01 AND created <= 2024-06-01`의 입력 필터가 URL 쿼리 문자열을 생성합니다. `?created[gte]=1704067200&created[lte]=1717200000` 

**예: FILTER\_STRING 모드**  
 다음 예제에서는 공백으로 패딩된 연산자와 함께 단일 필터 문자열 파라미터를 사용하는 REST API의 `FilterConfiguration`를 보여줍니다.

```
"FilterConfiguration": {
    "FilterMode": "FILTER_STRING",
    "OperatorMappings": {
        "EQUAL_TO": " eq ",
        "GREATER_THAN": " gt ",
        "GREATER_THAN_OR_EQUAL_TO": " ge ",
        "LESS_THAN": " lt ",
        "AND": " and ",
        "OR": " or "
    },
    "DateTimeFormat": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "BetweenConfiguration": {
        "Template": "{FIELD} ge {LOW} and {FIELD} le {HIGH}"
    },
    "FilterStringConfiguration": {
        "FilterStringKey": "search",
        "QuoteStringValues": true,
        "QuoteCharacter": "\""
    }
}
```

 이 구성을 사용하면 `status = "ACTIVE" AND lastUpdated > 2024-01-01T00:00:00.000Z`의 입력 필터가 URL 쿼리 문자열을 생성합니다. `?search=status eq "ACTIVE" and lastUpdated gt "2024-01-01T00:00:00.000Z"` 

## 쿼리 파티셔닝
<a name="rest-api-partitioning"></a>

 데이터 읽기를 Spark 워커 간에 병렬 파티션으로 분할하여 처리량을 개선할 수 있습니다. REST API 커넥터는 지정된 필드를 기반으로 데이터를 범위로 분할하는 필드 기반 파티셔닝을 지원합니다.

**Spark 작업 파라미터**  
다음 연결 옵션은 파티셔닝 동작을 제어합니다.
+ `PARTITION_FIELD` – 분할할 필드입니다. 스키마에서 `IsPartitionable: true`로 표시되어야 합니다.
+ `LOWER_BOUND` – 파티션 범위의 하한(포함)입니다.
+ `UPPER_BOUND` – 파티션 범위의 상한입니다. 중간 파티션은 이 값을 제외합니다. 마지막 파티션은 이 값을 포함합니다.
+ `NUM_PARTITIONS` – 병렬 파티션 수입니다.

**필드 기반 분할**  
 필드 기반 파티셔닝은 지정된 필드를 기반으로 데이터를 범위로 분할합니다. 다음 예제에서는 `lastUpdated` 필드의 데이터를 분할합니다.

```
rest_read = glueContext.create_dynamic_frame.from_options(
    connection_type="rest",
    connection_options={
        "connectionName": "{{connection-name}}",
        "ENTITY_NAME": "{{entity-name}}",
        "CONNECTION_TYPE": "{{REST-connection-type}}",
        "PARTITION_FIELD": "lastUpdated",
        "LOWER_BOUND": "2024-01-01T00:00:00.000Z",
        "UPPER_BOUND": "2024-12-31T00:00:00.000Z",
        "NUM_PARTITIONS": "4"
    }
)
```

`lastUpdated` 필드에 파티션이 4개인 경우 작업은 다음과 같이 분배됩니다.
+ 워커 1: `lastUpdated >= "2024-01-01" AND lastUpdated < "2024-04-01"`
+ 워커 2: `lastUpdated >= "2024-04-01" AND lastUpdated < "2024-07-01"`
+ 워커 3: `lastUpdated >= "2024-07-01" AND lastUpdated < "2024-10-01"`
+ 워커 4: `lastUpdated >= "2024-10-01" AND lastUpdated <= "2024-12-31"`

**RegisterConnectionType에서 파티션 지원 구성**  
 필드 기반 파티셔닝을 활성화하려면 스키마 정의에서 필드를 파티션 가능으로 표시합니다.

```
"Schema": {
    "lastUpdated": {
        "FieldDataType": "TIMESTAMP",
        "IsPartitionable": true
    }
}
```

파티셔닝에 대해 다음 `FieldDataType` 값이 지원됩니다.
+ `TIMESTAMP` – DateTime 파티셔닝. 범위를 시간 창으로 분할합니다.
+ `INTEGER` – 정수 파티셔닝. 범위를 숫자 창으로 분할합니다.

**참고**  
 커넥터는 AND를 사용하여 파티션 필터를 사용자 필터와 결합합니다. 필터에 LIMIT 절이 포함된 경우 커넥터는 파티셔닝을 건너맙니다. 파티션 생성에 실패하면 커넥터가 단일 파티션으로 폴백되며 작업은 계속 완료됩니다.