Destinos da API - Amazon EventBridge
Criar um destino de APIComo criar regras que enviam eventos para um destino de APIPerfil vinculado a serviçoCabeçalhos em solicitaçõesCódigos de erro de destino da APITaxa de invocação e entrega de eventos

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Destinos da API

Os destinos de EventBridge API da Amazon são endpoints HTTP que você pode invocar como alvo de uma regra, semelhante à forma como você invoca um AWS serviço ou recurso como destino. Usando destinos de API, você pode rotear eventos entre AWS serviços, aplicativos integrados de software como serviço (SaaS) e seus aplicativos externos AWS usando chamadas de API. Quando você especifica um destino de API como destino de uma regra, EventBridge invoca o endpoint HTTP para qualquer evento que corresponda ao padrão de evento especificado na regra e, em seguida, entrega as informações do evento com a solicitação. Com EventBridge, você pode usar qualquer método HTTP, exceto CONNECT e TRACE para a solicitação. Os métodos HTTP mais comuns a serem usados são PUT e POST. Também é possível usar transformadores de entrada para personalizar o evento de acordo com os parâmetros de um endpoint HTTP específico. Para ter mais informações, consulte Transformação EventBridge de insumos da Amazon.

nota

Os destinos de API não oferecem suporte a destinos privados, como endpoints VPC de interface, incluindo APIs HTTPS privadas em nuvens privadas virtuais (VPC) usando Network and Application Load Balancer e VPC endpoints de interface.

Para ter mais informações, consulte Usar o Amazon EventBridge com endpoints de interface do Amazon VPC .

Importante

EventBridge as solicitações para um endpoint de destino da API devem ter um tempo limite máximo de execução do cliente de 5 segundos. Se o endpoint de destino levar mais de 5 segundos para responder, o EventBridge tempo limite da solicitação será atingido. EventBridge as novas tentativas atingiram o tempo limite das solicitações até os máximos configurados em sua política de repetição. Por padrão, os máximos são 24 horas e 185 vezes. Após o número máximo de tentativas, os eventos são enviados para sua fila de mensagens não entregues, se você tiver uma. Caso contrário, o evento será descartado.

O seguinte vídeo demonstra o uso do destino da API:

Neste tópico:

Criar um destino de API

Cada destino de API requer uma conexão. Uma conexão determina o tipo de autorização e as credenciais a serem utilizadas para autorização com um endpoint HTTP de destino de API. Também é possível escolher uma conexão existente ou criar uma conexão ao criar um destino de API. Para mais informações, consulte Conexões para destinos de endpoint HTTP.

Para criar um destino de API usando o EventBridge console

  1. Faça login AWS usando uma conta que tenha permissões para gerenciar EventBridge e abrir o EventBridgeconsole.

  2. No painel de navegação à esquerda, escolha Destinos da API.

  3. Role para baixo até a tabela de destinos da API e escolha Criar destino da API.

  4. Na página Criar destino da API, insira um Nome para o destino da API. É possível usar até 64 letras maiúsculas ou minúsculas, números, caracteres de ponto (.), traço (-) ou sublinhado (_).

    O nome deve ser exclusivo na sua conta na sua região atual.

  5. Insira uma Descrição para o destino da API.

  6. Insira um Endpoint de destino da API para o destino da API. O endpoint de destino da API é um destino de endpoint de invocação HTTP para eventos. As informações de autorização que você inclui na conexão usada para esse destino de API são usadas para autorizar esse endpoint. O URL deve usar HTTPS.

  7. Insira o método HTTP a ser usado para se conectar ao endpoint de destino da API.

  8. (Opcional) No campo Limite de taxa de invocação por segundo, insira o número máximo de invocações por segundo a serem enviadas ao endpoint de destino da API.

    O limite de taxa definido pode afetar a forma como os eventos EventBridge são entregues. Para ter mais informações, consulte Como a taxa de invocação afeta a entrega do evento.

  9. Em Conexão, execute um dos seguintes procedimentos:

    • Escolha Usar uma conexão existente e selecione a conexão a ser usada para esse destino de API.

    • Escolha Criar uma nova conexão e insira os detalhes da conexão a ser criada. Para obter mais informações, consulte Conexões.

  10. Selecione Create (Criar).

