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á.
# Alvos universais para um barramento de eventos personalizado
Um alvo * universal * invoca uma ação de AWS API diretamente de um assinante, sem nenhuma função intermediária. Em vez de nomear uma fila, tópico ou função como destino, você nomeia o serviço e a ação da API e escreve a solicitação de API que EventBridge envia, como JSON fixo ou como uma expressão JSOnata que cria a solicitação a partir do evento. Um assinante pode gravar um item em uma tabela do DynamoDB, colocar um objeto em um bucket do Amazon S3, publicar em um tópico do Amazon SNS ou iniciar uma execução do Step Functions sem uma função Lambda no caminho.
## O ARN alvo
Um alvo universal `TargetArn` tem um formulário fixo sem região e sem conta:
```
arn:aws:events:::aws-sdk:{{service}}:{{apiAction}}
```
+ {{service}}é o identificador do serviço AWS SDK, que nem sempre é o nome familiar do serviço. Por exemplo, Step Functions é`sfn`, não`states`. Exemplos que funcionam:`sqs`,`sns`,`s3`,`dynamodb`,`bedrockagentcore`.
+ {{apiAction}}é o nome da ação da API em CamelCase com a primeira letra minúscula:, not. `putItem` `PutItem` EventBridge procura o nome exatamente como você o escreveu em seu índice de ações, que está no CamelCase, então `PutItem` é rejeitado `CreateSubscriber` com a mensagem A API não PutItem é válida para * o serviço dynamodb. * A mesma mensagem significa que a ação não existe para esse serviço.
Por exemplo, `arn:aws:events:::aws-sdk:dynamodb:putItem` invoca o DynamoDB e `arn:aws:events:::aws-sdk:sns:publish` invoca o Amazon `PutItem` SNS. `Publish`
## Ações que não são suportadas
Dois tipos de ação não podem ser o alvo de um assinante e os `CreateSubscriber` rejeita com uma mensagem dizendo que a API, ou todo o serviço, não é compatível.
+ Ações que leem em vez de mudar de estado, como aquelas cujos nomes começam com`get`,`list`, ou`describe`. Um evento carrega algo que aconteceu, então uma ação alvo deve mudar de estado. EventBridge mantém uma lista de nomes de ações e serviços bloqueados e pode adicioná-la, por exemplo, quando uma ação não se comporta como o alvo deveria, portanto, uma ação que foi aceita uma vez não é garantida para sempre; trate a mensagem de tempo de criação como autoridade.
+ As ações de EventBridge publicação `eventbridge:putEvents` `eventbridge:putPartnerEvents` e. Para entregar eventos em outro barramento de eventos, defina o ARN do barramento como o`TargetArn`; um barramento de eventos personalizado e um barramento de eventos personalizado - clássico são ambos suportados como alvos por si só. Consulte [Objetivo do ônibus de eventos: ônibus para ônibus](eb-custom-bus-target-bus.md).
## Parâmetros
Um alvo universal exige`InvokeConfiguration.UniversalTargetParameters`. `CreateSubscriber`rejeita um assinante que o omite ou que forneça um bloco de parâmetros diferente, como. `SqsParameters` A mensagem diz que `UniversalTargetParameters` é esperado. Defina a solicitação`Input`; um assinante de destino universal não usa a do assinante`Transformer`, então insira qualquer transformação JSoNata. `Input`
`Input`(obrigatório)
A solicitação da API, como uma string JSON ou como uma expressão JSONata incluída, `{% %}` que produz a solicitação. Use os nomes dos membros da própria referência da API de destino; para o Amazon SQS, `SendMessage` ou seja, `QueueUrl` e. `MessageBody` Até 262.144 caracteres.
Um JSON fixo `Input` é verificado quando você cria o assinante nos campos que a API exige, e um campo ausente é rejeitado pelo nome. A sintaxe de um JSoNata `Input` é verificada somente porque seu resultado depende do evento. Portanto, uma solicitação que a API de destino rejeite aparece no momento da entrega.
`InvocationTimeoutSeconds`
Quanto tempo EventBridge espera por uma chamada de API, de 1 a 30 segundos. O padrão é 30. Esse deve ser um número inteiro literal; uma expressão JSOnata não é aceita aqui.
A função de entrega `RoleArn` precisa da ação do IAM para a API que você invoca`dynamodb:PutItem`, como e `sqs:SendMessage` na fila de cartas mortas. Para ver a política de confiança da função e o restante de suas permissões, consulte[Controle de acesso para o Custom Event Bus](eb-custom-bus-access.md).
## Batching e a matriz `$events`
EventBridge faz uma chamada de API por lote, não uma por evento. `BatchConfiguration`define o lote: `MaxBatchSize` de 1 a 500 e `MaxBatchWindowInSeconds` de 0 a 300. Um lote fecha quando atinge o tamanho ou quando a janela termina, o que ocorrer primeiro.
Em um JSonata`Input`, `$events` é o lote: uma matriz dos eventos nele contidos. Com um tamanho de lote de 1, `$events.Data.orderId` gera o valor de um evento. Com um lote maior, endereça a matriz explicitamente, por exemplo, com `$map` e`$join`, ou a expressão produzirá uma matriz em que a API espera uma string e a entrega falhará.
`MaxBatchSize`Defina como 1 e `MaxBatchWindowInSeconds` como 0 para fazer uma chamada de API para cada evento. Faça isso sempre que o JSON `Input` for fixo, porque uma solicitação fixa é idêntica para cada evento no lote e o lote produz uma única chamada.
## Exemplo: um item do DynamoDB por evento
O assinante a seguir grava um item em uma tabela do DynamoDB para cada evento publicado com`PutRawEvents`, pegando a chave de partição do campo do evento. `orderId` A função de entrega precisa `dynamodb:PutItem` estar na mesa.
```
aws eventsv2 create-subscriber \
--name orders-to-dynamodb \
--event-bus-arn arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef \
--invoke-configuration '{
"TargetArn": "arn:aws:events:::aws-sdk:dynamodb:putItem",
"RoleArn": "arn:aws:iam::111122223333:role/EventBusDeliveryRole",
"UniversalTargetParameters": {
"Input": "{% { \"TableName\": \"orders\", \"Item\": { \"pk\": { \"S\": $events.Data.orderId }, \"total\": { \"N\": $string($events.Data.total) } } } %}"
}
}' \
--batch-configuration MaxBatchSize=1,MaxBatchWindowInSeconds=0 \
--on-failure-configuration '{ "Arn": "arn:aws:sqs:us-east-1:111122223333:orders-to-dynamodb-dlq" }'
```
Para um evento publicado com`PutEvents`, os mesmos campos estão em`detail`:`$events.Data.detail.orderId`. Consulte [Estrutura do evento: dados, metadados e metadados do sistema](eb-custom-bus-addressing.md).
## Quando a chamada da API falha
Quando você cria o assinante, EventBridge verifica a forma do ARN, se a ação existe e não está bloqueada, se um fixo `Input` carrega os campos obrigatórios da ação e, para um JSOnata`Input`, se a expressão analisa. Ele não verifica se o recurso nomeado na solicitação existe ou se a função de entrega pode chamar a ação. Essas falhas acontecem na entrega, e cada falha de entrega é repetida sob a responsabilidade do assinante`RetryPolicy`, por padrão, em até 5 tentativas em 300 segundos. Quando um limite é atingido, EventBridge grava um registro na fila de cartas mortas cujos `errorCode` nomes são a última falha. Os códigos que um alvo universal produz com mais frequência:
+ `CUSTOMER_VALIDATION`: a API de destino rejeitou a solicitação, por exemplo, um campo obrigatório ausente ou um valor fora do intervalo. O registro carrega a mensagem de erro da própria API de destino.
+ `ACCESS_DENIED`: não EventBridge pôde assumir a função de entrega ou a função não tem permissão para chamar a ação no recurso. O registro diz qual, em uma EventBridge mensagem que nomeia a função ou o recurso.
+ `RESOURCE_NOT_FOUND`: a tabela, o tópico ou outro recurso nomeado na solicitação não existe.
+ `INPUT_TRANSFORMATION_FAILURE`: a expressão JSonata em `Input` gerou um erro ou não produziu nenhum valor.
+ `THROTTLING`: a API de destino limitou a chamada. `REQUEST_TOO_LARGE`: a solicitação excedeu o limite de tamanho da ação; menor`MaxBatchSize`. `EXECUTION_TIMEOUT`: a chamada não retornou dentro do tempo limite.
Para ver a lista completa de códigos de erro, a mensagem que cada um carrega e como redirecionar, consulte[Políticas de repetição e filas de cartas mortas](eb-custom-bus-retry.md). Ative os registros de assinantes para ver cada tentativa e a solicitação exata enviada; consulte[Observabilidade do barramento de eventos personalizado: métricas, registros e CloudTrail](eb-custom-bus-observability.md).