Criar uma API privada - Amazon API Gateway
Pré-requisitosEtapa 1: Criar um endpoint da VPC para o API Gateway em sua VPCEtapa 2: Crie uma API privadaEtapa 3: Configurar uma política de recursos para uma API privada(Opcional) Associar ou desassociar um endpoint da VPC a uma API privadaEtapa 4: Implantar uma API privadaSolucionar problemas da API privada

Criar uma API privada

Antes de criar uma API privada, crie um endpoint da VPC para o API Gateway. Depois, crie a API privada e anexe uma política de recursos a ela. Opcionalmente, você pode associar seu endpoint da VPC à API privada para simplificar a invocação da API. Por fim, implante a API.

Os procedimentos a seguir descrevem como fazer isso. Você pode criar uma API REST privada usando o AWS Management Console, a AWS CLI ou um AWS SDK.

Pré-requisitos

Para seguir essas etapas, é necessário ter uma VPC totalmente configurada. Para saber como criar uma VPC, consulte Create a VPC only no Guia do usuário do Amazon VPC. Para seguir todas as etapas recomendadas ao criar uma VPC, habilite o DNS privado. Dessa forma, você pode invocar a API em uma VPC sem precisar passar o host ou o cabeçalho x-apigw-api-id.

Para habilitar o DNS privado, os atributos enableDnsSupport e enableDnsHostnames da sua VPC deverão ser definidos como true. Para obter mais informações, consulte DNS Support in Your VPC e Updating DNS Support for Your VPC.

Etapa 1: Criar um endpoint da VPC para o API Gateway em sua VPC

O procedimento a seguir mostra como criar um endpoint da VPC para o API Gateway. Para criar um endpoint da VPC para o API Gateway, especifique o domínio execute-api para a Região da AWS onde você está criando a API privada. O domínio execute-api é o serviço de componente do API Gateway para a execução da API.

Ao criar um endpoint da VPC para o API Gateway, especifique as configurações de DNS. Se você desativar o DNS privado, só poderá acessar a API usando o DNS público. Para ter mais informações, consulte Problema: não consigo me conectar à minha API pública por um endpoint da VPC do API Gateway.

AWS Management Console
Como criar um endpoint de interface da VPC para o API Gateway

  1. Faça login no AWS Management Console e abra o console da Amazon VPC em https://console.aws.amazon.com/vpc/.

  2. No menu à de navegação, em Nuvem privada virtual, escolha Endpoints.

  3. Escolha Criar endpoint.

  4. (Opcional) Em Etiqueta de nome, insira um nome para ajudar a identificar o endpoint da VPC.

  5. Em Categoria do serviço, escolha Serviços do AWS.

  6. Em Serviços, na barra de pesquisa, insira execute-api. Depois, escolha o endpoint de serviço do API Gateway na Região da AWS em que você criará a API. O nome do serviço deve ser semelhante a com.amazonaws.us-east-1.execute-api e o Tipo deve ser Interface.

  7. Para VPC, escolha a VPC na qual você deseja criar o endpoint.

  8. (Opcional) Para desativar a opção Habilitar nome DNS privado, escolha Configurações adicionais e desmarque a opção Habilitar nome DNS privado.

  9. Em Sub-redes, selecione as zonas de disponibilidade em que criou as interfaces de rede do endpoint. Para melhorar a disponibilidade da sua API, escolha várias sub-redes.

  10. Em Security group (Grupo de segurança), selecione os grupos de segurança a serem associados às interfaces de rede do VPC endpoint.

    O security group que você escolher deve ser definido para permitir o tráfego de entrada de HTTPS na porta TCP 443 a partir de um intervalo de IP na sua VPC ou de outro security group na sua VPC.

  11. Em Política, siga um destes procedimentos:

    • Se você não criou a API privada ou não quer configurar uma política de endpoint da VPC personalizada, escolha Acesso total.

    • Se você já criou uma API privada e quer configurar uma política de endpoint da VPC personalizada, é possível inserir uma política de endpoint da VPC personalizada. Para ter mais informações, consulte Usar políticas de VPC endpoint para APIs privadas no API Gateway.

    Você pode atualizar a política de endpoint da VPC depois de criar o endpoint da VPC. Para obter mais informações, consulte Update a VPC endpoint policy.

  12. Escolha Criar endpoint.

  13. Copie o ID de endpoint da VPC resultante, pois talvez precise usá-lo em etapas futuras.

