# Conexão com uma API REST
O AWS Glue permite que você configure um AWS Glue ConnectionType que pode ser usado para conectar o AWS Glue a qualquer fonte de dados baseada na API REST. Isso pode ser usado como fonte de dados nos seus trabalhos de ETL. Esses trabalhos podem ser executados para transferir dados entre a fonte de dados baseada na API REST e os serviços da AWS ou outras aplicações compatíveis.
**Topics**
+ [Suporte do AWS Glue para API REST](rest-api-support.md)
+ [Políticas que contêm as operações de API para registrar os tipos de conexão e criar/usar as conexões](rest-api-configuring-iam-permissions.md)
+ [Configuração do ConnectionType da API REST](rest-api-configuring.md)
+ [Configuração de uma conexão da API REST](rest-api-configuring-connections.md)
+ [Tutorial: criação de um ConnectionType e uma conexão da API REST](rest-api-example.md)
+ [Limitações](rest-api-limitations.md)
# Suporte do AWS Glue para API REST
AWS Glue oferece suporte para API REST da seguinte forma:
**Compatível como fonte?**
Sim. Você pode usar os trabalhos de ETL do AWS Glue para consultar dados de uma fonte de dados baseada na API REST.
**Compatível como destino?**
Não.
# Políticas que contêm as operações de API para registrar os tipos de conexão e criar/usar as conexões
O exemplo de política do IAM a seguir descreve as permissões necessárias para registrar, criar, gerenciar e usar as conexões da API REST com trabalhos de ETL do AWS Glue. Se você estiver criando um novo perfil, crie uma política que contenha o seguinte:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"glue:RegisterConnectionType",
"glue:ListConnectionTypes",
"glue:DescribeConnectionType",
"glue:CreateConnection",
"glue:RefreshOAuth2Tokens",
"glue:ListEntities",
"glue:DescribeEntity"
],
"Resource": "*"
}
]
}
```
É possível usar as seguintes políticas do IAM para permitir acesso:
+ [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole) – Concede acesso a recursos que vários processos do AWS Glue exigem para fazer a execução em seu nome. Esses recursos incluem o AWS Glue, Amazon S3, IAM, CloudWatch Logs e Amazon EC2. Se você seguir a convenção de nomenclatura para os recursos especificados nesta política, os processos do AWS Glue terão as permissões necessárias. Esta política geralmente é anexada a funções especificadas durante a definição de crawlers, trabalhos e endpoints de desenvolvimento.
+ [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess): concede acesso total aos recursos do AWS Glue quando uma identidade à qual a política está anexada usa o Console de Gerenciamento da AWS. Se você seguir a convenção de nomenclatura para os recursos especificados nesta política, os usuários poderão acessar todos os recursos do console. Esta política geralmente é anexada aos usuários do console do AWS Glue.
Se você fornecer opções de rede ao criar uma conexão com a API REST, as seguintes ações também deverão ser incluídas no perfil do IAM:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue",
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteNetworkInterface"
],
"Resource": "*"
}
]
}
```
# Configuração do ConnectionType da API REST
Antes de poder usar o AWS Glue para transferir dados da fonte de dados baseada na API REST, você precisa atender aos seguintes requisitos:
## Requisitos mínimos
São requisitos mínimos:
+ Um tipo de conexão da API REST do AWS Glue já foi configurado e registrado. Consulte [Conexão às APIs REST](https://docs.aws.amazon.com/glue/latest/dg/rest-api-connections.html).
+ Se estiver usando as credenciais de cliente, o código de autorização ou JWT do OAuth2, configure a aplicação cliente adequadamente.
Se você atender a esses requisitos, poderá conectar o AWS Glue à sua fonte de dados baseada na API REST. Normalmente, nenhuma configuração adicional é necessária em relação à API REST.
# Configuração de uma conexão da API REST
Para configurar um conector da API REST do AWS Glue, é preciso configurar um tipo de conexão ao AWS Glue. Esse tipo de conexão contém detalhes sobre as propriedades de como a fonte de dados REST opera e interpreta autenticação, solicitações, respostas, paginação, validações e entidades/metadados. Para obter uma lista abrangente das propriedades necessárias para um tipo de conexão REST do AWS Glue, consulte a API [RegisterConnectionType](https://docs.aws.amazon.com/glue/latest/webapi/API_DescribeConnectionType.html) e as etapas para [conexão às APIs REST](https://docs.aws.amazon.com/glue/latest/dg/rest-api-connections.html).
Para a criação do conector da API REST, a política a seguir é necessária para permitir ações relevantes:
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"glue:RegisterConnectionType",
"glue:ListConnectionTypes",
"glue:DescribeConnectionType",
"glue:CreateConnection",
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue",
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteNetworkInterface"
],
"Resource": "*"
}
]
}
```
# Tutorial: criação de um ConnectionType e uma conexão da API REST
**Conexão à API REST Foo**
Criaremos um ConnectionType da API REST do AWS Glue e uma conexão correspondente do AWS Glue para a API REST Foo. Essa API tem as seguintes propriedades (que podem ser consultadas na documentação da API REST).
+ **URL da instância**: https://foo.cloud.com/rest/v1.
+ **Tipo de autenticação**: OAuth2 (Credenciais do cliente).
+ **Método REST**: GET.
+ **Tipo de paginação**: offset com as propriedades “limite” e “offset” colocadas no parâmetro de consulta da solicitação.
+ **Entidades compatíveis**:
+ **Bar**: caminho relativo [/bar.json].
+ **Baz**: caminho relativo [/baz.json].
Após obtermos todos os detalhes, podemos começar a criar a conexão do AWS Glue com a API REST Foo.
**Para criar uma conexão com a API REST**:
1. Crie um tipo de conexão API REST no AWS Glue chamando a API RegisterConnectionType usando API, CLI ou SDK da AWS. Isso criará um novo recurso ConnectionType no AWS Glue.
```
{
"ConnectionType": "REST-FOO-CONNECTOR",
"IntegrationType": "REST",
"Description": "AWS Glue Connection Type for the FOO REST API",
"ConnectionProperties": {
"Url": {
"Name": "Url",
"Required": true,
"DefaultValue": "https://foo.cloud.com/rest/v1",
"PropertyType": "USER_INPUT"
}
},
"ConnectorAuthenticationConfiguration": {
"AuthenticationTypes": ["OAUTH2"],
"OAuth2Properties": {
"OAuth2GrantType": "CLIENT_CREDENTIALS"
}
},
"RestConfiguration": {
"GlobalSourceConfiguration": {
"RequestMethod": "GET",
"ResponseConfiguration": {
"ResultPath": "$.result",
"ErrorPath": "$.error.message"
},
"PaginationConfiguration": {
"OffsetConfiguration": {
"OffsetParameter": {
"Key": "offset",
"PropertyLocation": "QUERY_PARAM"
},
"LimitParameter": {
"Key": "limit",
"PropertyLocation": "QUERY_PARAM",
"DefaultValue": "50"
}
}
}
},
"ValidationEndpointConfiguration": {
"RequestMethod": "GET",
"RequestPath": "/bar.json?offset=1&limit=10"
},
"EntityConfigurations": {
"bar": {
"SourceConfiguration": {
"RequestMethod": "GET",
"RequestPath": "/bar.json",
"ResponseConfiguration": {
"ResultPath": "$.result",
"ErrorPath": "$.error.message"
}
},
"Schema": {
"name": {
"Name": "name",
"FieldDataType": "STRING"
},
"description": {
"Name": "description",
"FieldDataType": "STRING"
},
"id": {
"Name": "id",
"FieldDataType": "STRING"
},
"status": {
"Name": "status",
"FieldDataType": "STRING"
}
}
}
}
}
}
```
1. No AWS Secrets Manager, crie um segredo. O segredo deve conter o segredo do consumidor da aplicação conectada com `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` como chave.
**nota**
É preciso criar um segredo por conexão no AWS Glue
1. Crie a conexão do AWS Glue chamando a API CreateConnection usando a API, a CLI ou o SDK da AWS.
1. Faça referência ao nome do tipo de conexão REST da Etapa 1 como “ConnectionType”.
1. Forneça o InstanceUrl e quaisquer outras ConnectionProperties definidas durante o processo de registro do ConnectionType do AWS Glue.
1. Escolha entre os tipos de autenticação configurados. A API REST Foo usa OAuth2 com o tipo de concessão ClientCredentials.
1. Forneça **SecretArn** e outras **AuthenticationProperties** configuradas. Por exemplo, configuramos `OAUTH2` como AuthenticationType, então definiremos o “OAuth2Properties” no CreateConnectionInput. Isso exigirá propriedades como “OAuth2GrantType”, “TokenUrl” e “OAuth2ClientApplication”.
1. Faça a solicitação CreateConnection que criará a conexão do AWS Glue.
```
{
"ConnectionInput": {
"Name": "ConnectionFooREST",
"ConnectionType": "REST-FOO-CONNECTOR",
"ConnectionProperties": {},
"ValidateCredentials": true,
"AuthenticationConfiguration": {
"AuthenticationType": "OAUTH2",
"SecretArn": "arn:aws:secretsmanager:::secret:",
"OAuth2Properties": {
"OAuth2GrantType": "CLIENT_CREDENTIALS",
"TokenUrl": "https://foo.cloud.com/oauth/token",
"OAuth2ClientApplication": {
"UserManagedClientApplicationClientId": "your-managed-client-id"
}
}
}
}
}
```
# Limitações
Estas são as limitações do conector da API REST
+ O conector da API REST só está disponível por meio da API, CLI ou SDK da AWS. Não é possível configurar conectores REST por meio do console.
+ O REST do AWS Glue ConnectionType só pode ser configurado para LER dados da fonte de dados baseada na API REST. A conexão só pode ser usada como FONTE em trabalhos de ETL do AWS Glue.
+ Não há suporte para filtragem nem para particionamento.
+ Não há suporte para a seleção de campos.