Richiamo delle funzioni AWS Lambda

Amazon Connect è in grado di interagire con i sistemi e seguire percorsi differenti nei flussi in modo dinamico. A questo scopo, richiama le funzioni AWS Lambda all'interno del flusso, recupera i risultati e chiama i servizi o interagisci con altri datastore o servizi AWS. Per ulteriori informazioni, consulta la Guida per gli sviluppatori di AWS Lambda.

Per richiamare una funzione Lambda da un flusso, esegui le seguenti operazioni.

Creazione di una funzione Lambda

Crea una funzione Lambda utilizzando qualsiasi runtime e configurala. Per ulteriori informazioni, consulta Nozioni di base su Lambda nella Guida per gli sviluppatori AWS Lambda.

Se crei la funzione Lambda nella stessa regione del contact center, puoi utilizzare la console di Amazon Connect per aggiungere la funzione Lambda all'istanza come descritto nella seguente attività, Aggiunta di una funzione Lambda all'istanza Amazon Connect. Questa operazione aggiunge automaticamente le autorizzazioni sulle risorse che consentono ad Amazon Connect di richiamare la funzione Lambda. In caso contrario, se la funzione Lambda si trova in un'altra regione puoi aggiungerla al flusso dei utilizzando il designer del flusso e aggiungere le autorizzazioni sulle risorse utilizzando il comando add-permission, con il parametro Principale impostato di connect.amazonaws.com e l'ARN dell'istanza Amazon Connect. Per ulteriori informazioni, consulta Utilizzo delle policy basate su risorse per AWS Lambda nella Guida per lo sviluppatore di AWS Lambda.

Aggiunta di una funzione Lambda all'istanza Amazon Connect

Prima di utilizzare una funzione Lambda nel flusso è necessario aggiungerla all'istanza Amazon Connect.

Aggiunta di una funzione Lambda all'istanza

1. Apri la console Amazon Connect all'indirizzo https://console.aws.amazon.com/connect.

2. Nella pagina delle istanze, scegli il nome dell'istanza nella colonna Alias istanza. Questo nome di istanza appare nell'URL che usi per accedere ad Amazon Connect.

   

3. Nel riquadro di navigazione, scegli Flussi.

4. Nella sezione AWS Lambda, utilizza la casella a discesa Function (Funzione) per selezionare la funzione da aggiungere all'istanza.

   Suggerimento

   Il menu a discesa elenca solo le funzioni nella stessa regione dell'istanza. Se non sono elencate funzioni, scegli Crea una nuova funzione Lambda per aprire la console AWS Lambda.

   Per utilizzare una Lambda in una regione o in un account diverso, in Invoca funzione AWS Lambda , sotto Seleziona una funzione, puoi inserire l'ARN di una Lambda. Quindi imposta la policy basata sulle risorse corrispondente su quella Lambda per consentire al flusso di chiamarla.

   Per chiamare lambda:AddPermission, è necessario:

   • impostare il principale su connect.amazonaws.com;

   • impostare l'account di origine come account in cui si trova l'istanza;

   • impostare l'ARN di origine sull'ARN dell'istanza.

   Per ulteriori informazioni, consulta Concessione di accesso alle funzioni ad altri account.

5. Scegli Aggiungi funzione Lambda. Verifica che l'ARN della funzione sia aggiunto sotto la voce Lambda Functions (Funzioni Lambda).

Ora è possibile fare riferimento a quella funzione Lambda nei flussi.

Richiamo di una funzione Lambda da un flusso

1. Apri o crea un flusso.

2. Aggiungi un blocco Invoca funzione AWS Lambda (nel gruppo Integrate (Integrazione)) alla griglia. Collega i rami da e al blocco.

3. Scegli il titolo del blocco Invoca funzione AWS Lambda per aprirne la pagina delle proprietà.

4. In Select a function (Seleziona una funzione), scegli dall'elenco delle funzioni aggiunte all'istanza.

