Trasformazione degli input di Amazon EventBridge Pipes

Amazon EventBridge Pipes supporta trasformatori di input opzionali per il trasferimento dei dati all'arricchimento e alla destinazione. Puoi utilizzare i trasformatori di input per rimodellare il payload di input degli JSON eventi per soddisfare le esigenze del servizio di arricchimento o di destinazione. Per Amazon API Gateway e API destinazioni, ecco come modellare l'evento di input in base al RESTful modello del vostroAPI. I trasformatori di input sono modellati come parametro InputTemplate. Possono essere testo libero, un JSON percorso verso il payload dell'evento o un JSON oggetto che include JSON percorsi in linea verso il payload dell'evento. Per l'arricchimento, il payload di eventi proviene dall'origine. Per le destinazioni, il payload di eventi è ciò che viene restituito dall'arricchimento, se configurato nella pipe. Oltre ai dati specifici del servizio presenti nel payload di eventi, è possibile utilizzare variabili riservate in InputTemplate per fare riferimento ai dati per la pipe.

Per accedere agli elementi in un array, utilizza la notazione con parentesi quadre.

Nota

EventBridge non supporta tutta la sintassi di JSON Path e la valuta in fase di esecuzione. La sintassi supportata include:

• notazione a punti (ad esempio, $.detail)

• trattini

• caratteri di sottolineatura

• caratteri alfanumerici

• indici array

• caratteri jolly (*)

Di seguito sono riportati alcuni InputTemplate parametri di esempio che fanno riferimento a un payload di SQS eventi Amazon:

Stringa statica

InputTemplate: "Hello, sender"

JSONPercorso

InputTemplate: <$.attributes.SenderId>

Stringa dinamica

InputTemplate: "Hello, <$.attributes.SenderId>"

Statico JSON

InputTemplate: >
{
  "key1": "value1",
  "key2": "value2",
  "key3": "value3",
}

Dinamico JSON

InputTemplate: >
{
  "key1": "value1"
  "key2": <$.body.key>,
  "d": <aws.pipes.event.ingestion-time>
}

Per accedere agli elementi in un array con la notazione tra parentesi quadre:

InputTemplate: >
{
  "key1": "value1"
  "key2": <$.body.Records[3]>,
  "d": <aws.pipes.event.ingestion-time>
}

Nota

EventBridge sostituisce i trasformatori di ingresso in fase di esecuzione per garantire un output valido. JSON Per questo motivo, inserite tra virgolette le variabili che fanno riferimento ai parametri del JSON percorso, ma non le virgolette attorno alle variabili che si riferiscono a JSON oggetti o matrici.

Variabili riservate

I modelli di input possono utilizzare le seguenti variabili riservate:

• <aws.pipes.pipe-arn>— L'Amazon Resource Name (ARN) della pipe.

• <aws.pipes.pipe-name>: il nome della pipe.

• <aws.pipes.source-arn>— La ARN fonte dell'evento della pipe.

• <aws.pipes.enrichment-arn>— L'ARNarricchimento della pipa.

• <aws.pipes.target-arn>— Il bersaglio ARN della pipa.

• <aws.pipes.event.ingestion-time>: l'ora alla quale il trasformatore di input ha ricevuto l'evento. Si tratta di un ISO timestamp 8601. Questa ora è diversa per il trasformatore di input di arricchimento e il trasformatore di input di destinazione, a seconda di quando l'arricchimento ha completato l'elaborazione dell'evento.

• <aws.pipes.event>: l'evento come ricevuto dal trasformatore di input.

  Per un trasformatore di input di arricchimento, si tratta dell'evento proveniente dall'origine. Contiene il payload originale dall'origine, nonché altri metadati specifici del servizio. Per esempi specifici del servizio, vedi gli argomenti in Fonti Amazon EventBridge Pipes.

  Per un trasformatore di input di destinazione, si tratta dell'evento restituito dall'arricchimento, se configurato, senza metadati aggiuntivi. Pertanto, un payload restituito dall'arricchimento potrebbe non essere-. JSON Se nessun arricchimento è configurato sulla pipe, questo è l'evento proveniente dall'origine con metadati.

• <aws.pipes.event.json>— Uguale aaws.pipes.event, ma la variabile ha un valore solo se il payload originale, proveniente dalla fonte o restituito dall'arricchimento, è. JSON Se la pipe ha un campo codificato, come il SQS body campo Amazon o data Kinesis, tali campi vengono decodificati e resi validi. JSON Poiché non è escluso, la variabile può essere utilizzata solo come valore per un campo. JSON Per ulteriori informazioni, consulta Analisi implicita dei dati del corpo.

Esempi di trasformazione di input

Di seguito è riportato un esempio di EC2 evento Amazon che possiamo utilizzare come evento di esempio.

{
  "version": "0",
  "id": "7bf73129-1428-4cd3-a780-95db273d1602",
  "detail-type": "EC2 Instance State-change Notification",
  "source": "aws.ec2",
  "account": "123456789012",
  "time": "2015-11-11T21:29:54Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:ec2:us-east-1:123456789012:instance/i-abcd1111"
  ],
  "detail": {
    "instance-id": "i-0123456789",
    "state": "RUNNING"
  }
}
		