Como criar regras que enviam eventos para um destino de API

Depois de criar um destino de API, é possível selecioná-lo como destino de uma regra. Para usar um destino de API como destino, você deve fornecer um perfil do IAM com as permissões corretas. Para mais informações, consulte Permissões necessárias EventBridge para acessar destinos usando funções do IAM.

Selecionar um destino de API como um destino faz parte da criação da regra.

Para criar uma regra que envia eventos para um destino de API usando o console

  1. Siga as etapas no procedimento Como criar regras do Amazon EventBridge que reagem a eventos.

  2. Na Selecione destinos etapa, quando solicitado a escolher um destino de API como tipo de destino:

    1. Selecione o destino EventBridge da API.

    2. Execute um destes procedimentos:

      • Escolha Usar um destino de API existente e selecione um destino de API existente

      • Escolha Criar um novo destino de API e especifique a configuração necessária para definir seu novo destino de API.

        Para obter mais informações sobre como especificar as configurações necessárias, consulteCriar um destino de API.

    3. (Opcional): Para especificar parâmetros de cabeçalho para o evento, em Parâmetros de cabeçalho, escolha Adicionar parâmetro de cabeçalho.

      Em seguida, especifique a chave e o valor do parâmetro do cabeçalho.

    4. (Opcional): Para especificar os parâmetros da sequência de caracteres de consulta para o evento, em Parâmetros da sequência de consulta, escolha Adicionar parâmetro da sequência de caracteres de consulta.

      Em seguida, especifique a chave e o valor para o parâmetro da sequência de caracteres de consulta.

  3. Conclua a criação da regra seguindo as etapas do procedimento.

Perfil vinculado ao serviço para destinos de API

Quando você cria uma conexão para um destino de API, uma função vinculada ao serviço chamada AWS ServiceRoleForAmazonEventBridgeApiDestinationsé adicionada à sua conta. EventBridge usa a função vinculada ao serviço para criar e armazenar um segredo no Secrets Manager. Para conceder as permissões necessárias à função vinculada ao serviço, EventBridge anexe a AmazonEventBridgeApiDestinationsServiceRolePolicypolítica à função. A política limita as permissões concedidas somente às necessárias para que o perfil interaja com o segredo da conexão. Nenhuma outra permissão está incluída, e o perfil só pode interagir com as conexões em sua conta para gerenciar o segredo.

A política a seguir é a AmazonEventBridgeApiDestinationsServiceRolePolicy.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "secretsmanager:CreateSecret",
                "secretsmanager:UpdateSecret",
                "secretsmanager:DescribeSecret",
                "secretsmanager:DeleteSecret",
                "secretsmanager:GetSecretValue",
                "secretsmanager:PutSecretValue"
            ],
            "Resource": "arn:aws:secretsmanager:*:*:secret:events!connection/*"
        }
    ]
}

Para obter mais informações sobre os perfis vinculados ao serviço, consulte Como usar perfis vinculados ao serviço na documentação do IAM.

A função AmazonEventBridgeApiDestinationsServiceRolePolicy vinculada ao serviço é suportada nas seguintes regiões: AWS

  • Leste dos EUA (Norte da Virgínia)

  • Leste dos EUA (Ohio)

  • Oeste dos EUA (N. da Califórnia)

  • Oeste dos EUA (Oregon)

  • África (Cidade do Cabo)

  • Ásia-Pacífico (Hong Kong)

  • Ásia-Pacífico (Mumbai)

  • Ásia-Pacífico (Osaka)

  • Ásia-Pacífico (Seul)

  • Ásia-Pacífico (Singapura)

  • Ásia-Pacífico (Sydney)

  • Ásia-Pacífico (Tóquio)

  • Canadá (Central)

  • Europa (Frankfurt)

  • Europa (Irlanda)

  • Europa (Londres)

  • Europa (Milão)

  • Europa (Paris)

  • Europa (Estocolmo)

  • América do Sul (São Paulo)

  • China (Ningxia)

  • China (Pequim)

