# Tutorial: Crie uma API REST como um proxy do Amazon S3
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](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html).
+ Expor GET em um recurso Folder para [visualizar uma lista de todos os objetos no bucket do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html).
+ Expor GET em um recurso Folder/Item para [visualizar ou baixar um objeto de um bucket do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html).
É 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](api-as-s3-proxy-export-swagger-with-extensions.md). Este exemplo contém mais métodos expostos. Para obter instruções sobre como importar uma API usando a definição do OpenAPI, consulte [Desenvolver APIs REST usando OpenAPI no API Gateway](api-gateway-import-api.md).
**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](https://docs.aws.amazon.com/general/latest/gr/apigateway.html).
**Topics**
+ [Configurar permissões do IAM para a API invocar ações do Amazon S3](#api-as-s3-proxy-iam-permissions)
+ [Criar recursos de API para representar recursos do Amazon S3](#api-as-s3-proxy-create-resources)
+ [Expor um método de API para listar os buckets do Amazon S3 do autor da chamada](#api-root-get-as-s3-get-service)
+ [Expor métodos de API para acessar um bucket do Amazon S3](#api-folder-operations-as-s3-bucket-actions)
+ [Expor métodos de API para acessar um objeto do Amazon S3 em um bucket](#api-items-in-folder-as-s3-objects-in-bucket)
+ [Definições do OpenAPI da API de amostra como um proxy do Amazon S3](api-as-s3-proxy-export-swagger-with-extensions.md)
+ [Chamar a API usando um cliente de API REST](api-as-s3-proxy-test-using-postman.md)
## 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. Neste exercício, você cria um perfil do IAM.
**Como criar o perfil de execução do proxy de serviço da AWS**
1. Faça login no Console de gerenciamento da AWS e abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. Escolha **Perfis**.
1. Selecione **Criar perfil**.
1. 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**.
1. Selecione **Próximo** e, depois, **Próximo**.
1. Em **Role name (Nome da função)**, digite **APIGatewayS3ProxyPolicy** e escolha **Create role (Criar função)**.
1. 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.
1. Para a função escolhida, selecione a guia **Adicionar permissões**.
1. Selecione **Anexar políticas** na lista suspensa.
1. 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.
1. Anote o **ARN do perfil** recém-criado, você o usará posteriormente.
## Criar recursos de API para representar recursos do Amazon S3
Use o recurso-raiz da API (`/`) como o contêiner de buckets do Amazon S3 de um chamador autenticado. Também crie 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}**.
1. Selecione **Criar recurso**.
1. Mantenha **Recurso proxy** desativado.
1. Em **Caminho do recurso**, selecione `/`.
1. Em **Resource Name (Nome do recurso)**, insira **{folder}**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desmarcado.
1. Selecione **Criar recurso**.
1. Selecione o recurso **/{folder}** e, depois, **Criar recurso**.
1. 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](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html) 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**.
1. Em tipo de método, selecione **GET**.
1. Em **Tipo de integração**, selecione **AWS service (Serviço da AWS)**.
1. Para **Região da AWS**, selecione a Região da AWS onde você criou o bucket do Amazon S3.
1. Em **AWS service (Serviço da AWS)**, selecione **Amazon Simple Storage Service**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, selecione **GET**.
1. 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAPI.html) 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.
1. Em **Substituição de caminho**, digite **/**.
1. Em **Perfil de execução**, digite o ARN do perfil para **APIGatewayS3ProxyPolicy**.
1. Escolha **Configurações de solicitação de método**.
Use as configurações de solicitação de método para controlar quem pode chamar esse método da sua API.
1. Em **Autorização**, no menu suspenso, selecione `AWS_IAM`.
1. 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.
Para que a API retorne respostas bem-sucedidas e exceções corretamente ao chamador, declare as respostas 200, 400 e 500 em **Resposta de método**. Use o mapeamento padrão para respostas 200 para que as respostas do back-end do código de status não declaradas aqui sejam retornadas ao chamador 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**.
1. Selecione **Adicionar usuário** e faça o seguinte:
1. Em **Nome do cabeçalho**, insira **Content-Type**.
1. Escolha **Add header** (Adicionar cabeçalho).
Repita essas etapas para criar um cabeçalho **Timestamp** e um **Content-Length**.
1. Escolha **Salvar**.
1. Na guia **Resposta de método**, em **Respostas do método**, selecione **Criar resposta**.
1. Para o **código de status HTTP**, insira **400**.
Você não vai definir nenhum cabeçalho para essa resposta.
1. Escolha **Salvar**.
1. 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 útil XML, e a resposta de método padrão do API Gateway retorna uma carga útil JSON, você deve mapear o valor do parâmetro do cabeçalho Content-Type do back-end 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, mostre também 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**.
1. Para o cabeçalho **Content-Length**, insira **integration.response.header.Content-Length** para o valor do mapeamento.
1. Para o cabeçalho **Content-Type**, insira **integration.response.header.Content-Type** para o valor do mapeamento.
1. Para o cabeçalho **Carimbo de data e hora**, insira **integration.response.header.Date** para o valor do mapeamento.
1. Escolha **Salvar**. O resultado deve ser semelhante ao seguinte:
1. Na guia **Resposta de integração**, em **Respostas de integração**, selecione **Criar resposta**.
1. 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.
1. Em **Código de status de resposta do método**, selecione **400**.
1. Escolha **Criar**.
1. 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, teste a API que você configurou 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.
1. Escolha **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, exponha 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](#api-root-get-as-s3-get-service). 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](api-as-s3-proxy-export-swagger-with-extensions.md).
**Como expor o método GET em um recurso de pasta**
1. Selecione o recurso **/{folder}** e, depois, **Criar método**.
1. Em tipo de método, selecione **GET**.
1. Em **Tipo de integração**, selecione **AWS service (Serviço da AWS)**.
1. Para **Região da AWS**, selecione a Região da AWS onde você criou o bucket do Amazon S3.
1. Em **AWS service (Serviço da AWS)**, selecione **Amazon Simple Storage Service**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, selecione **GET**.
1. Em **Tipo de ação**, escolha **Usar substituição de caminho**.
1. Em **Substituição de caminho**, digite **{bucket}**.
1. Em **Perfil de execução**, digite o ARN do perfil para **APIGatewayS3ProxyPolicy**.
1. 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**.
1. Selecione **Parâmetros de caminho de URL** e, depois, **Adicionar parâmetro de caminho**.
1. Em **Nome**, digite **bucket**.
1. Em **Mapeado de**, insira **method.request.path.folder**.
1. Escolha **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.
1. Em **Caminho**, em **pasta**, insira o nome do bucket.
1. Escolha **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](api-as-s3-proxy-export-swagger-with-extensions.md).
**Como expor o método GET em um recurso de item**
1. Selecione o recurso **/{item}** e, depois, **Criar método**.
1. Em tipo de método, selecione **GET**.
1. Em **Tipo de integração**, selecione **AWS service (Serviço da AWS)**.
1. Para **Região da AWS**, selecione a Região da AWS onde você criou o bucket do Amazon S3.
1. Em **AWS service (Serviço da AWS)**, selecione **Amazon Simple Storage Service**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, selecione **GET**.
1. Em **Tipo de ação**, escolha **Usar substituição de caminho**.
1. Em **Substituição de caminho**, insira **{bucket}/{object}**.
1. Em **Perfil de execução**, digite o ARN do perfil para **APIGatewayS3ProxyPolicy**.
1. 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**.
1. Selecione **Parâmetros de caminho de URL**.
1. Selecione **Adicionar parâmetro de caminho**.
1. Em **Nome**, digite **bucket**.
1. Em **Mapeado de**, insira **method.request.path.folder**.
1. Selecione **Adicionar parâmetro de caminho**.
1. Em **Nome**, digite **object**.
1. Em **Mapeado de**, insira **method.request.path.item**.
1. Escolha **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.
1. Em **Caminho**, em **pasta**, insira o nome do bucket.
1. Em **Caminho**, em **item**, insira o nome de um item.
1. Escolha **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 (amzn-s3-demo-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.
1. Em **Tipos de mídia binária**, selecione **Adicionar tipo de mídia binária**.
1. Selecione **Adicionar tipo de mídia binária** e insira o tipo de mídia necessário, por exemplo, `image/png`.
1. Selecione **Save changes** (Salvar alterações) para salvar a configuração.
1. 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.
1. 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 [Transformações de dados para APIs REST no API Gateway](rest-api-data-transformations.md).
O tamanho máximo da carga é 10 MB. Consulte [Cotas para configurar e executar uma API REST no API Gateway](api-gateway-execution-service-limits-table.md).
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](api-gateway-payload-encodings-workflow.md).