Como uso o API Gateway como proxy para outro serviço da AWS?

12 minuto de leitura

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

Tópicos

Sem servidor Web e dispositivos móveis front-end Rede e entrega de conteúdo

Vídeos relacionados

Assista ao vídeo de Akanksha para saber mais (8:47)

AWS OFICIALAtualizada há um ano

Conteúdo relevante

Como faço para resolver erros HTTP 502 das APIs REST do API Gateway com integração de proxy do Lambda?
AWS OFICIALAtualizada há 2 anos
Como faço para migrar as APIs REST do API Gateway entre contas ou regiões da AWS?
AWS OFICIALAtualizada há 3 anos
Como posso solucionar problemas de logs do CloudWatch ausentes para APIs REST do API Gateway?
AWS OFICIALAtualizada há 2 anos
Como resolvo erros de “Permissões inválidas na função do Lambda” das APIs REST do API Gateway?
AWS OFICIALAtualizada há 2 anos