Como carregar uma imagem ou arquivo PDF no Amazon S3 por meio do API Gateway?

Breve descrição

Para fazer upload de uma imagem ou PDF como arquivo binário em um bucket do Amazon S3 por meio do API Gateway, ative o suporte a binários.

Para conceder à sua API acesso ao seu bucket do S3, crie um perfil do AWS Identity and Access Management (IAM). O perfil do IAM deve incluir permissões para o API Gateway executar as ações PutObject e GetObject no seu bucket do S3.

Resolução

Criar um perfil do IAM para o API Gateway

1.    Abra o console do IAM.

2.    No painel de navegação, selecione Roles (Perfis).

3.    Escolha Create role (Criar perfil).

4.    Na seção Select type of trusted entity (Selecionar tipo de entidade confiável), escolha AWS Service (Serviço da AWS).

5.    Na seção Choose a use case (Escolha um caso de uso), escolha API Gateway.

6.    Na seção Select your use case (Selecionar seu caso de uso), escolha API Gateway.

7.    Escolha Next (Avançar). Permissões.
Observação: esta seção mostra o serviço gerenciado da AWS que permite ao API Gateway enviar logs para a conta de um usuário. Você adicionará permissões para o Amazon S3 mais tarde.

8.    (Opcional) Escolha Next (Avançar): Etiquetas para adicionar etiquetas.

9.    Escolha Next (Avançar). Revisão.

10.    Para Role name (Nome do perfil), insira um nome para sua política. Por exemplo: api-gateway-upload-to-s3.

11.    Escolha Create role (Criar perfil).

Criar e anexar uma política do IAM ao perfil do API Gateway

1.    Abra o console do IAM.

2.    No painel de navegação, selecione Roles (Perfis).

3.    Na caixa de pesquisa, insira o nome do novo perfil do API Gateway que você criou. Em seguida, escolha esse perfil na coluna Role name (Nome do perfil).

4.    Na guia da Roles detail page (Página de detalhes do perfil), escolha Add permissions (Adicionar permissões).

5.    Escolha Create inline policy (Criar política em linha).

6.    Na guia Visual editor (Editor visual), na seção Select a service (Selecionar um serviço), escolha Choose a service (Escolher um serviço).

7.    Insira S3 e, em seguida, escolha S3.

8.    Na caixa Specify the actions allowed in S3 (Especificar as ações permitidas no S3), insira PutObject e escolha PutObject.

9.    Insira GetObject e escolha GetObject.

10.    Expanda Resources (Recursos) e escolha Specific (Específico).

11.    Escolha Add ARN (Adicionar ARN).

12.    Em Bucket name (Nome do bucket), insira o nome do seu bucket. Inclua o prefixo, se aplicável.

13.    Em Object name (Nome do objeto), insira um nome de objeto.
Observação: o nome do bucket especifica a localização dos arquivos carregados. O nome do objeto especifica o padrão que o objeto deve seguir para alinhamento de políticas. Para mais informações, consulte Bucket naming rules (Regras de nomenclatura de buckets) e Amazon S3 objects overview (Visão geral de objetos do Amazon S3).

14.    Escolha Add (Adicionar).

15.    (Opcional) Escolha Next (Avançar): Etiquetas para adicionar etiquetas.

16.    Escolha Next (Avançar). Revisão.

17.    Em Name, insira o nome da sua política.

18.    Escolha Create policy (Criar política).

19.    Na caixa de pesquisa de políticas, insira o nome da política que você criou na etapa 17 e selecione essa política.

20.    Escolha Policy actions (Ações da política) e depois Attach (Anexar). É exibida uma lista de perfis do IAM.

21.    Procure o perfil do API Gateway que você criou anteriormente. Em seguida, selecione o perfil.

22.    Escolha Attach policy (Anexar política).

Criar uma API REST do API Gateway

Criar uma API para atender às suas solicitações

1.    Abra o console do API Gateway.

2.    No painel de navegação, escolha APIs.

3.    Escolha Create API (Criar API).

4.    Na seção Choose an API type (Escolher um tipo de API), para API REST, escolha Create (Criar).

5.    Em API Name (Nome da API), insira um nome para sua API e escolha Next (Avançar).

6.    Escolha Create API (Criar API).

Criar recursos para sua API

1.    No painel Resources (Recursos) da sua página de API, selecione /.

2.    Em Actions (Ações), escolha Create Resource (Criar recurso).

3.    Em Resource Name (Nome do recurso), insira folder (pasta).

4.    Em Resource Path (Caminho do recurso), insira {folder}.

5.    Escolha Create Resource (Criar recurso).

6.    No painel Resources (Recursos), selecione o recurso /{folder} que você criou na etapa 5.

7.    Escolha Actions (Ações) e depois Create Resource (Criar recurso).

