Como uso o API Gateway como proxy para outro serviço da AWS?
Quero usar o Amazon API Gateway como proxy para outro serviço da AWS e integrar outros serviços com o API Gateway.
Breve descrição
As APIs de serviço da AWS são essencialmente APIs REST às quais você pode fazer uma solicitação HTTPS. Você pode integrar muitos serviços da AWS com o API Gateway, mas a configuração e o mapeamento variam de acordo com a API de serviço específica.
Para integrar outro serviço ao API Gateway, crie uma solicitação HTTPS do API Gateway para a API do serviço. Dessa forma, todos os parâmetros da solicitação são mapeados corretamente.
Este artigo descreve um exemplo de configuração para integrar a API de Publicação do Amazon Simple Notification Service (Amazon SNS) com o API Gateway. Use esse exemplo como um esboço para integrar outros serviços.
Resolução
Observação: se você receber erros ao executar comandos da AWS Command Line Interface (AWS CLI), certifique-se de estar usando a versão mais recente da AWS CLI.
Configure as ferramentas e os recursos necessários
Configure seu ambiente e crie todos os recursos da AWS necessários para seu caso de uso. Para a configuração de exemplo do Amazon SNS, faça o seguinte:
- Instale a AWS CLI.
- Crie um tópico do Amazon SNS. Observe o nome de recurso da Amazon (ARN) do tópico. Use essas informações na próxima etapa e posteriormente nessa configuração.
- Crie uma assinatura para o tópico.
- Abra o console AWS Identity and Access Management (IAM) e, em seguida, crie um perfil de execução do proxy de serviço da AWS. Anote o ARN do perfil para mais tarde, na configuração. Esse perfil do IAM concede permissões ao API Gateway como uma entidade confiável para assumir o serviço e realizar a ação de API que você está integrando. Para a configuração de exemplo do Amazon SNS, permita a ação sns:Publish. Para mais informações, consulte API Gateway permissions model for invoking an API (Modelo de permissões do API Gateway para invocar uma API).
- Crie uma API REST do API Gateway com um recurso de teste. Para mais informações e exemplos, consulte os tutoriais e workshops do Amazon API Gateway.
Observação: opcionalmente, importe a API REST usando o exemplo de definição OpenAPI 2.0 (Swagger) a seguir. Essa opção pré-configura as definições para a configuração de exemplo do Amazon SNS. Certifique-se de substituir arn:aws:iam::account-id:role/apigateway-sns-role pelo ARN do seu perfil do IAM. Substitua a região pela região da AWS em que você deseja criar sua API REST.
{ "swagger": "2.0", "info": { "version": "2019-10-09T14:10:24Z", "title": "aws-service-integration" }, "basePath": "/dev", "schemes": [ "https" ], "paths": { "/test": { "post": { "produces": [ "application/json" ], "parameters": [ { "name": "Message", "in": "query", "required": true, "type": "string" }, { "name": "TopicArn", "in": "query", "required": true, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::account-id:role/apigateway-sns-role", "uri": "arn:aws:apigateway:region:sns:action/Publish", "responses": { "default": { "statusCode": "200" } }, "requestParameters": { "integration.request.querystring.TopicArn": "method.request.querystring.TopicArn", "integration.request.querystring.Message": "method.request.querystring.Message" }, "passthroughBehavior": "when_no_match", "httpMethod": "POST", "type": "aws" } } } }, "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } } }
Obtenha um exemplo de solicitação HTTPS
Um exemplo de solicitação HTTPS da API de serviço que você está integrando pode ajudá-lo a mapear corretamente os parâmetros da solicitação no API Gateway. Para obter um exemplo de solicitação HTTPS, faça o seguinte:
Consulte exemplos na documentação da API. Para a API de Publicação do Amazon SNS, você pode consultar a Referência da API de serviço para obter um exemplo de solicitação:
https://sns.us-west-2.amazonaws.com/?Action=Publish &TargetArn=arn%3Aaws%3Asns%3Aus-west-2%3A803981987763%3Aendpoint%2FAPNS_SANDBOX%2Fpushapp%2F98e9ced9-f136-3893-9d60-776547eafebb &Message=%7B%22default%22%3A%22This+is+the+default+Message%22%2C%22APNS_SANDBOX%22%3A%22%7B+%5C%22aps%5C%22+%3A+%7B+%5C%22alert%5C%22+%3A+%5C%22You+have+got+email.%5C%22%2C+%5C%22badge%5C%22+%3A+9%2C%5C%22sound%5C%22+%3A%5C%22default%5C%22%7D%7D%22%7D &Version=2010-03-31 &AUTHPARAMS
- ou -
Gere isso a partir de uma chamada de API. Use a AWS CLI para chamar a API de serviço e, em seguida, analise a saída. Determine o comando da AWS CLI correspondente para a API de serviço que você está integrando e, em seguida, execute uma solicitação de teste com a opção**--debug**.
Dica: verifique a Referência de Comandos da AWS CLI para encontrar o comando da AWS CLI correspondente.
Para o exemplo de configuração do Amazon SNS, execute este comando:
Observação: substitua arn:aws:sns:us-east-1:123456789012:test pelo ARN do seu tópico do Amazon SNS.
$ aws sns publish --topic-arn arn:aws:sns:us-east-1:123456789012:test --message "hi" --debug
A saída do comando contém a solicitação HTTPS e os cabeçalhos que são passados. Aqui está um exemplo do que procurar:
2018-11-22 11:56:39,647 - MainThread - botocore.client - DEBUG - Registering retry handlers for service: sns 2018-11-22 11:56:39,648 - MainThread - botocore.hooks - DEBUG - Event before-parameter-build.sns.Publish: calling handler <function generate_idempotent_uuid at 0x11093d320> 2018-11-22 11:56:39,649 - MainThread - botocore.endpoint - DEBUG - Making request for OperationModel(name=Publish) (verify_ssl=True) with params: {'body': {'Action': u'Publish', u'Message': u'hello', 'Version': u'2010-03-31', u'TopicArn': u'arn:aws:sns:us-east-1:123456789012:test'}, 'url': u'https://sns.us-east-1.amazonaws.com/', 'headers': {'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8', 'User-Agent': 'aws-cli/1.15.74 Python/2.7.14 Darwin/16.7.0 botocore/1.9.23'}, 'context': {'auth_type': None, 'client_region': 'us-east-1', 'has_streaming_input': False, 'client_config': <botocore.config.Config object at 0x1118437d0>}, 'query_string': '', 'url_path': '/', 'method': u'POST'} 2018-11-22 11:56:39,650 - MainThread - botocore.hooks - DEBUG - Event request-created.sns.Publish: calling handler <bound method RequestSigner.handler of <botocore.signers.RequestSigner object at 0x111843750>> 2018-11-22 11:56:39,650 - MainThread - botocore.hooks - DEBUG - Event choose-signer.sns.Publish: calling handler <function set_operation_specific_signer at 0x11093d230> 2018-11-22 11:56:39,650 - MainThread - botocore.auth - DEBUG - Calculating signature using v4 auth. 2018-11-22 11:56:39,651 - MainThread - botocore.auth - DEBUG - CanonicalRequest: POST / content-type:application/x-www-form-urlencoded; charset=utf-8 host:sns.us-east-1.amazonaws.com x-amz-date:20181122T062639Z content-type;host;x-amz-date
Neste exemplo, a solicitação é enviada como um método HTTP POST.
Crie um método para sua API do API Gateway
- No console do API Gateway, no painel APIs, selecione o nome da sua API.
- No painel Recursos, selecione um recurso. Para a configuração de exemplo do Amazon SNS, selecione o recurso de teste que você criou.
- Selecione Ações e, em seguida, selecione Criar método.
- Na lista suspensa, escolha o método usado pela sua API de serviço no exemplo de solicitação HTTPS. (Para a configuração de exemplo do Amazon SNS, selecione POST.) Em seguida, selecione o ícone de marca de seleção.
- No painel Configuração, faça como a seguir:
Em Tipo de integração, selecione AWS Service.
Em região da AWS, selecione a região da AWS do recurso associado à API de serviço que você está integrando. Para a configuração de exemplo do Amazon SNS, selecione a região do seu tópico do SNS.
Em AWS Service, selecione o serviço que você está integrando ao API Gateway. Por exemplo, Simple Notification Service (SNS).
(Opcional) Em Subdomínio da AWS, insira o subdomínio usado pelo serviço da AWS. Verifique a documentação do serviço para confirmar a disponibilidade de um subdomínio. Para o exemplo de configuração do Amazon SNS, deixe em branco.
Em Método HTTP, selecione o método que corresponde à API de serviço da AWS que você está integrando. Para a configuração de exemplo do Amazon SNS, selecione POST.
Em Tipo de ação, se a API de serviço que você está integrando for uma ação compatível, selecione Usar nome da ação. Consulte areferência da API do serviço para obter uma lista de ações compatíveis. Para o Amazon SNS, consulte Ações.
Em Ação, insira o nome da API de serviço. Para a configuração de exemplo do Amazon SNS, insira Publicar.
-ou-
Em Tipo de ação, se a API de serviço da AWS espera um caminho de recurso em sua solicitação, selecione Usar substituição de caminho. Por exemplo, para a API ListLexicons do Amazon Polly, insira /v1/lexicons para Substituição de caminho (opcional).
Em Perfil de execução, insira o ARN do perfil do IAM que você criou.
(Opcional) Em Tratamento de conteúdo e Tempo limite de uso padrão, faça as alterações necessárias para seu caso de uso. Para a configuração de exemplo do Amazon SNS, não altere essas configurações. - Escolha Save (Salvar).
Crie parâmetros para a solicitação do método
Determine os parâmetros de solicitação obrigatórios e opcionais para a API de serviço que você está integrando. Para identificar esses parâmetros, consulte o exemplo de solicitação HTTPS que você recebeu anteriormente ou consulte a Referência de API para a API de serviço. Por exemplo, consulte Publicar.
- No console do API Gateway, no painel Execução de método do método de API do API Gateway, selecione Solicitação de método.
- (Opcional) No painel Solicitação de Método, em Validador de Solicitação, selecione um validador de solicitação, corpo e cabeçalhos se quiser validar os parâmetros da string de consulta.
- Expanda os parâmetros da string de consulta de URL.
- Selecione Adicionar string de consulta.
- Em Nome, insira o nome de um parâmetro de solicitação para a API de serviço que você está integrando.
- Selecione o ícone de marca de seleção (Criar uma nova string de consulta).
- Se o parâmetro for obrigatório, marque a caixa de seleção em Obrigatório.
- Repita as etapas de 4 a 7 para todos os parâmetros de solicitação que você deseja incluir. Para a configuração de exemplo do Amazon SNS, crie um parâmetro chamado T****opicArn e outro chamado Mensagem.
Para obter mais informações, consulte Configurar um método usando o console do API Gateway.
Observação: para algumas APIs de serviço, você deve enviar os cabeçalhos necessários e um corpo na solicitação de integração, além dos parâmetros necessários. Você pode criar os cabeçalhos e o corpo no painel Solicitação de integração em Cabeçalhos da solicitação HTTP e Corpo da solicitação.
Por exemplo, se você estiver integrando a API ListCollections do Amazon Rekognition, crie o cabeçalho X-Amz-Target: RekognitionService.ListCollections. A solicitação tem a seguinte aparência:
POST https://rekognition.us-west-2.amazonaws.com/ HTTP/1.1 Host: rekognition.us-west-2.amazonaws.com Accept-Encoding: identity Content-Length: 2 X-Amz-Target: RekognitionService.ListCollections X-Amz-Date: 20170105T155800Z User-Agent: aws-cli/1.11.25 Python/2.7.9 Windows/8 botocore/1.4.82 Content-Type: application/x-amz-json-1.1 Authorization: AWS4-HMAC-SHA256 Credential=XXXXXXXX/20170105/us-west-2/rekognition/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=XXXXXXXX {}
Se você estiver integrando a API SendMessage do Amazon Simple Queue Service (Amazon SQS), mapeie o corpo da solicitação usando a expressão de mapeamento method.request.body.JSONPath_EXPRESSION. (Substitua JSONPath_EXPRESSION por uma expressão JSONPath para um campo JSON do corpo da solicitação.) Neste exemplo, uma solicitação é semelhante à seguinte:
{'url_path': '/', 'query_string': '', 'method': 'POST', 'headers': {'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8', 'User-Agent': 'aws-cli/1.16.81 Python/3.6.5 Darwin/18.7.0 botocore/1.12.183'}, 'body': {'Action': 'SendMessage', 'Version': '2012-11-05', 'QueueUrl': 'https://sqs.ap-southeast-2.amazonaws.com/123456789012/test01', 'MessageBody': 'Hello'}, 'url': 'https://ap-southeast-2.queue.amazonaws.com/', 'context': {'client_region': 'ap-southeast-2', 'client_config': <botocore.config.Config object at 0x106862da0>, 'has_streaming_input': False, 'auth_type': None}}
Crie parâmetros para a solicitação de integração
Mapeie os parâmetros que você criou para a solicitação de método com os parâmetros da solicitação de integração.
- No console do API Gateway, volte ao painel Execução de método do método de API do API Gateway e selecione Solicitação de integração.
- No painel Solicitação de integração, expanda Parâmetros da string de consulta de URL.
- Selecione Adicionar string de consulta.
- Em Nome, insira o nome de um parâmetro de solicitação para a API de serviço que você está integrando.
Observação: o nome diferencia maiúsculas de minúsculas e deve aparecer exatamente conforme o esperado pela API de serviço. - Em Mapeado de,insira method.request.querystring.param_name. Substitua o param_name pelo nome do parâmetro correspondente que você criou para a solicitação de método. Por exemplo, method.request.querystring.TopicArn.
- Selecione o ícone de marca de seleção (Criar).
- Repita as etapas de 3 a 6 para criar parâmetros para a solicitação de integração que correspondam a cada um dos parâmetros que você criou para a solicitação de método.
Observação: se você criou cabeçalhos obrigatórios e um corpo para a solicitação de método, mapeie-os também para a solicitação de integração. Crie-os no painel Solicitação de integração em Cabeçalhos HTTP e Modelos de mapeamento.
Para mais informações, consulte Configurar uma solicitação de integração de API usando o console do API Gateway.
(Opcional) Verifique sua configuração de integração
Para confirmar que sua configuração de integração está conforme o esperado, você pode executar o comando get-integration da AWS CLI para verificar a configuração semelhante à seguinte:
$ aws apigateway get-integration --rest-api-id 1234123412 --resource-id y9h6rt --http-method POST
Para a configuração de exemplo do Amazon SNS, a saída é semelhante à seguinte:
{ "integrationResponses": { "200": { "responseTemplates": { "application/json": null }, "statusCode": "200" } }, "passthroughBehavior": "WHEN_NO_MATCH", "timeoutInMillis": 29000, "uri": "arn:aws:apigateway:us-east-2:sns:action/Publish", "httpMethod": "POST", "cacheNamespace": "y9h6rt", "credentials": "arn:aws:iam::1234567890:role/apigateway-sns-role", "type": "AWS", "requestParameters": { "integration.request.querystring.TopicArn": "method.request.querystring.TopicArn", "integration.request.querystring.Message": "method.request.querystring.Message" }, "cacheKeyParameters": [] }
No console do API Gateway, volte para o painel Execução de método do método de API do API Gateway e selecione TEST.
- No painel Teste de método, faça o seguinte:
Em Strings de consulta, insira uma string de consulta que inclua parâmetros e valores de solicitação para elas. Para o exemplo de configuração do Amazon SNS, insira TopicArn= arn:aws:sns:us-east-1:123456789012:test&Message="Hello". Substitua arn:aws:sns:us-east-1:123456789012:test pelo ARN do seu tópico do Amazon SNS.
Para Cabeçalhos e Corpo da Solicitação, se você os criou para sua configuração, insira os nomes dos cabeçalhos e o corpo da solicitação JSON.
Escolha Testar. Uma resposta aparece no painel Teste de método. Se a resposta for bem-sucedida, você verá Status: 200. Para a configuração de exemplo do Amazon SNS, uma resposta bem-sucedida inclui um MessageId no corpo da resposta.
Para obter mais informações, consulte Usar o console do API Gateway para testar um método da API REST. - Implante sua API REST.
- Teste sua API usando qualquer ferramenta de sua preferência.
Informações relacionadas
Tutorial: Crie uma API REST do API Gateway com integração com a AWS
Configurar métodos da API REST no API Gateway
Configurar integrações da API REST
Configure mapeamentos de dados de solicitação e resposta usando o console do API Gateway
Vídeos relacionados
Conteúdo relevante
- AWS OFICIALAtualizada há 3 anos
- AWS OFICIALAtualizada há 2 anos
- AWS OFICIALAtualizada há 21 dias
- AWS OFICIALAtualizada há um mês