AWS CLI

O seguinte comando create-vpc-endpoint pode ser usado para criar um endpoint da VPC:

aws ec2 create-vpc-endpoint \
    --vpc-id vpc-1a2b3c4d \
    --vpc-endpoint-type Interface \
    --service-name com.amazonaws.us-east-1.execute-api \
    --subnet-ids subnet-7b16de0c \
    --security-group-id sg-1a2b3c4d

Copie o ID de endpoint da VPC resultante, pois talvez precise usá-lo em etapas futuras.

Etapa 2: Crie uma API privada

Depois de criar o endpoint da VPC, crie uma API REST privada. O procedimento a seguir mostra como criar uma API privada.

AWS Management Console
Para criar uma API privada

  1. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

  2. Selecione Create API (Criar API).

  3. Em REST API, escolha Build (Criar).

  4. Em Nome, insira um nome.

  5. (Opcional) Em Description (Descrição), insira uma descrição.

  6. Em Tipo de endpoint de API, escolha Privado.

  7. (Opcional) Em ID do endpoint da VPC, insira um ID de endpoint da VPC.

    Se você associar um ID de endpoint da VPC à sua API privada, poderá invocar a API de dentro da VPC sem substituir um cabeçalho Host ou transmitir um x-apigw-api-id header. Para obter mais informações, consulte (Opcional) Associar ou desassociar um endpoint da VPC a uma API privada.

  8. Selecione Criar API.

Depois de concluir as etapas anteriores, você poderá seguir as mesmas instruções em Começar a usar o console da API REST para configurar métodos e integrações para essa API, mas não poderá implantar a API. Para implantar a API, siga a etapa 3 e anexe uma política de recursos à API.

AWS CLI

O seguinte comando create-rest-api mostra como criar uma API privada:

aws apigateway create-rest-api \
        --name 'Simple PetStore (AWS CLI, Private)' \
        --description 'Simple private PetStore API' \
        --region us-west-2 \
        --endpoint-configuration '{ "types": ["PRIVATE"] }'

Uma chamada bem-sucedida retorna uma saída semelhante ao seguinte:

{
    "createdDate": "2017-10-13T18:41:39Z",
    "description": "Simple private PetStore API",
    "endpointConfiguration": {
        "types": "PRIVATE"
    },
    "id": "0qzs2sy7bh",
    "name": "Simple PetStore (AWS CLI, Private)"
}

Depois de concluir as etapas anteriores, você poderá seguir as mesmas instruções em Tutorial: Criar uma API REST usando AWS SDKs ou a AWS CLI para configurar métodos e integrações para essa API, mas não poderá implantar a API. Para implantar a API, siga a etapa 3 e anexe uma política de recursos à API.

SDK JavaScript v3

O seguinte exemplo mostra como criar uma API privada usando o AWS SDK para JavaScript v3:

import {APIGatewayClient, CreateRestApiCommand} from "@aws-sdk/client-api-gateway";
const apig = new APIGatewayClient({region:"us-east-1"});

const input = { // CreateRestApiRequest
  name: "Simple PetStore (JavaScript v3 SDK, private)", // required
  description: "Demo private API created using the AWS SDK for JavaScript v3",
  version: "0.00.001",
  endpointConfiguration: { // EndpointConfiguration
    types: [ "PRIVATE"],
  },  
};

export const handler = async (event) => {
const command = new CreateRestApiCommand(input);
try {
  const result = await apig.send(command);
  console.log(result);
} catch (err){
  console.error(err)
 }
};

