View a markdown version of this page

Obiettivi universali per un bus eventi personalizzato - Amazon EventBridge

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Obiettivi universali per un bus eventi personalizzato

Un target universale richiama un'azione AWS API direttamente da un sottoscrittore, senza alcuna funzione intermedia. Invece di nominare una coda, un argomento o una funzione come destinazione, si assegna un nome al servizio e all'azione API e si scrive la richiesta API che viene EventBridge inviata, come JSON fisso o come espressione JSONata che genera la richiesta dall'evento. Un sottoscrittore può scrivere un elemento in una tabella DynamoDB, inserire un oggetto in un bucket Amazon S3, pubblicarlo su un argomento Amazon SNS o avviare un'esecuzione di Step Functions senza una funzione Lambda nel percorso.

L'ARN di destinazione

Un obiettivo universale TargetArn ha una forma fissa senza regione e senza account:

arn:aws:events:::aws-sdk:service:apiAction
  • serviceè l'identificatore del servizio AWS SDK, che non è sempre il nome familiare del servizio. Ad esempio, Step Functions non lo èsfn. states Esempi che funzionano: sqssns,s3,dynamodb,bedrockagentcore.

  • apiActionè il nome dell'azione API in camelCase con una prima lettera minuscola:, not. putItem PutItem EventBridge cerca il nome esattamente come l'hai scritto nel suo indice delle azioni, che è in camelCase, quindi viene rifiutato CreateSubscriber con il messaggio L'api non PutItem PutItem è valido per il servizio dynamodb. Lo stesso messaggio indica che l'azione non esiste per quel servizio.

Ad esempio, arn:aws:events:::aws-sdk:dynamodb:putItem richiama DynamoDB e arn:aws:events:::aws-sdk:sns:publish richiama PutItem Amazon SNS. Publish

Azioni non supportate

Due tipi di azione non possono essere l'obiettivo di un abbonato e li CreateSubscriber respinge con un messaggio che indica che l'API, o l'intero servizio, non è supportata.

  • Azioni che leggono anziché modificare lo stato, ad esempio quelle i cui nomi iniziano conget,list, o. describe Un evento è legato a qualcosa che è accaduto, quindi un'azione mirata deve cambiare stato. EventBridge mantiene un elenco di nomi e servizi delle azioni bloccate e può aggiungervi altri elementi, ad esempio quando un'azione non si comporta come dovrebbe fare l'obiettivo, quindi un'azione che è stata accettata una volta non è garantita per sempre; considera il messaggio in fase di creazione come l'autorità.

  • Le azioni di EventBridge pubblicazione e. eventbridge:putEvents eventbridge:putPartnerEvents Per inviare eventi a un altro bus di eventi, impostate l'ARN del bus come valoreTargetArn; un Custom Event Bus e un Custom Event Bus - Classic sono entrambi supportati come obiettivi a sé stanti. Consulta Obiettivo del bus dell'evento: da bus a bus.

Parameters

Un obiettivo universale richiedeInvokeConfiguration.UniversalTargetParameters. CreateSubscriberrifiuta un sottoscrittore che lo omette o che fornisce un blocco di parametri diverso, ad esempio. SqsParameters Il messaggio dice che UniversalTargetParameters è previsto. Dai forma alla richiestaInput; un sottoscrittore con destinazione universale non utilizza quella dell'abbonatoTransformer, quindi inserisci qualsiasi trasformazione JSonata. Input

Input (obbligatorio)

La richiesta API, come stringa JSON o come espressione JSONata inclusa che produce la richiesta. {% %} Usa i nomi dei membri del riferimento dell'API di destinazione; per Amazon SQS SendMessage questo è e. QueueUrl MessageBody Fino a 262.144 caratteri.

Quando si crea l'abbonato, un JSON fisso Input viene confrontato con i campi richiesti dall'API e un campo mancante viene rifiutato per nome. Un JSonata Input viene controllato solo per la sintassi, poiché il suo risultato dipende dall'evento, quindi una richiesta che l'API di destinazione rifiuti appare invece al momento della consegna.

InvocationTimeoutSeconds

