Tutorial: Criar uma API REST como um proxy do Amazon S3 no API Gateway

Como exemplo para mostrar o uso de uma API REST no API Gateway para o proxy do Amazon S3, esta seção descreve como criar e configurar uma API REST para expor as seguintes operações do Amazon S3:

• Expor GET no recurso raiz da API para listar todos os buckets do Amazon S3 de um autor da chamada.

• Expor GET em um recurso Folder para visualizar uma lista de todos os objetos no bucket do Amazon S3.

• Expor GET em um recurso Folder/Item para visualizar ou baixar um objeto de um bucket do Amazon S3.

É recomendável importar a API de exemplo como um proxy do Amazon S3, conforme mostrado em Definições do OpenAPI da API de amostra como um proxy do Amazon S3. Este exemplo contém mais métodos expostos. Para obter instruções sobre como importar uma API usando a definição do OpenAPI, consulte Configurar uma API REST usando OpenAPI.

nota

Para integrar sua API do API Gateway ao Amazon S3, é necessário escolher uma região onde os serviços API Gateway e Amazon S3 estejam disponíveis. Para obter a disponibilidade da região, consulte Endpoints e cotas do Amazon API Gateway.

Tópicos

• Configurar permissões do IAM para a API invocar ações do Amazon S3
• Criar recursos de API para representar recursos do Amazon S3
• Expor um método de API para listar os buckets do Amazon S3 do autor da chamada
• Expor métodos de API para acessar um bucket do Amazon S3
• Expor métodos de API para acessar um objeto do Amazon S3 em um bucket
• Definições do OpenAPI da API de amostra como um proxy do Amazon S3
• Chamar a API usando um cliente de API REST

Configurar permissões do IAM para a API invocar ações do Amazon S3

Para permitir que a API invoque ações do Amazon S3, é necessário que as políticas do IAM apropriadas sejam associadas a um perfil do IAM.

Como criar o perfil de execução do proxy de serviço da AWS

1. Faça login no AWS Management Console e abra o console do IAM em https://console.aws.amazon.com/iam/.

2. Escolha Funções.

3. Selecione Criar perfil.

4. Selecione Serviço da AWS em Selecionar tipo de entidade confiável, selecione API Gateway e Permite que o API Gateway envie logs ao CloudWatch Logs.

5. Selecione Próximo e, depois, Próximo.

6. Em Role name (Nome da função), digite APIGatewayS3ProxyPolicy e escolha Create role (Criar função).

7. Na lista Roles (Funções), escolha a função que você acaba de criar. Talvez seja necessário rolar a página ou usar a barra de pesquisa para encontrar o perfil.

8. Para a função escolhida, selecione a guia Adicionar permissões.

9. Selecione Anexar políticas na lista suspensa.

10. Na barra de pesquisa, insira AmazonS3FullAccess e escolha Adicionar permissões.

    nota

    Este tutorial usa uma política gerenciada em prol da simplicidade. Como prática recomendada, você deve criar sua própria política do IAM para conceder as permissões mínimas necessárias.

11. Anote o ARN do perfil recém-criado, você o usará posteriormente.

Criar recursos de API para representar recursos do Amazon S3

Usaremos o recurso raiz da API (/) como o contêiner de buckets do Amazon S3 de um autor da chamada autenticado. Também criaremos recursos Folder e Item para representar um bucket do Amazon S3 específico e um determinado objeto do Amazon S3, respectivamente. O nome da pasta e a chave do objeto serão especificados, no formato de parâmetros de caminho como parte de uma URL de solicitação, pelo autor da chamada.

nota

Ao acessar objetos cuja chave de objeto inclua / ou qualquer outro caractere especial, o caractere deverá ser codificado por URL. Por exemplo, test/test.txt deve ser codificado para test%2Ftest.txt.

Como criar um recurso de API que expõe os recursos de serviços do Amazon S3

1. Na mesma em Região da AWS onde você criou o bucket do Amazon S3, crie uma API chamada MyS3. O recurso raiz dessa API (/) representa o serviço Amazon S3. Nesta etapa, você vai criar dois recursos adicionais/{folder} e/{item}.