Uma chamada bem-sucedida retorna uma saída semelhante ao seguinte:

{
  apiKeySource: 'HEADER',
  createdDate: 2024-04-03T17:56:36.000Z,
  description: 'Demo private API created using the AWS SDK for JavaScript v3',
  disableExecuteApiEndpoint: false,
  endpointConfiguration: { types: [ 'PRIVATE' ] },
  id: 'abcd1234',
  name: 'Simple PetStore (JavaScript v3 SDK, private)',
  rootResourceId: 'efg567',
  version: '0.00.001'
}

Depois de concluir as etapas anteriores, você poderá seguir as mesmas instruções em Tutorial: Criar uma API REST usando AWS SDKs ou a AWS CLI para configurar métodos e integrações para essa API, mas não poderá implantar a API. Para implantar a API, siga a etapa 3 e anexe uma política de recursos à API.

Python SDK

O seguinte exemplo mostra como criar uma API privada usando o AWS SDK para Python:

import json
import boto3
import logging

logger = logging.getLogger()
apig = boto3.client('apigateway')

def lambda_handler(event, context):
    try:
      result = apig.create_rest_api(
      name='Simple PetStore (Python SDK, private)',
      description='Demo private API created using the AWS SDK for Python',
      version='0.00.001',
      endpointConfiguration={
          'types': [
             'PRIVATE',
          ],
      },
      )
    except botocore.exceptions.ClientError as error:
            logger.exception("Couldn't create private API %s.", error)
            raise
    attribute=["id", "name", "description", "createdDate", "version", "apiKeySource", "endpointConfiguration"]
    filtered_data ={key:result[key] for key in attribute}
    result = json.dumps(filtered_data, default=str, sort_keys='true')
    return result

Uma chamada bem-sucedida retorna uma saída semelhante ao seguinte:

"{\"apiKeySource\": \"HEADER\", \"createdDate\": \"2024-04-03 17:27:05+00:00\", \"description\": \"Demo private API created using the AWS SDK for \", \"endpointConfiguration\": {\"types\": [\"PRIVATE\"]}, \"id\": \"abcd1234\", \"name\": \"Simple PetStore (Python SDK, private)\", \"version\": \"0.00.001\"}"

Depois de concluir as etapas anteriores, você poderá seguir as mesmas instruções em Tutorial: Criar uma API REST usando AWS SDKs ou a AWS CLI para configurar métodos e integrações para essa API, mas não poderá implantar a API. Para implantar a API, siga a etapa 3 e anexe uma política de recursos à API.

Etapa 3: Configurar uma política de recursos para uma API privada

Sua API privada atual está inacessível para todas as VPCs. Use uma política de recursos para conceder às suas VPCs e endpoints da VPC acesso às suas APIs privadas. É possível conceder acesso a um endpoint da VPC em qualquer conta da AWS.

Sua política de recursos deve conter as condições aws:SourceVpc ou aws:SourceVpce para restringir o acesso. Recomendamos que você identifique VPCs e endpoints da VPC específicos e não crie uma política de recursos que permita acesso a todas as VPCs e endpoints da VPC.

O procedimento a seguir mostra como anexar uma política de recursos à sua API.

AWS Management Console

  1. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

  2. Escolha uma API REST.

  3. No painel de navegação principal, escolha Política de recursos.

  4. Escolha Criar política.

  5. Escolha Selecionar um modelo e selecione Source VPC (VPC de origem).

  6. Substitua {{vpceID}} (incluindo as chaves) por seu ID de endpoint da VPC.

  7. Escolha Salvar alterações.

AWS CLI

O seguinte comando update-rest-api mostra como anexar uma política de recursos a uma API existente:

aws apigateway update-rest-api \
    --rest-api-id a1b2c3 \
    --patch-operations op=replace,path=/policy,value='"{\"jsonEscapedPolicyDocument\"}"'