5. (Facoltativo) In Function input parameters (Parametri di input della funzione), scegli Add a parameter (Aggiungi un parametro). È possibile specificare coppie chiave-valore che vengono inviate alla funzione Lambda quando viene richiamata. È possibile anche specificare un valore Timeout per la funzione.

6. In Timeout (massimo 8 secondi), specifica quanto tempo Lambda attende prima del timeout. Trascorso questo tempo, il contatto viene indirizzato verso il ramo Errore.

A ogni invocazione della funzione Lambda da un flusso, è possibile passare un set di informazioni predefinito correlato a un contatto in corso, nonché eventuali attributi aggiuntivi definiti in Parametri di input funzione per il blocco Richiama funzione AWS Lambda aggiunto.

Di seguito è riportato un esempio di richiesta JSON a una funzione Lambda:

{
    "Details": {
        "ContactData": {
            "Attributes": {
               "exampleAttributeKey1": "exampleAttributeValue1"
              },
            "Channel": "VOICE",
            "ContactId": "4a573372-1f28-4e26-b97b-XXXXXXXXXXX",
            "CustomerEndpoint": {
                "Address": "[phone]",
                "Type": "TELEPHONE_NUMBER"
            },
            "CustomerId": "someCustomerId",
            "Description": "someDescription",
            "InitialContactId": "4a573372-1f28-4e26-b97b-XXXXXXXXXXX",
            "InitiationMethod": "INBOUND | OUTBOUND | TRANSFER | CALLBACK",
            "InstanceARN": "arn:aws:connect:aws-region:1234567890:instance/c8c0e68d-2200-4265-82c0-XXXXXXXXXX",
            "LanguageCode": "en-US",
            "MediaStreams": {
                "Customer": {
                    "Audio": {
                        "StreamARN": "arn:aws:kinesisvideo::eu-west-2:111111111111:stream/instance-alias-contact-ddddddd-bbbb-dddd-eeee-ffffffffffff/9999999999999",
                        "StartTimestamp": "1571360125131", // Epoch time value
                        "StopTimestamp": "1571360126131",
                        "StartFragmentNumber": "100" // Numberic value for fragment number 
                    }
                }
            },
            "Name": "ContactFlowEvent",
            "PreviousContactId": "4a573372-1f28-4e26-b97b-XXXXXXXXXXX",
            "Queue": {
                   "ARN": "arn:aws:connect:eu-west-2:111111111111:instance/cccccccc-bbbb-dddd-eeee-ffffffffffff/queue/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
                 "Name": "PasswordReset"
                "OutboundCallerId": {
                    "Address": "[phone]",
                    "Type": "TELEPHONE_NUMBER"
                }
            },
            "References": {
                "key1": {
                    "Type": "url",
                    "Value": "urlvalue"
                }
            },
            "SystemEndpoint": {
                "Address": "[phone]",
                "Type": "TELEPHONE_NUMBER"
            }
        },
        "Parameters": {"exampleParameterKey1": "exampleParameterValue1",
               "exampleParameterKey2": "exampleParameterValue2"
        }
    },
    "Name": "ContactFlowEvent"
}

La richiesta è divisa in due parti:

• Dati di contatto: vengono sempre trasmessi da Amazon Connect per ogni contatto. Alcuni parametri sono opzionali.

  Questa sezione può includere attributi precedentemente associati a un contatto, ad esempio quando si utilizza un blocco Imposta attributi contatti in un flusso. Questa mappa può essere vuota se non esistono attributi salvati.

  L'immagine seguente mostra dove apparirebbero questi attributi nella pagina delle proprietà di un Imposta attributi contatti.

  

• Parametri: si tratta di parametri specifici di questa chiamata che sono stati definiti al momento della creazione della funzione Lambda. L'immagine seguente mostra dove apparirebbero questi parametri nella pagina delle proprietà del blocco Richiama funzione AWS Lambda.

  

Il blocco Richiama Lambda può ricevere parametri di input in formato JSON, adattandosi sia a tipi di dati primitivi che a JSON annidato. Di seguito è riportato un esempio di input JSON che può essere utilizzato nel richiamo del blocco Lambda.

