Tarefas básicas de uma solicitação de integração da API

Uma solicitação de integração é uma solicitação HTTP que o API Gateway envia para o backend, transmitindo os dados da solicitação enviada pelo cliente e transformação dos dados, se necessário. O método HTTP (ou o verbo) e o URI da solicitação de integração são determinados pelo backend (ou seja, o endpoint de integração). Eles podem ser os mesmos ou diferentes do método HTTP da solicitação de método e do URI, respectivamente.

Por exemplo, quando uma função do Lambda retorna um arquivo que é procurado no Amazon S3, você pode expor essa operação intuitivamente como uma solicitação de método GET para o cliente, embora a solicitação de integração correspondente exija que uma solicitação POST seja usada para invocar a função do Lambda. Para um endpoint HTTP, é provável que a solicitação de método e a solicitação de integração correspondente usem o mesmo verbo HTTP. No entanto, isso não é obrigatório. Você pode integrar a seguinte solicitação de método:

GET /{var}?query=value
Host: api.domain.net

Com a solicitação de integração a seguir:

POST /
Host: service.domain.com
Content-Type: application/json
Content-Length: ...

{
   path: "{var}'s value",
   type: "value"
}

Como desenvolvedor de API, você pode usar qualquer verbo HTTP e URI para que uma solicitação de método atenda aos seus requisitos. No entanto, você deve seguir os requisitos do endpoint de integração. Quando os dados da solicitação de método diferem dos dados da solicitação de integração, você pode reconciliar a diferença ao fornecer mapeamentos dos dados da solicitação de método para os dados da solicitação de integração.

Nos exemplos anteriores, o mapeamento converte a variável de caminho ({var}) e os valores do parâmetro de consulta (query) da solicitação de método GET nos valores das propriedades da carga útil da solicitação de integração de path e type. Outros dados de solicitação mapeáveis incluem cabeçalhos e corpo da solicitação. Eles estão descritos em Configurar mapeamentos de dados de solicitação e resposta usando o console do API Gateway.

Ao configurar a solicitação de integração de proxy HTTP ou o HTTP, você atribui a URL de endpoint HTTP de backend como o valor de URI da solicitação de integração. Por exemplo, na API PetStore, a solicitação, o método para obter uma página de animais de estimação tem o seguinte URI de solicitação de integração:

http://petstore-demo-endpoint.execute-api.com/petstore/pets

Ao configurar o Lambda ou a integração de proxy do Lambda, você atribui o Nome de recurso da Amazon (ARN) para invocar a função do Lambda como o valor da solicitação de integração do URI. Esse Nome de recurso da Amazon (ARN) tem o seguinte formato:

arn:aws:apigateway:api-region:lambda:path//2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations

A parte após arn:aws:apigateway:api-region:lambda:path/, ou seja, /2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations, é o caminho do URI da API REST da ação Invocar do Lambda. Se você usar o console do API Gateway para configurar a integração do Lambda, o API Gateway cria o ARN e o atribui ao URI da integração depois de solicitar a escolha de lambda-function-name a partir de uma região.

Depois de configurar a solicitação de integração com outra ação de serviço da AWS, o URI da solicitação de integração também é um ARN, semelhante à integração com a ação Invoke do Lambda. Por exemplo, para a integração com a ação GetBucket do Amazon S3, o URI da solicitação de integração é um ARN do seguinte formato:

arn:aws:apigateway:api-region:s3:path/{bucket}

O URI da solicitação de integração segue a convenção de caminho para especificar a ação, em que {bucket} é o espaço reservado de um nome de bucket. Como alternativa, uma ação de serviço da AWS pode ser referenciada por seu nome. Usando o nome da ação, o URI da solicitação de integração para a ação GetBucket do Amazon S3 se torna o seguinte:

arn:aws:apigateway:api-region:s3:action/GetBucket

Com a URI da solicitação de integração com base em ação, o nome do bucket ({bucket}) deve ser especificado no corpo da solicitação de integração ({ Bucket: "{bucket}" }), seguindo o formato de entrada da ação GetBucket.

Para integrações da AWS, você também deve configurar credenciais para permitir que o API Gateway chame as ações integradas. Você pode criar uma função nova do IAM ou escolher uma existente para o API Gateway chamar a ação e especificar a função usando seu ARN. Veja a seguir um exemplo desse Nome de recurso da Amazon (ARN):

arn:aws:iam::account-id:role/iam-role-name

Essa função do IAM deve conter uma política para permitir que a ação seja executada. Ela também deve ter o API Gateway declarado (na relação de confiança da função) como uma entidade confiável para assumir a função. Essas permissões podem ser concedidas na própria ação. Elas são conhecidas como permissões com base em recursos. Para a integração do Lambda, você pode chamar a ação addPermission do Lambda para definir as permissões baseadas em recursos e definir credentials como nulas na solicitação de integração do API Gateway.

Já abordamos a configuração de integração básica. As configurações avançadas envolvem dados da solicitação de método de mapeamento para os dados da solicitação de integração. Depois de discutir a configuração básica para uma resposta de integração, abordamos tópicos avançados em Configurar mapeamentos de dados de solicitação e resposta usando o console do API Gateway, onde também abordamos a transmissão da carga útil e o processamento das codificações de conteúdo.