Usiamo quanto segue JSON come nostro Transformer.

{
  "instance" : <$.detail.instance-id>,
  "state": <$.detail.state>,
  "pipeArn" : <aws.pipes.pipe-arn>,
  "pipeName" : <aws.pipes.pipe-name>,
  "originalEvent" : <aws.pipes.event.json>
}

Di seguito è riportato l'output risultante:

{
  "instance" : "i-0123456789",
  "state": "RUNNING",
  "pipeArn" : "arn:aws:pipe:us-east-1:123456789012:pipe/example",
  "pipeName" : "example",
  "originalEvent" : {
    ... // commented for brevity
  }
}

Analisi implicita dei dati del corpo

I seguenti campi nel payload in entrata possono essere JSON -escaped, come l'SQSbodyoggetto Amazon, o con codifica base64, come l'oggetto Kinesis. data Sia per il filtraggio che per la trasformazione degli input, EventBridge trasforma questi campi in campi validi in modo da poter fare riferimento direttamente ai sottovalori. JSON Ad esempio, <$.data.someKey> per Kinesis.

Per fare in modo che la destinazione riceva il payload originale senza metadati aggiuntivi, utilizza un trasformatore di input con questi dati del corpo, specifici dell'origine. Ad esempio, <$.body> per Amazon SQS o <$.data> per Kinesis. Se il payload originale è una JSON stringa valida (ad esempio{"key": "value"}), l'uso del trasformatore di input con dati corporei specifici della sorgente comporterà la rimozione delle virgolette all'interno del payload di origine originale. Ad esempio, {"key": "value"} diventerà "{key: value}" quando distribuito alla destinazione. Se il target richiede JSON payload validi (ad esempio, EventBridge Lambda o Step Functions), ciò causerà un errore di consegna. Per fare in modo che la destinazione riceva i dati di origine originali senza generare dati non validiJSON, avvolgi il trasformatore di input dei dati del corpo di origine. JSON Ad esempio, {"data": <$.data>}.

L'analisi implicita del corpo può essere utilizzata anche per immettere dinamicamente i valori della maggior parte dei parametri di destinazione o di arricchimento delle pipe. Per ulteriori informazioni, consulta Parametri di percorso dinamici

Nota

Se il payload originale è validoJSON, questo campo conterrà il payload senza escape, non codificato in base64. JSON Tuttavia, se il payload non è validoJSON, EventBridge base64 codifica per i campi elencati di seguito, ad eccezione di Amazon. SQS

• MQ attivo: data

• Kinesis: data

• Amazon MSK — key e value

• Rabbit MQ: data

• Apache Kafka autogestito: key e value

• Amazon SQS — body

Problemi comuni con la trasformazione di input

Questi sono alcuni problemi comuni che si verificano quando si trasforma l'input in EventBridge pipe:

• Per le stringhe, le virgolette sono obbligatorie.

• Non è prevista alcuna convalida durante la creazione del JSON percorso per il modello.

• Se specifichi una variabile in modo che corrisponda a un JSON percorso che non esiste nell'evento, quella variabile non viene creata e non verrà visualizzata nell'output.

• JSONproprietà come aws.pipes.event.json possono essere utilizzate solo come valore di un JSON campo, non in linea in altre stringhe.

• EventBridge non sfugge ai valori estratti da Input Path, quando compila il modello di input per un target.

• Se un JSON percorso fa riferimento a un JSON oggetto o a un array, ma la variabile è referenziata in una stringa, EventBridge rimuove tutte le virgolette interne per garantire una stringa valida. Ad esempio, «Body is <$.body>» comporterebbe la EventBridge rimozione delle virgolette dall'oggetto.

  Pertanto, se si desidera generare un JSON oggetto basato su una singola variabile di JSON percorso, è necessario posizionarlo come chiave. In questo esempio, {"body": <$.body>}.

• Le virgolette non sono necessarie per le variabili che rappresentano stringhe. Sono consentite, ma EventBridge Pipes aggiunge automaticamente le virgolette ai valori delle variabili di stringa durante la trasformazione, per garantire che l'output della trasformazione sia validoJSON. EventBridge Pipes non aggiunge virgolette alle variabili che rappresentano JSON oggetti o matrici. Non aggiungete virgolette per le variabili che rappresentano JSON oggetti o matrici.

  Ad esempio, il seguente modello di input include variabili che rappresentano sia stringhe che oggetti: JSON

  {
    "pipeArn" : <aws.pipes.pipe-arn>,
    "pipeName" : <aws.pipes.pipe-name>,
    "originalEvent" : <aws.pipes.event.json>
  }

  Risulta valido JSON con la citazione corretta:

  {
    "pipeArn" : "arn:aws:events:us-east-2:123456789012:pipe/example",
    "pipeName" : "example",
    "originalEvent" : {
      ... // commented for brevity
    }
  }

• Per gli arricchimenti o i target Lambda o Step Functions, i batch vengono consegnati alla destinazione come JSON array, anche se la dimensione del batch è 1. Tuttavia, i trasformatori di input verranno comunque applicati ai singoli record dell'JSONarray, non all'intero array. Per ulteriori informazioni, consulta Dosaggio e concorrenza di Amazon EventBridge Pipes.