{ 
  "Name": "Jane", 
  "Age":10, 
  "isEnrolledInSchool": true, 
  "hobbies": {
    "books":["book1", "book2"], 
    "art":["art1", "art2"]
  } 
} 
        

Policy per riprovare una chiamata

Se l'invocazione Lambda in un flusso è oggetto di limitazione, la richiesta verrà ritentata. Sarà inoltre riprovata se si verifica un errore di servizio generale (errore 500).

Quando una chiamata sincrona restituisce un errore, Amazon Connect riprova fino a 3 volte, per un massimo di 8 secondi. A quel punto, il flusso procederà verso il basso nel ramo Error (Errore).

Per ulteriori informazioni sui nuovi tentativi di Lambda, consulta Gestione degli errori e nuovi tentativi automatici in AWS Lambda.

Richiamo a più funzioni Lambda

Durante l'esecuzione di una funzione Lambda, i clienti sentono il silenzio. Si consiglia di aggiungere un blocco Riproduci prompt tra le funzioni per mantenerli impegnati e consapevoli della lunga interazione.

Configurazione della funzione Lambda per l'analisi dell'evento

Per passare attributi e parametri tra la funzione Lambda e Amazon Connect, configura la funzione per analizzare correttamente la richiesta JSON inviata dal blocco Richiama funzione AWS Lambda o Imposta attributi contatti e definire l'eventuale logica di business da applicare. La modalità di analisi di JSON dipende dal runtime utilizzato per la funzione.

Ad esempio, il codice seguente mostra come accedere exampleParameterKey1 dal blocco Richiama funzione AWS Lambda e exampleAttributeKey1 dal blocco Imposta attributi contatti utilizzando Node.JS:

exports.handler = function(event, context, callback) {
// Example: access value from parameter (Invoke AWS Lambda function)
let parameter1 = event['Details']['Parameters']['exampleParameterKey1'];
  		  
// Example: access value from attribute (Set contact attributes block)
let attribute1 = event['Details']['ContactData']['Attributes']['exampleAttributeKey1'];
  		  
// Example: access customer's phone number from default data
let phone = event['Details']['ContactData']['CustomerEndpoint']['Address'];
  		  
// Apply your business logic with the values
// ...
}            
        

Verificare la risposta della funzione

Suggerimento

Il riferimento a un array non è supportato in un flusso. Gli array possono essere utilizzati solo in un'altra funzione Lambda.

La risposta della funzione Lambda può essere di tipo STRING_MAP o JSON e deve essere impostata durante la configurazione del blocco Richiama funzione Lambda AWS nel flusso. Se la convalida della risposta è impostata su STRING_MAP, la funzione Lambda dovrebbe restituire un oggetto flat composto da coppie chiave/valore del tipo stringa. Altrimenti, se la convalida della risposta è impostata su JSON, la funzione Lambda può restituire qualsiasi JSON valido, incluso JSON nidificato.

La risposta lambda può arrivare fino a 32 KB. Se non è possibile raggiungere Lambda, la funzione genera un'eccezione, la risposta non è compresa, oppure la funzione Lambda richiede più tempo rispetto al limite, il flusso passa all'etichetta Error.

Verifica l'output restituito dalla funzione Lambda per confermare che verrà correttamente usato quando restituito ad Amazon Connect. L'esempio seguente mostra una richiesta di esempio in Node.JS.

exports.handler = function(event, context, callback) {
// Extract data from the event object	     
let phone = event['Details']['ContactData']['CustomerEndpoint']['Address'];    
	   
// Get information from your APIs

let customerAccountId = getAccountIdByPhone(phone);
let customerBalance = getBalanceByAccountId(customerAccountId);
  		  
    let resultMap = {
        AccountId: customerAccountId,
        Balance: '$' + customerBalance,
}

callback(null, resultMap);
}

Questo esempio mostra invece una risposta di esempio in Python:

def lambda_handler(event, context):
// Extract data from the event object
  phone = event['Details']['ContactData']['CustomerEndpoint']['Address']
  		  
// Get information from your APIs
  customerAccountId = getAccountIdByPhone(phone)
  customerBalance = getBalanceByAccountId(customerAccountId)
  		  
  	resultMap = {
  		"AccountId": customerAccountId,
  		"Balance": '$%s' % customerBalance
  		}
        
 return resultMap

L'output restituito dalla funzione deve essere un oggetto flat di coppie chiave/valore con i valori che includono solo caratteri alfanumerici, trattini e sottolineature. La dimensione dei dati restituiti deve essere inferiore a 32 KB di dati UTF-8.

L'esempio seguente mostra l'output JSON da queste funzioni Lambda.

{
"AccountId": "a12345689",
"Balance": "$1000"
}

Se la convalida della risposta è impostata su JSON, la funzione Lambda può restituire anche un JSON annidato, ad esempio:

{
  "Name": {
      "First": "John",
      "Last": "Doe"
  },
  "AccountId": "a12345689",
  "OrderIds": ["x123", "y123"]
}

È possibile restituire qualsiasi risultato purché si tratti di semplici coppie chiave-valore.

Utilizzo della risposta della funzione Lambda

Ci sono due modi per utilizzare la risposta della funzione nel flusso. È possibile fare riferimento direttamente alle variabili restituite da Lambda o archiviare i valori restituiti dalla funzione come attributi di contatto e quindi fare riferimento agli attributi archiviati. Quando utilizzi un riferimento esterno a una risposta da una funzione Lambda, il riferimento riceverà sempre la risposta dalla funzione richiamata più recente. Per usare la risposta da una funzione prima che venga richiamata una funzione successiva, la risposta deve essere salvata come un attributo di contatto o passata come un parametro alla funzione successiva.

1. Accesso diretto alle variabili

Se accedi alle variabili direttamente, puoi utilizzarle in blocchi di flusso, ma non sono incluse nei record dei contatti. Per accedere a queste variabili direttamente in un blocco di flusso, aggiungi il blocco dopo il blocco Richiama funzione AWS Lambda e quindi fai riferimento agli attributi come mostrato nell'esempio seguente:

Name - $.External.Name
Address - $.External.Address
CallerType - $.External.CallerType

L'immagine seguente mostra la pagina delle proprietà del blocco Riproduci prompt. Le variabili sono specificate nel blocco di sintesi vocale.

Assicurati che il nome specificato per l'attributo di origine corrisponda al nome della chiave restituito da Lambda.

2. Archiviazione di variabili come attributi di contatto

Se archivi le variabili come attributi di contatto, puoi utilizzarle in tutto il flusso di contatti e sono incluse nei record dei contatti.

Per archiviare i valori restituiti come attributi di contatto e quindi fare riferimento a essi, utilizza un blocco Imposta attributi contatti nel flusso dopo il blocco Richiama funzione AWS Lambda. Scegli Usa attributo, Esterno per il Tipo. Seguendo l'esempio, imposta Attributo di destinazione su MyAccountId, imposta l'attributo su AccountId e fai lo stesso per MyBalance e Saldo. Una configurazione di esempio è mostrata nell'immagine seguente.

Aggiungi Indirizzo come un Source Attribute (Attributo origine) e utilizza returnedContactAddress come la Destination key (Chiave di destinazione). Quindi aggiungi CallerType come Attributo origine e utilizza returnedContactType per Chiave di destinazione.

Assicurati che il nome specificato per l'attributo di origine corrisponda al nome della chiave restituito da Lambda.

Tutorial: Creazione di una funzione Lambda e richiamo in un flusso

Passaggio 1: creazione dell'esempio Lambda

1. Accedi alla AWS Management Console e aprire la console di AWS Lambda all'indirizzo https://console.aws.amazon.com/lambda/.

2. In AWS Lambda, scegli Crea funzione.