Talvez você também queira controlar quais recursos têm acesso ao seu endpoint da VPC. Para controlar quais recursos têm acesso ao endpoint da VPC, anexe uma política de endpoint ao endpoint da VPC. Para ter mais informações, consulte Usar políticas de VPC endpoint para APIs privadas no API Gateway.

(Opcional) Associar ou desassociar um endpoint da VPC a uma API privada

Quando você associa um endpoint da VPC a uma API privada, o API Gateway gera um registro DNS de alias do Route 53. Você pode usar esse registro para invocar suas APIs privadas da mesma forma como o faz para suas APIs públicas sem substituir um cabeçalho Host ou transmitir um cabeçalho x-apigw-api-id.

O URL base gerado está no seguinte formato:

https://{rest-api-id}-{vpce-id}.execute-api.{region}.amazonaws.com/{stage}
Associate a VPC endpoint (AWS Management Console)

É possível associar um endpoint da VPC a uma API privada tanto durante a criação quanto depois. O procedimento a seguir mostra como associar um endpoint da VPC a uma API já criada.

Como associar um endpoint da VPC a uma API privada

  1. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

  2. Selecione a API privada.

  3. No painel de navegação principal, escolha Política de recursos.

  4. Edite a política de recursos para permitir chamadas do endpoint da VPC adicional.

  5. No painel de navegação principal, selecione Configurações da API.

  6. Na seção Detalhes da API, escolha Editar.

  7. Em IDs de endpoint da VPC, selecione IDs de endpoint da VPC adicionais.

  8. Escolha Salvar.

  9. Implante a API novamente para que as alterações entrem em vigor.

Dissociate a VPC endpoint (AWS Management Console)
Como dissociar um endpoint da VPC de uma API REST privada

  1. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

  2. Selecione a API privada.

  3. No painel de navegação principal, escolha Política de recursos.

  4. Edite a política de recursos para remover as menções ao endpoint da VPC que você deseja dissociar da API privada.

  5. No painel de navegação principal, selecione Configurações da API.

  6. Na seção Detalhes da API, escolha Editar.

  7. Em IDs de endpoint da VPC, clique no X para dissociar o endpoint da VPC.

  8. Escolha Salvar.

  9. Implante a API novamente para que as alterações entrem em vigor.

Associate a VPC endpoint (AWS CLI)

O seguinte comando create-rest-api mostra como associar endpoints da VPC no momento da criação da API:

aws apigateway create-rest-api \
    --name Petstore \
    --endpoint-configuration '{ "types": ["PRIVATE"], "vpcEndpointIds" : ["vpce-0212a4ababd5b8c3e", "vpce-0393a628149c867ee"] }' \
    --region us-west-2

A saída será exibida da seguinte forma:

{
    "apiKeySource": "HEADER",
    "endpointConfiguration": {
        "types": [
            "PRIVATE"
        ],
        "vpcEndpointIds": [
            "vpce-0212a4ababd5b8c3e",
            "vpce-0393a628149c867ee"
        ]
    },
    "id": "u67n3ov968",
    "createdDate": 1565718256,
    "name": "Petstore"
}

O seguinte comando update-rest-api mostra como associar endpoints da VPC a uma API já criada:

aws apigateway update-rest-api \
    --rest-api-id u67n3ov968 \
    --patch-operations "op='add',path='/endpointConfiguration/vpcEndpointIds',value='vpce-01d622316a7df47f9'" \
    --region us-west-2

A saída será exibida da seguinte forma:

{
    "name": "Petstore",
    "apiKeySource": "1565718256",
    "tags": {},
    "createdDate": 1565718256,
    "endpointConfiguration": {
        "vpcEndpointIds": [
            "vpce-0212a4ababd5b8c3e",
            "vpce-0393a628149c867ee",
            "vpce-01d622316a7df47f9"
        ],
        "types": [
            "PRIVATE"
        ]
    },
    "id": "u67n3ov968"
}

Implante a API novamente para que as alterações entrem em vigor.

Disassociate a VPC endpoint (AWS CLI)

