# Lectura desde una API de REST
<a name="rest-api-reading"></a>

 Tras registrar un valor para ConnectionType de la API de REST y crear una conexión de AWS Glue, puede leer los datos de la API de REST en sus trabajos de ETL de AWS Glue. Con esta conexión, puede procesar datos de la API de REST externa junto con otros orígenes en el mismo trabajo. Necesita el nombre de la conexión y el nombre de la entidad para leer los datos. 

En el siguiente ejemplo, se muestra cómo leer desde un origen de datos de la API de REST mediante Python:

```
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}}"
    }
)
```

## Filtrado de datos
<a name="rest-api-filtering"></a>

 Puede insertar predicados de filtro en la API de REST de origen para reducir la cantidad de datos transferidos. El conector de la API de REST admite dos modos de filtro: 
+ **QUERY\_PARAMS**: cada filtro se convierte en un parámetro de consulta de URL independiente. Por ejemplo: .: `?created[gte]=1704067200&created[lte]=1717200000`
+ **FILTER\_STRING**: todos los filtros se combinan en un único parámetro de consulta. Por ejemplo: .: `?search=status eq "ACTIVE" and lastUpdated gt "2024-01-01"`

 Para aplicar un predicado de filtro en su trabajo de ETL de AWS Glue, utilice la opción de conexión `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\""
    }
)
```

**Propiedades de FilterConfiguration**  
 Configure el comportamiento de filtrado en su registro de ConnectionType mediante el objeto `FilterConfiguration`. En la siguiente tabla se describen las propiedades disponibles: 


| Propiedad | Tipo | Descripción | 
| --- | --- | --- | 
| `FilterMode` | Cadena | Obligatorio. `QUERY_PARAMS` o `FILTER_STRING`. | 
| `OperatorMappings` | Asignación | Asigna los operadores lógicos a la sintaxis específica de la API. | 
| `DateTimeFormat` | Cadena | Patrón de formato DateTime o `EPOCH_SECONDS`/`EPOCH_MILLIS`. | 
| `StripQuotes` | Booleano | Especifica si se deben eliminar las comillas adyacentes de los valores de entrada. Valor predeterminado: `true`. | 
| `BetweenConfiguration` | Objeto | Configuración predeterminada de la gestión de BETWEEN. | 
| `FilterStringConfiguration` | Objeto | Configuración específica del modo `FILTER_STRING`. | 

**Propiedades de FilterStringConfiguration**  
En la siguiente tabla se describen las propiedades del modo `FILTER_STRING`:


| Propiedad | Tipo | Descripción | 
| --- | --- | --- | 
| `FilterStringKey` | Cadena | Obligatorio. Clave del parámetro de consulta (por ejemplo, “search” o “filter”). | 
| `QuoteStringValues` | Booleano | Especifica si se deben incluir los valores String y DateTime entre comillas. | 
| `QuoteCharacter` | Cadena | Carácter de comilla. Valor predeterminado: `"` | 

**Propiedades de BetweenConfiguration**  
En la siguiente tabla se describen las propiedades de gestión de BETWEEN:


| Propiedad | Mode | Descripción | 
| --- | --- | --- | 
| `LowBoundKey` | QUERY\_PARAMS | Plantilla de clave para el límite inferior. Admite el marcador de posición `{FIELD}`. | 
| `HighBoundKey` | QUERY\_PARAMS | Plantilla de clave para el límite superior. Omítalo para eliminar el límite superior. | 
| `Template` | FILTER\_STRING | Plantilla con los marcadores de posición `{FIELD}`, `{LOW}` y `{HIGH}`. | 

**Operadores admitidos**  
 Los predicados de filtro admiten los siguientes operadores: `EQUAL_TO`, `GREATER_THAN`, `LESS_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN_OR_EQUAL_TO`, `NOT_EQUAL_TO`, `CONTAINS`, `BETWEEN`, `AND`, `OR`. 