2. Selecione o recurso raiz da API e, depois, e selecione Criar recurso.

3. Mantenha Recurso proxy desativado.

4. Em Caminho do recurso, selecione /.

5. Em Resource Name (Nome do recurso), insira {folder}.

6. Mantenha CORS (Compartilhamento de recursos de origem cruzada) desmarcado.

7. Selecione Criar recurso.

8. Selecione o recurso /{folder} e, depois, Criar recurso.

9. Use as etapas anteriores para criar um recurso secundário de /{folder} chamado {item}.

   A API final deverá ser semelhante à seguinte:

   

Expor um método de API para listar os buckets do Amazon S3 do autor da chamada

Obter a lista de buckets do Amazon S3 do autor da chamada envolve invocar a ação GET Service no Amazon S3. No recurso raiz do API, (/), crie o método GET. Configure o método GET para integrar-se ao Amazon S3 da maneira a seguir.

Para criar e inicializar o método GET / da API

1. Selecione o recurso / e Criar método.

2. Em tipo de método, selecione GET.

3. Em Tipo de integração, selecione AWS service (Serviço da AWS).

4. Para Região da AWS, selecione a Região da AWS onde você criou o bucket do Amazon S3.

5. Em AWS service (Serviço da AWS), selecione Amazon Simple Storage Service.

6. Mantenha o subdomínio da AWS em branco.

7. Em Método HTTP, selecione GET.

8. Em Tipo de ação, escolha Usar substituição de caminho. Com a substituição de caminho, o API Gateway encaminha a solicitação do cliente para o Amazon S3 como a solicitação no estilo de caminho da API REST do Amazon S3 correspondente em que um recurso do Amazon S3 é expresso pelo caminho de recurso do padrão s3-host-name/bucket/key. O API Gateway define o s3-host-name e transmite o bucket especificado pelo cliente e key do cliente para o Amazon S3.

9. Em Substituição de caminho, digite /.

10. Em Perfil de execução, digite o ARN do perfil para APIGatewayS3ProxyPolicy.

11. Escolha Criar método.

Essa configuração integra a solicitação GET https://your-api-host/stage/ do front-end com o GET https://your-s3-host/ do backend.

nota

Após a configuração inicial, você pode modificar essas configurações na página Solicitação de integração do método.

Para controlar quem pode chamar esse método da nossa API, podemos ativar o sinalizador de autorização de método e defini-lo como AWS_IAM.

Como permitir que o IAM controle o acesso ao método GET /

1. Na guia Solicitação de método, em Configurações de solicitação de método, escolha Editar.

2. Em Autorização, no menu suspenso, selecione AWS_IAM.

   

3. Escolha Save (Salvar).

Para que a nossa API retorne respostas e exceções bem-sucedidas corretamente ao autor da chamada, declaramos as respostas 200, 400 e 500 em Resposta de método. Usamos o mapeamento padrão para respostas 200 para que as respostas do backend do código de status não declaradas aqui sejam retornadas ao autor da chamada como respostas 200.

Como declarar tipos de resposta para o método GET /

1. Na guia Resposta de método, em Resposta 200, selecione Editar.

2. Selecione Adicionar usuário e faça o seguinte:

   1. Em Nome do cabeçalho, insira Content-Type.

   2. Escolha Add header (Adicionar cabeçalho).

   Repita essas etapas para criar um cabeçalho Timestamp e um Content-Length.

3. Escolha Save (Salvar).

4. Na guia Resposta de método, em Respostas do método, selecione Criar resposta.

5. Para o código de status HTTP, insira 400.

   Você não vai definir nenhum cabeçalho para essa resposta.

6. Escolha Save (Salvar).

7. Repita as etapas a seguir para criar a resposta 500.

   Você não vai definir nenhum cabeçalho para essa resposta.

Como a resposta de integração bem-sucedida do Amazon S3 retorna a lista de buckets como uma carga XML, e a resposta de método padrão do API Gateway retorna uma carga JSON, devemos mapear o valor do parâmetro do cabeçalho Content-Type do backend para sua contraparte do front-end. Caso contrário, o cliente receberá application/json para o tipo de conteúdo quando o corpo da resposta é na verdade uma string XML. O procedimento a seguir mostra como configurar isso. Além disso, também queremos mostrar para o cliente outros parâmetros de cabeçalho, como Date e Content-Length.