O seguinte comando update-rest-api mostra como desassociar um endpoint da VPC de uma API privada:

aws apigateway update-rest-api \
    --rest-api-id u67n3ov968 \
    --patch-operations "op='remove',path='/endpointConfiguration/vpcEndpointIds',value='vpce-0393a628149c867ee'" \
    --region us-west-2

A saída será exibida da seguinte forma:

{
    "name": "Petstore",
    "apiKeySource": "1565718256",
    "tags": {},
    "createdDate": 1565718256,
    "endpointConfiguration": {
        "vpcEndpointIds": [
            "vpce-0212a4ababd5b8c3e",
            "vpce-01d622316a7df47f9"
        ],
        "types": [
            "PRIVATE"
        ]
    },
    "id": "u67n3ov968"
}

Implante a API novamente para que as alterações entrem em vigor.

Etapa 4: Implantar uma API privada

Para implantar uma API, crie uma implantação de API e a associe a um estágio. O procedimento a seguir mostra como implantar uma API privada.

AWS Management Console
Como implantar uma API privada

  1. Selecione a API.

  2. Escolha Implantar API.

  3. Em Estágio, selecione Novo estágio.

  4. Em Nome do estágio, insira o nome de um estágio.

  5. (Opcional) Em Description (Descrição), insira uma descrição.

  6. Escolha Implantar.

AWS CLI

O seguinte comando create-deployment mostra como implantar uma API privada:

aws apigateway create-deployment --rest-api-id a1b2c3 \ 
  --stage-name test \
  --stage-description 'Private API test stage' \
  --description 'First deployment'

Solucionar problemas da API privada

O tópico a seguir fornece orientações para a solução de erros e problemas que você pode encontrar ao criar uma API privada.

Problema: não consigo me conectar à minha API pública por um endpoint da VPC do API Gateway

Ao criar uma VPC, você pode definir as configurações de DNS. Recomendamos ativar a opção de DNS privado para a VPC. Se você optar por não ativar o DNS privado, só poderá acessar a API via DNS público.

Se você habilitar o DNS privado, não poderá acessar o endpoint padrão de uma API pública do API Gateway pelo endpoint da VPC. É possível acessar uma API com um nome de domínio personalizado.

Se você criar um nome de domínio personalizado regional, use um registro de alias do tipo A; se você criar um nome de domínio personalizado otimizado para bordas, não haverá restrições para o tipo de registro. Você pode acessar essas APIs públicas com o DNS privado habilitado. Para obter mais informações, consulte Issue: I connect to my public API from an API Gateway VPC endpoint.

Problema: minha API retorna {"Message":"User: anonymous is not authorized to perform: execute-api:Invoke on resource: arn:aws:execute-api:us-east-1:********/****/****/"}

Em sua política de recursos, se você definir a entidade principal como uma entidade principal da AWS, como a seguinte:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            ""Principal": {
                "AWS": [
                    "arn:aws:iam::account-id:role/developer",
                    "arn:aws:iam::account-id:role/Admin"
                ]
            },
            "Action": "execute-api:Invoke",
            "Resource": [
                "execute-api:/*"
            ]
        },
        ...
        }

Você deverá usar a autorização AWS_IAM para todos os métodos em sua API, caso contrário, a API retornará a mensagem de erro anterior. Para obter mais instruções sobre como ativar a autorização AWS_IAM para um método, consulte Métodos para APIs REST no API Gateway.

Problema: não consigo saber se meu endpoint da VPC está associado à minha API

Se você associar ou desassociar um endpoint da VPC de sua API privada, será necessário reimplantar a API. A operação de atualização pode levar alguns minutos para ser concluída devido à propagação do DNS. Durante esse período, sua API está disponível, mas a propagação de DNS para os URLs do DNS recém-gerados ainda poderá estar em andamento. Se os novos URLs não estiverem sendo resolvidos no DNS depois de alguns minutos, recomendamos que você reimplante a API.