**Anulaciones de campos**  
 Puede configurar el comportamiento de los filtros de cada campo utilizando `FilterOverrides` en la definición del esquema. Están disponibles las siguientes propiedades de anulación: 
+ `FieldName`: anula el nombre de campo utilizado en la salida del filtro.
+ `OperatorMappings`: anulaciones de operadores de campos.
+ `BetweenConfiguration`: anulación de BETWEEN por campo.
+ `DateTimeFormat`: anulación del formato DateTime por campo.

**Ejemplo: modo QUERY\_PARAMS**  
 En el siguiente ejemplo se muestra `FilterConfiguration` para una API de REST que utiliza parámetros de consulta con notación entre corchetes para los operadores y marcas de tiempo de época para los valores de fecha: 

```
"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]"
    }
}
```

 Con esta configuración, un filtro de entrada `created >= 2024-01-01 AND created <= 2024-06-01` produce la cadena de consulta URL siguiente: `?created[gte]=1704067200&created[lte]=1717200000` 

**Ejemplo: modo FILTER\_STRING**  
 En el siguiente ejemplo se muestra `FilterConfiguration` para una API de REST que utiliza un único parámetro de cadena de filtro con operadores rellenados con espacios: 

```
"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": "\""
    }
}
```

 Con esta configuración, un filtro de entrada `status = "ACTIVE" AND lastUpdated > 2024-01-01T00:00:00.000Z` produce la cadena de consulta URL siguiente: `?search=status eq "ACTIVE" and lastUpdated gt "2024-01-01T00:00:00.000Z"` 

## Consultas de particionamiento
<a name="rest-api-partitioning"></a>

 Puede dividir las lecturas de datos en particiones paralelas entre trabajadores de Spark para mejorar el rendimiento. El conector de la API de REST admite la partición basada en campos, que divide los datos en intervalos en función de un campo específico. 

**SparkParámetros de los trabajos de**  
Las siguientes opciones de conexión controlan el comportamiento de la partición:
+ `PARTITION_FIELD`: campo en el que realizar la partición. Debe estar marcado con `IsPartitionable: true` en el esquema.
+ `LOWER_BOUND`: límite inferior inclusivo del intervalo de particiones.
+ `UPPER_BOUND`: límite superior del intervalo de particiones. Las particiones intermedias excluyen este valor. La última partición lo incluye.
+ `NUM_PARTITIONS`: número de particiones paralelas.

**Partición basada en campos**  
 La creación de particiones basada en campos divide los datos en intervalos en función de un campo específico. En el siguiente ejemplo se dividen los datos en el campo `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"
    }
)
```

Con 4 particiones en el campo `lastUpdated`, el trabajo se distribuye de la siguiente manera:
+ Trabajador 1: `lastUpdated >= "2024-01-01" AND lastUpdated < "2024-04-01"`
+ Trabajador 2: `lastUpdated >= "2024-04-01" AND lastUpdated < "2024-07-01"`
+ Trabajador 3: `lastUpdated >= "2024-07-01" AND lastUpdated < "2024-10-01"`
+ Trabajador 4: `lastUpdated >= "2024-10-01" AND lastUpdated <= "2024-12-31"`

**Configuración de la compatibilidad de particiones en RegisterConnectionType**  
 Para habilitar la creación de particiones basada en campos, marque los campos como particionables en la definición del esquema: 

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

Se admiten los siguientes valores de `FieldDataType` para la creación de particiones:
+ `TIMESTAMP`: creación de particiones según DateTime. Divide el intervalo en periodos de tiempo.
+ `INTEGER`: creación de particiones según enteros. Divide el intervalo en periodos numéricos.

**nota**  
 El conector combina filtros de partición con filtros de usuario mediante AND. Si el filtro contiene una cláusula LIMIT, el conector omite la creación de particiones. Si se produce un error en la creación de particiones, el conector recurre a una sola partición y el trabajo se completa igualmente.