3. Scegli Crea da zero, se non è già selezionato. In Informazioni di base, per Nome funzione, inserisci MyFirstConnectLambda. Per tutte le altre opzioni, accetta le impostazioni predefinite. Queste opzioni sono mostrate nell'immagine seguente della console AWS Lambda.

   

4. Scegli Create function (Crea funzione).

5. Nella casella Sorgente codice, nella scheda index.js, elimina il codice del modello dall'editor di codice.

6. Copia e incolla il codice seguente nell'editor di codice come mostrato nell'immagine seguente:

   

   exports.handler = async (event, context, callback) => {
   // Extract information
           const customerNumber = event.Details.ContactData.CustomerEndpoint.Address;
           const companyName = event.Details.Parameters.companyName;
   // Fetch data
           const balance = await fetchBalance(customerNumber, companyName);
           const support = await fetchSupportUrl(companyName);
   // Prepare result
           const resultMap = {
           customerBalance: balance,
           websiteUrl: support
           }
           callback(null, resultMap);
           }
           
           async function fetchBalance(customerPhoneNumber, companyName) {
   // Get data from your API Gateway or Database like DynamoDB
           return Math.floor(Math.random() * 1000);
           }
           
           async function fetchSupportUrl(companyName) {
   // Get data from your API Gateway or Database like DynamoDB
           return 'www.GGG.com/support';
           }

   Questo codice genererà un risultato casuale per CustomerBalance.

7. Seleziona Deploy (Implementa).

8. Dopo aver scelto Implementa, scegli Test per avviare l'editor di test.

9. Nella finestra di dialogo Configura evento di test, seleziona Crea nuovo evento. Per Nome evento, immetti ConnectMock come nome del test.

10. Nella casella Evento JSON, elimina il codice di esempio e inserisci invece il codice seguente.

    {
    "Details": {
    "ContactData": {
        "Attributes": {},
        "Channel": "VOICE",
        "ContactId": "4a573372-1f28-4e26-b97b-XXXXXXXXXXX",
        "CustomerEndpoint": {
        "Address": "[phone]",
        "Type": "TELEPHONE_NUMBER"
        },
    "InitialContactId": "4a573372-1f28-4e26-b97b-XXXXXXXXXXX",
    "InitiationMethod": "INBOUND | OUTBOUND | TRANSFER | CALLBACK",
    "InstanceARN": "arn:aws:connect:aws-region:1234567890:instance/c8c0e68d-2200-4265-82c0-XXXXXXXXXX",
    "PreviousContactId": "4a573372-1f28-4e26-b97b-XXXXXXXXXXX",
    "Queue": {
        "ARN": "arn:aws:connect:eu-west-2:111111111111:instance/cccccccc-bbbb-dddd-eeee-ffffffffffff/queue/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "Name": "PasswordReset"
      },
    "SystemEndpoint": {
        "Address": "[phone]",
        "Type": "TELEPHONE_NUMBER"
        } 
    },
    "Parameters": {
        "companyName": "GGG"
        }
    },
    "Name": "ContactFlowEvent"
    }

11. Seleziona Salva.

12. Scegli Test (Esegui test). Dovrebbe essere visualizzato un output simile al seguente:

    

    Il saldo sarà diverso. Il codice genera un numero casuale.

Passaggio 2: Aggiunta della Lambda ad Amazon Connect

1. Vai alla console Amazon Connect all'indirizzo https://console.aws.amazon.com/connect/.

2. Scegli l'alias dell'istanza Amazon Connect.

   

3. Nel menu di navigazione, scegli Flussi.

4. Nella sezione AWS Lambda, utilizza la casella a discesa Funzioni Lambda per selezionare MyFirstConnectLambda.

   

5. Scegli Aggiungi funzione Lambda.

Passaggio 3: creazione di un flusso dei contatti

L'immagine seguente è un esempio del flusso che verrà creato mediante le fasi di questa procedura. Contiene i seguenti blocchi: Imposta attributi contatti, Riproduci prompt, Richiama funzione Lambda AWS, un altro blocco Imposta attributi contatti, un altro blocco Riproduci prompt e infine un blocco Disconnetti.