Quanto tempo EventBridge attende una chiamata API, da 1 a 30 secondi. Il valore predefinito è 30. Deve essere un numero intero letterale; un'espressione JSonata non è accettata qui.

Il ruolo di consegna in RoleArn richiede l'azione IAM per l'API richiamata, ad esempiodynamodb:PutItem, e sqs:SendMessage nella coda delle lettere morte. Per la politica di fiducia del ruolo e il resto delle relative autorizzazioni, consulta. Controllo degli accessi per il Custom Event Bus

Batching e array $events

EventBridge effettua una chiamata API per batch, non una per evento. BatchConfigurationimposta il batch: MaxBatchSize da 1 a 500 e MaxBatchWindowInSeconds da 0 a 300. Un batch si chiude quando raggiunge la dimensione o allo scadere della finestra, a seconda dell'evento che si verifica per primo.

In un JSonataInput, $events è il batch: un array degli eventi in esso contenuti. Con una dimensione del batch pari a 1, $events.Data.orderId restituisce il valore di un evento. Con un batch più grande, indirizzate l'array in modo esplicito, ad esempio con $map and$join, oppure l'espressione produce un array in cui l'API si aspetta una stringa e la consegna ha esito negativo.

MaxBatchSizeImpostate su 1 e MaxBatchWindowInSeconds su 0 per effettuare una chiamata API per ogni evento. Fatelo ogni volta che Input viene impostato un JSON fisso, perché una richiesta fissa è identica per ogni evento del batch e il batch produce una singola chiamata.

Esempio: un elemento DynamoDB per evento

Il sottoscrittore seguente scrive un elemento in una tabella DynamoDB per ogni evento pubblicato conPutRawEvents, prendendo la chiave di partizione dal campo dell'evento. orderId Il ruolo di consegna deve essere dynamodb:PutItem indicato sulla tabella.

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" }'

Per un evento pubblicato conPutEvents, gli stessi campi si trovano indetail:$events.Data.detail.orderId. Consulta Struttura degli eventi: dati, metadati e metadati di sistema.

Quando la chiamata API fallisce

Quando crei il sottoscrittore, EventBridge verifica la forma dell'ARN, verifica che l'azione esista e non sia bloccata e che un fix contenga i campi obbligatori dell'azione e, per un JSonataInput, che l'espressione venga analizzata. Input Non verifica che la risorsa indicata nella richiesta esista o che il ruolo di consegna possa chiamare l'azione. Questi errori si verificano al momento della consegna e ogni tentativo di consegna viene ripetuto dall'abbonatoRetryPolicy, per impostazione predefinita fino a 5 tentativi entro 300 secondi. Quando viene raggiunto un limite, EventBridge scrive un record nella coda delle lettere morte indicando l'ultimo errore. errorCode I codici che un target universale produce più spesso:

  • CUSTOMER_VALIDATION: l'API di destinazione ha rifiutato la richiesta, ad esempio un campo obbligatorio mancante o un valore non compreso nell'intervallo. Il record riporta il messaggio di errore dell'API di destinazione.

  • ACCESS_DENIED: non è EventBridge stato possibile assumere il ruolo di consegna o il ruolo non è autorizzato a richiamare l'azione sulla risorsa. Il record indica quale, in un EventBridge messaggio che nomina il ruolo o la risorsa.

  • RESOURCE_NOT_FOUND: la tabella, l'argomento o l'altra risorsa indicata nella richiesta non esiste.

  • INPUT_TRANSFORMATION_FAILURE: l'espressione JSonata in Input ha generato un errore o non ha prodotto alcun valore.

  • THROTTLING: l'API di destinazione ha limitato la chiamata. REQUEST_TOO_LARGE: la richiesta ha superato il limite di dimensione dell'azione; inferiore. MaxBatchSize EXECUTION_TIMEOUT: la chiamata non è stata restituita entro il timeout.

Per l'elenco completo dei codici di errore, il messaggio riportato su ciascuno di essi e come eseguire il redrive, consulta. Policy di ripetizione dei tentativi e code DLQ Attiva i registri degli abbonati per visualizzare ogni tentativo e l'esatta richiesta inviata; vedi. Osservabilità per il Custom Event Bus: metriche, registri e CloudTrail