Para configurar mapeamentos de cabeçalho de resposta para o método GET /

1. Na guia Resposta de integração, em Padrão - Resposta, selecione Editar.

2. Para o cabeçalho Content-Length, insira integration.response.header.Content-Length para o valor do mapeamento.

3. Para o cabeçalho Content-Type, insira integration.response.header.Content-Type para o valor do mapeamento.

4. Para o cabeçalho Carimbo de data e hora, insira integration.response.header.Date para o valor do mapeamento.

5. Escolha Save (Salvar). O resultado deve ser semelhante ao seguinte:

   

6. Na guia Resposta de integração, em Respostas de integração, selecione Criar resposta.

7. Em HTTP status regex (Regex de status HTTP), insira 4\d{2}. Isso associa todos os códigos de status de resposta HTTP 4xx à resposta do método.

8. Em Código de status de resposta do método, selecione 400.

9. Escolha Create (Criar).

10. Repita as etapas a seguir para criar uma resposta de integração para a resposta do método 500. Em HTTP status regex (Regex de status HTTP), insira 5\d{2}.

Como prática recomendada, vamos testar a API que configuramos até agora.

Como testar o método GET /

1. Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.

2. Escolha Test (Testar). O resultado deve ser algo semelhante à seguinte imagem:

   

Expor métodos de API para acessar um bucket do Amazon S3

Para trabalhar com um bucket do Amazon S3, expomos o método GET no recurso /{folder} para listar objetos em um bucket. As instruções são semelhantes às descritas em Expor um método de API para listar os buckets do Amazon S3 do autor da chamada. Para conhecer mais métodos, é possível importar a API de exemplo aqui, Definições do OpenAPI da API de amostra como um proxy do Amazon S3.

Como expor o método GET em um recurso de pasta

1. Selecione o recurso /{folder} e, depois, Criar método.

2. Em tipo de método, selecione GET.

3. Em Tipo de integração, selecione AWS service (Serviço da AWS).

4. Para Região da AWS, selecione a Região da AWS onde você criou o bucket do Amazon S3.

5. Em AWS service (Serviço da AWS), selecione Amazon Simple Storage Service.

6. Mantenha o subdomínio da AWS em branco.

7. Em Método HTTP, selecione GET.

8. Em Tipo de ação, escolha Usar substituição de caminho.

9. Em Substituição de caminho, digite {bucket}.

10. Em Perfil de execução, digite o ARN do perfil para APIGatewayS3ProxyPolicy.

11. Escolha Criar método.

Você vai definir os parâmetros de caminho {folder} no URL do endpoint do Amazon S3. É necessário associar o parâmetro de caminho {folder} da solicitação de método ao parâmetro de caminho {bucket} da solicitação de integração.

Como associar {folder} a {bucket}

1. Na guia Solicitação de integração, em Configurações de solicitação de integração, selecione Editar.

2. Selecione Parâmetros de caminho de URL e, depois, Adicionar parâmetro de caminho.

3. Em Nome, digite bucket.

4. Em Mapeado de, insira method.request.path.folder. A configuração deve ser semelhante à seguinte:

   

5. Escolha Save (Salvar).

Agora, você vai testar a API.

Como testar o método /{folder} GET.

1. Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.

2. Em Caminho, em pasta, insira o nome do bucket.

3. Escolha Test (Testar).

   O resultado do teste conterá uma lista de objetos no bucket.

   

Expor métodos de API para acessar um objeto do Amazon S3 em um bucket

O Amazon S3 oferece suporte a ações GET, DELETE, HEAD, OPTIONS, POST e PUT para acessar e gerenciar objetos em um determinado bucket. Neste tutorial, você vai expor um método GET no recurso {folder}/{item} para obter uma imagem de um bucket. Para conhecer mais aplicações do recurso {folder}/{item}, consulte a API de exemplo, Definições do OpenAPI da API de amostra como um proxy do Amazon S3.