Cabeçalhos em solicitações para destinos da API

A seção a seguir detalha como EventBridge manipula cabeçalhos HTTP em solicitações para destinos de API.

Cabeçalhos incluídos nas solicitações para destinos de API

Além dos cabeçalhos de autorização definidos para a conexão usada para um destino de API, EventBridge inclui os seguintes cabeçalhos em cada solicitação.

Chave de cabeçalho Valor de cabeçalho

User-Agent

Amazon//EventBridgeApiDestinations

Content-Type

Se nenhum valor personalizado de Content-Type for especificado, EventBridge inclua o seguinte valor padrão como Content-Type:

application/json; charset=utf-8

Intervalo

bytes=0-1048575

Accept-Encoding

gzip,deflate

Conexão

feche

Content-Length

Um cabeçalho de entidade que indica o tamanho do corpo da entidade, em bytes, enviado ao destinatário.

Host

Um cabeçalho de solicitação que especifica o host e o número da porta do servidor para o qual a solicitação está sendo enviada.

Cabeçalhos que não podem ser substituídos em solicitações para destinos de API

EventBridge não permite que você substitua os seguintes cabeçalhos:

  • User-Agent

  • Intervalo

Os cabeçalhos são EventBridge removidos das solicitações para os destinos da API

EventBridge remove os seguintes cabeçalhos para todas as solicitações de destino da API:

  • A-IM

  • Accept-Charset

  • Accept-Datetime

  • Accept-Encoding

  • Cache-Control

  • Conexão

  • Content-Encoding

  • Content-Length

  • Conteúdo-MD5

  • Data

  • Expect

  • Encaminhado

  • De

  • Host

  • HTTP2-Settings

  • If-Match

  • If-Modified-Since

  • If-None-Match

  • If-Range

  • If-Unmodified-Since

  • Max-Forwards

  • Origem

  • Pragma

  • Proxy-Authorization

  • Intervalo

  • Referer

  • TE

  • Trailer

  • Transfer-Encoding

  • User-Agent

  • Upgrade

  • Via

  • Aviso

Códigos de erro de destino da API

Quando EventBridge tenta entregar um evento para um destino de API e ocorre um erro, EventBridge faça o seguinte:

  • Eventos associados aos códigos de erro 409, 429 e 5xx são repetidos.

  • Eventos associados aos códigos de erro 1xx, 2xx, 3xx e 4xx (excluindo 429) não são repetidos.

EventBridge Os destinos da API leem o cabeçalho de resposta HTTP padrão Retry-After para descobrir quanto tempo esperar antes de fazer uma solicitação de acompanhamento. EventBridge escolhe o valor mais conservador entre a política de repetição definida e o Retry-After cabeçalho. Se Retry-After o valor for negativo, EventBridge interrompe a tentativa de entrega desse evento.

Como a taxa de invocação afeta a entrega do evento

Se a taxa de invocação for definida por segundo para um valor muito menor do que o número de invocações geradas, os eventos podem não ser entregues dentro do tempo de repetição de 24 horas para eventos. Por exemplo, se definir a taxa de invocação para 10 invocações por segundo, mas milhares de eventos por segundo forem gerados, você rapidamente terá um acúmulo de eventos para entregar que excede 24 horas. Para garantir que nenhum evento seja perdido, configure uma fila de mensagens não entregues para enviar eventos com invocações com falha para que seja possível processar os eventos posteriormente. Para ter mais informações, consulte Usando filas de cartas mortas para processar eventos não entregues.