8.    Em Resource Name (Nome do recurso), insira object.

9.    Em Resource Path (Caminho do recurso), insira {object}.

10.    Escolha Create Resource (Criar recurso).

Criar um método PUT para sua API para carregar uma imagem ou PDF

1.    Escolha Actions (Ações) e depois Create Method (Criar Método).

2.    Na lista suspensa, escolha PUT e escolha o ícone de marca de seleção.

3.    Na categoria Integration type (Tipo de integração), escolha AWS Service (Serviço da AWS).

4.    Para Região da AWS, escolha us-east-1 ou a região da AWS que você vê na página Propriedades do bucket.

5.    Em Serviço da AWS, escolha Simple Storage Service (S3).

6.    Mantenha o Subdomínio da AWS vazio.

7.    Em Método HTTP, escolha PUT.

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

9.    Em Path override (optional) (Substituição de caminho (opcional)), insira {bucket}/{key}.

10.    Em Execution role (Perfil de execução), insira o ARN do perfil do IAM que você criou anteriormente.. A criação do ARN faz parte da seção Create and attach an IAM policy to the API Gateway role (Criar e anexar uma política do IAM ao perfil do API Gateway).

11.    Em Content Handling (Manuseio de conteúdo), escolha Passthrough (Passagem).

12.    Escolha Save (Salvar).

Configurar mapeamentos de parâmetros para o método PUT

1.    No painel Resources (Recursos) da sua página de API, escolha PUT.

2.    Escolha Integration Request (Solicitação de integração).

3.   Expanda URL Path Parameters (Parâmetros de caminho de URL).

4.    Escolha Add path (Adicionar caminho).

5.    Em Name (Nome), insira bucket.

6.    Em Mapeado de (Mapeado de), insira method.request.path.folder.

7.    Escolha o ícone de marca de seleção no final da linha.

8.    Repita as etapas de 4 a 7. Na etapa 5, defina Name como key. Na etapa 6, defina Mapeado de como method.request.path.object.

Criar um método GET para sua API para recuperar uma imagem

1.    No painel Resources (Recursos) da sua página de API, escolha /{object}.

2.    Escolha Actions (Ações) e depois Create Method (Criar Método).

3.    Na lista suspensa, escolha GET e escolha o ícone de marca de seleção.

4.    Na categoria Integration type (Tipo de integração), escolha AWS Service (Serviço da AWS).

5.    Para Região da AWS, escolha us-east-1 ou a região que você vê na página Propriedades do bucket.

6.    Em Serviço da AWS, escolha Simple Storage Service (S3).

7.    Mantenha o Subdomínio da AWS vazio.

8.    Em Método HTTP, escolha GET.

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

10.    Em Path override (optional) (Substituição de caminho (opcional)), insira {bucket}/{key}.

11.    Em Execution role (Perfil de execução), insira o ARN do perfil do IAM que você criou anteriormente.. A criação do ARN faz parte da seção Create and attach an IAM policy to the API Gateway role (Criar e anexar uma política do IAM ao perfil do API Gateway).

12.    Em Content Handling (Manuseio de conteúdo), escolha Passthrough (Passagem).

13.    Escolha Save (Salvar).

Configurar mapeamentos de parâmetros para o método GET

1.    No painel Resources (Recursos) da sua página de API, escolha GET.

2.    Escolha Integration Request (Solicitação de integração).

3.   Expanda URL Path Parameters (Parâmetros de caminho de URL).

4.    Escolha Add path (Adicionar caminho).

5.    Em Name (Nome), insira bucket.

6.    Em Mapeado de (Mapeado de), insira method.request.path.folder.

7.    Escolha o ícone de marca de seleção no final da linha.

8.    Repita as etapas de 4 a 7. Na etapa 5, defina Name como key. Na etapa 6, defina Mapeado de como method.request.path.object.

Configure o mapeamento de respostas para ver a imagem ou o PDF no navegador

1.    No painel Resources (Recursos) da sua página de API, escolha GET.

2.    Escolha Method Response (Resposta do método).

3.    Expanda 200.

4.    Em Response Body for 200 (Corpo da resposta para 200), remova application/json.

5.    Em Response headers for 200 (Cabeçalhos de resposta para 200), escolha Add header (Adicionar cabeçalho).

6.    Em Name (Nome), insira content-type.

7.    Escolha o ícone de marca de seleção para salvar.

8.    Escolha Method execution (Execução do método) para voltar ao painel Method Execution (Execução do método).

9.    Escolha Integration Response (Resposta de integração).

10.    Expanda 200 e depois Header Mappings (Mapeamentos de cabeçalho).

11.    Escolha o ícone de lápis no final da linha denominada content-type.