Como expor o método GET em um recurso de item

1. Selecione o recurso /{item} e, depois, Criar método.

2. Em tipo de método, selecione GET.

3. Em Tipo de integração, selecione AWS service (Serviço da AWS).

4. Para Região da AWS, selecione a Região da AWS onde você criou o bucket do Amazon S3.

5. Em AWS service (Serviço da AWS), selecione Amazon Simple Storage Service.

6. Mantenha o subdomínio da AWS em branco.

7. Em Método HTTP, selecione GET.

8. Em Tipo de ação, escolha Usar substituição de caminho.

9. Em Substituição de caminho, insira {bucket}/{object}.

10. Em Perfil de execução, digite o ARN do perfil para APIGatewayS3ProxyPolicy.

11. Escolha Criar método.

Você vai definir os parâmetros de caminho {folder} e o {item} no URL do endpoint do Amazon S3. É necessário associar o parâmetro de caminho da solicitação de método ao parâmetro de caminho da solicitação de integração.

Nesta etapa, faça o seguinte:

• Mapeie o parâmetro de caminho {folder} da solicitação de método ao parâmetro de caminho {bucket} da solicitação de integração.

• Mapeie o parâmetro de caminho {item} da solicitação de método ao parâmetro de caminho {object} da solicitação de integração.

Como associar {folder} a {bucket} e {item} a {object}

1. Na guia Solicitação de integração, em Configurações de solicitação de integração, selecione Editar.

2. Selecione Parâmetros de caminho de URL.

3. Selecione Adicionar parâmetro de caminho.

4. Em Nome, digite bucket.

5. Em Mapeado de, insira method.request.path.folder.

6. Selecione Adicionar parâmetro de caminho.

7. Em Nome, digite object.

8. Em Mapeado de, insira method.request.path.item.

9. Escolha Save (Salvar).

Como testar o método /{folder}/{object} GET.

1. Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.

2. Em Caminho, em pasta, insira o nome do bucket.

3. Em Caminho, em item, insira o nome de um item.

4. Escolha Test (Testar).

   O corpo da resposta incluirá o conteúdo do item.

   

   A solicitação exibe corretamente o texto sem formatação (“Hello world”) como o conteúdo do arquivo especificado (test.txt) no bucket do Amazon S3 especificado (DOC-EXAMPLE-BUCKET).

Para fazer download ou upload de arquivos binários, que no API Gateway é qualquer conteúdo que não seja JSON codificado em utf-8, são necessárias configurações de API adicionais. Isto é descrito da seguinte forma:

Para fazer download ou upload de arquivos binários do S3

1. Registre os tipos de mídia do arquivo afetado para binaryMediaTypes da API. Você pode fazer isso no console:

   1. Selecione Configurações para a API.

   2. Em Tipos de mídia binária, selecione Adicionar tipo de mídia binária.

   3. Selecione Adicionar tipo de mídia binária e insira o tipo de mídia necessário, por exemplo, image/png.

   4. Selecione Save changes (Salvar alterações) para salvar a configuração.

2. Adicione o cabeçalho Content-Type (para upload) e/ou Accept (para download) à solicitação de método para exigir que o cliente especifique o tipo de mídia binário necessário e o mapeie para a solicitação de integração.

3. Defina Tratamento de conteúdo como Passthrough na solicitação de integração (para upload) e em uma resposta de integração (para download). Certifique-se de que nenhum modelo de mapeamento está definido para o tipo de conteúdo afetado. Para obter mais informações, consulte Comportamentos de passagem direta de integração e Selecionar um modelo de mapeamento VTL.

O tamanho máximo da carga é 10 MB. Consulte Cotas do API Gateway para configurar e executar uma API REST.

Certifique-se de que os arquivos no Amazon S3 tenham os tipos de conteúdo corretos adicionados como metadados de arquivos. Para a transmissão de conteúdo de mídia, talvez também seja necessário adicionar Content-Disposition:inline aos metadados.

Para obter mais informações sobre o suporte binário no API Gateway, consulte Conversões de tipo de conteúdo no API Gateway.