1. Accedi al sito web dell'amministratore di Amazon Connect all'indirizzo https://instance name.my.connect.aws/.

2. Nel menu di navigazione, vai su Instradamento, Flussi, Crea un flusso di contatti.

3. Trascina un blocco Set contact attributes (Imposta attributi contatti) sulla griglia e configura la pagina delle proprietà mostrata nell'immagine seguente:

   

   1. Namespace = Definito dall'utente.

   2. Attributo = companyName.

   3. Scegli Aggiungi manualmente. Valore = GGG.

   4. Seleziona Salva.

4. Trascina un blocco Play prompt (Riproduci comando) sulla griglia e configura la pagina delle proprietà come mostrato nell'immagine seguente:

   

   1. Scegli Sintesi vocale o testo della chat, Imposta manualmente e imposta Interpreta come su SSML. Inserisci il seguente testo nella casella affinché il testo venga pronunciato:

      Hello, thank you for calling $.Attributes.companyName inc.

   2. Seleziona Salva.

5. Trascina un altro blocco Play prompt (Riproduci comando) sulla griglia e configura la pagina delle proprietà come mostrato nell'immagine seguente:

   

   1. Scegli Sintesi vocale o testo della chat, Imposta manualmente e imposta e imposta Interpreta come su Testo. Inserisci il seguente testo nella casella affinché il testo venga pronunciato:

      Please try again later.

   2. Seleziona Salva.

6. Trascina un blocco Invoca funzione AWS Lambda sulla griglia e configura la pagina delle proprietà come mostrato nell'immagine seguente:

   

   1. Scegli Seleziona manualmente, quindi scegli MyFirstConnectLambda dal menu a discesa.

   2. Nella casella Chiave di destinazione, inserisci companyName. (Questo viene inviato a Lambda.)

   3. Scegli la casella Imposta dinamicamente

   4. Per Namespace, seleziona Definito dall'utente.

   5. Per Attributo, inserisci companyName.

   6. Seleziona Salva.

7. Trascina un blocco Set contact attributes (Imposta attributi contatti) sulla griglia, scegli Aggiungi un altro attributo e configura la pagina delle proprietà come mostrato nell'immagine seguente:

   

   1. Namespace = Definito dall'utente. Attributo = MyBalance.

   2. Scegli Imposta dinamicamente.

   3. Namespace = Esterno.

   4. Attributo = customerBalance. Questo è il risultato di Lambda.

   5. Scegli Add another attribute (Aggiungi un altro attributo).

   6. Namespace = Definito dall'utente.

   7. Attributo = myURL.

   8. Seleziona Imposta dinamicamente. Namespace = Esterno.

   9. Attributo = WebsiteURL. Questo è il risultato di Lambda.

   10. Seleziona Salva.

8. Trascina un blocco Play prompt (Riproduci comando) sulla griglia e configura la pagina delle proprietà come mostrato nell'immagine seguente:

   

   1. Scegli Sintesi vocale o testo della chat e imposta Interpreta come su SSML. Immetti il testo seguente nella casella di testo:

      Your remaining balance is <say-as interpret-as="characters">$.Attributes.MyBalance</say-as>.

      Thank you for calling $.Attributes.companyName.

      Visit $.Attributes.MyURL for more information.

   2. Seleziona Salva.

9. Trascina un blocco Disconnect / hang up (Disconnetti/riaggancia) sulla griglia.

10. Connetti tutti i blocchi in modo che il flusso assomigli all'immagine mostrata all'inizio di questa procedura.

11. Immetti MyFirstConnectFlow come nome, quindi scegli Pubblica.

12. Nel menu di navigazione, vai su Canali, Numeri di telefono.

13. Seleziona il numero di telefono.

14. Seleziona MyFirstConnectFlow e scegli Salva.

Ora provalo. Chiamare il numero. Dovresti sentire un messaggio di saluto, il saldo e il sito web da visitare.