12.    Insira 'image/jpeg' para ver um arquivo de imagem.
-ou-
Insira 'application/pdf' para ver um arquivo PDF.

Configurar tipos de mídia binária para a API

1.   No painel de navegação da sua página de API, escolha Settings (Configurações).

2.    Na seção Binary Media Type (Tipos de mídia binários), escolha Add Binary Media Type (Adicionar tipo de mídia binário).

3.    Na caixa de texto, adicione a seguinte string: */*
Observação: não coloque a string entre aspas. Você pode substituir um curinga por um tipo Multipurpose Internet Mail Extensions (MIME) específico que deseja tratar como um tipo de mídia binário. Por exemplo, para que o API Gateway trate imagens JPEG como tipos de mídia binários, escolha 'image/jpeg'. Se você adicionar */*, o API Gateway tratará todos os tipos de mídia como binários.

4.    Escolha Save changes (Salvar alterações).

Resolver o erro de CORS com configurações binárias para API

1.    Se você usar as APIs mencionadas anteriormente (PUT e GET) em uma aplicação Web, poderá encontrar um erro de CORS. Para mais informações, consulte Erros de CORS no site do Mozilla.

2.    Para resolver o erro do CORS com as configurações binárias ativadas, inicie o CORS no console do API Gateway.

3.    No painel Resources (Recursos) da sua página de API, selecione /{object}.

4.    Em Actions (Ações), escolha Enable CORS (Ativar CORS).

5.    Escolha Enable CORS and replace existing CORS headers (Ativar o CORS e substitua os cabeçalhos dele existentes).

6.    Para atualizar a propriedade de tratamento de conteúdo, execute o comando update-integration da CLI.. Essa atualização permite que o conteúdo binário manipule solicitações de opções de preflight com integração simulada.

7.    Atualize o ID da API, o ID do recurso e a região da AWS para executar os dois comandos da CLI a seguir. Para obter o ID da API e o ID do recurso, selecione o recurso {object} na parte superior do console da API do Gateway.

aws apigateway update-integration --rest-api-id API_ID --resource-id RESOURCE_id --http-method OPTIONS --patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT' --region AWS_REGION

aws apigateway update-integration-response --rest-api-id API_ID --resource-id RESOURCE_id --http-method OPTIONS --status-code 200 --patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT' --region AWS_REGION

Implantar sua API

1.    No painel de navegação da sua página de API, escolha Resources (Recursos)..

2.    No painel Resources (Recursos), escolha Actions (Ações) e, em seguida, Deploy API (Implantar API).

3.    Na janela Deploy API (Implantar API), em Deployment stage (Estágio de implantação), escolha [New Stage].

4.    Em Stage name (Nome do estágio), insira v1.

5.    Escolha Deploy (Implantar).

6.    No painel de navegação, escolha Stages (Estágios).

7.    Escolha o estágio v1. O URL de invocação para fazer solicitações ao snapshot da API implantada é exibido.

8.    Copie o URL de invocação.

Observação: para mais informações, consulte Deploying a REST API in Amazon API Gateway (Implantar uma API REST no Amazon API Gateway).

Invocar sua API para carregar um arquivo de imagem no S3

Anexe o nome do bucket e o nome do arquivo do objeto ao URL de invocação da sua API. Em seguida, faça uma solicitação HTTP PUT com um cliente de sua escolha. Por exemplo, com a aplicação externa Postman, escolha o método PUT no menu suspenso. Escolha Body (Corpo) e depois binary (binário). Quando o botão Select File (Selecionar arquivo) for exibido, selecione um arquivo local para carregar.

Para mais informações, consulte Invoking a REST API in Amazon API Gateway (Invocar uma API REST no Amazon API Gateway).

Exemplo de comando curl para fazer uma solicitação HTTP PUT para carregar uma imagem ou um PDF

No exemplo a seguir, abc12345 é seu ID de API, testfolder é seu bucket do S3 e testimage.jpeg é o arquivo local que você carrega:

curl -i --location --request PUT 'https://abc12345.execute-api.us-west-2.amazonaws.com/v1/testfolder/testimage.jpeg' --header 'Content-Type: text/plain' --data-binary '@/Path/to/file/image.jpeg'

Importante: se */* estiver incluído na lista de tipos de mídia binários, você poderá fazer uma solicitação PUT para carregar o arquivo. Se image.jpeg estiver incluído na lista de tipos de mídia binários, você deverá adicionar o cabeçalho Content-Type à sua solicitação PUT. Você deve definir Cabeçalho Content-Type como 'image/jpeg'.

Agora, você verá a imagem ou o PDF em um navegador da Web com o mesmo URL. Isso ocorre porque o navegador da Web faz uma solicitação GET.

Informações relacionadas

Ativar o suporte a binários usando a API REST do API Gateway