Ler uma API REST

Depois de registrar um ConnectionType API REST e criar uma conexão do AWS Glue, é possível ler os dados da API REST nos trabalhos de ETL do AWS Glue. Com essa conexão, você pode processar dados externos da API REST junto com outras fontes no mesmo trabalho. Você precisa do nome da conexão e do nome da entidade para ler os dados.

O seguinte exemplo mostra como ler uma fonte de dados API REST usando 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"
    }
)

Como filtrar dados

Você pode enviar predicados de filtro para a API REST de origem para reduzir a quantidade de dados transferidos. O conector da API REST é compatível com dois modos de filtro:

Para aplicar um predicado de filtro no trabalho de ETL do AWS Glue, use a opção de conexão 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\""
    }
)

Propriedades de FilterConfiguration

Configure o comportamento de filtragem no registro de ConnectionType usando o objeto FilterConfiguration. A seguinte tabela descreve as propriedades disponíveis:

Propriedades de FilterStringConfiguration

A seguinte tabela descreve as propriedades do modo FILTER_STRING:

Propriedades de BetweenConfiguration

A seguinte tabela descreve as propriedades de tratamento de BETWEEN:

Operadores compatíveis

Os seguintes operadores são compatíveis com predicados de filtro: EQUAL_TO, GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL_TO, LESS_THAN_OR_EQUAL_TO, NOT_EQUAL_TO, CONTAINS, BETWEEN, AND, OR.

Substituições no nível do campo

Você pode configurar o comportamento do filtro por campo usando FilterOverrides na definição do esquema. As seguintes propriedades de substituição estão disponíveis:

Exemplo: modo QUERY_PARAMS

O exemplo a seguir mostra uma FilterConfiguration para uma API REST que usa parâmetros de consulta com notação de colchetes para operadores e timestamps de época em valores de data:

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

Com essa configuração, um filtro de entrada created >= 2024-01-01 AND created <= 2024-06-01 gera a string de consulta de URL: ?created[gte]=1704067200&created[lte]=1717200000

Exemplo: modo FILTER_STRING

O exemplo a seguir mostra uma FilterConfiguration para uma API REST que usa um único parâmetro de string de filtro com operadores completados com espaços:

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

Com essa configuração, um filtro de entrada status = "ACTIVE" AND lastUpdated > 2024-01-01T00:00:00.000Z gera a string de consulta de URL: ?search=status eq "ACTIVE" and lastUpdated gt "2024-01-01T00:00:00.000Z"

Consultas de particionamento

Você pode dividir as leituras de dados em partições paralelas entre operadores Spark para melhorar o throughput. O conector da API REST é compatível com particionamento baseado no campo, que divide os dados em intervalos com base em um campo especificado.

SparkParâmetros de trabalho do

As seguintes opções de conexão controlam o comportamento do particionamento:

Particionamento com base em campo

O particionamento baseado no campo divide os dados em intervalos com base em um campo especificado. O seguinte exemplo particiona os dados no 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"
    }
)

Com quatro partições no campo lastUpdated, o trabalho é distribuído da seguinte forma:

Configurar compatibilidade com partição em RegisterConnectionType

Para habilitar o particionamento baseado no campo, marque os campos como particionáveis na definição do esquema:

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

Os seguintes valores de FieldDataType são compatíveis com particionamento: