Invocar funções do AWS Lambda

O Amazon Connect pode interagir com seus próprios sistemas e tomar diferentes caminhos em fluxos dinamicamente. Para fazer isso, invoque as funções do AWS Lambda em um fluxo, busque resultados e chame seus próprios serviços ou interaja com outros armazenamentos de dados ou serviços da AWS. Para obter mais informações, consulte o Guia do desenvolvedor do AWS Lambda.

Para invocar uma função do Lambda de um fluxo, conclua as tarefas a seguir.

Criar uma função do Lambda

Crie uma função do Lambda, usando qualquer tempo de execução, e configure-a. Para obter mais informações, consulte Conceitos básicos do Lambda no Guia do desenvolvedor do AWS Lambda.

Se você criar a função do Lambda na mesma região que a sua central de atendimento, poderá usar o console do Amazon Connect para adicionar a função do Lambda à sua instância, conforme descrito na próxima tarefa, Adicionar uma função do Lambda à instância do Amazon Connect. Isso adiciona automaticamente permissões de recursos que permitem que o Amazon Connect invoque a função do Lambda. Caso contrário, se a função do Lambda estiver em uma região diferente, você poderá adicioná-la ao seu fluxo usando o designer de fluxo de contato e incluir as permissões de recurso usando o comando add-permission, com uma entidade principal de connect.amazonaws.com e o ARN de sua instância do Amazon Connect. Para obter mais informações, consulte Uso de políticas com base em recursos do AWS Lambda em Guia do desenvolvedor do AWS Lambda.

Adicionar uma função do Lambda à instância do Amazon Connect

Para que seja possível usar uma função do Lambda em um fluxo, você precisa adicioná-lo à instância do Amazon Connect.

Adicionar uma função do Lambda à instância

1. Abra o console do Amazon Connect em https://console.aws.amazon.com/connect.

2. Na página Instâncias, escolha o nome da instância na coluna Alias da instância. Esse nome da instância aparece no URL que você usa para acessar o Amazon Connect.

   

3. No painel de navegação, escolha Fluxos.

4. Na seção AWS Lambda, use a caixa suspensa Function (Função) para selecionar a função a ser adicionada à sua instância.

   dica

   O menu suspenso lista apenas as funções que estão na mesma região de sua instância. Se não houver funções na lista, selecione Criar uma função do Lambda, que abre o console do AWS Lambda.

   Para usar um Lambda em uma região ou conta diferente, em Invocar função do AWS Lambda , em Selecionar uma função, você pode inserir o ARN de um Lambda. Em seguida, configure a política baseada em recursos correspondente nesse Lambda para permitir que o fluxo o chame.

   Para chamar lambda:AddPermission, você precisa:

   • Definir a entidade principal como connect.amazonaws.com

   • Definir a conta de origem como a conta em que sua instância está.

   • Definir o ARN de origem como o ARN da sua instância.

   Para obter mais informações, consulte Conceder o acesso de função a outras contas.

5. Escolha Adicionar função do Lambda. Confirme se o ARN da função é adicionado em Lambda Functions (Funções Lambda).

Agora você pode fazer referência a essa função do Lambda em seus fluxos.

Invocar uma função do Lambda em um fluxo

1. Abra ou crie um fluxo.

2. Adicione um bloco Invocar função do AWS Lambda (no grupo Integrate (Integrar)) à grade. Conecte as ramificações ao bloco e vice-versa.

3. Escolha o título do bloco Invocar função do AWS Lambda para abrir a respectiva página de propriedades.

4. Em Select a function (Selecionar uma função), escolha na lista de funções que você adicionou à instância.

5. (Opcional) Em Function input parameters (Parâmetros de entrada de função), escolha Add a parameter (Adicionar um parâmetro). Você pode especificar pares chave-valor que são enviados para a função do Lambda quando ela é invocada. Você também pode especificar um valor de Timeout (Tempo limite) para a função.

6. Em Tempo limite (máximo de 8 segundos), especifique quanto tempo aguardar o tempo limite do Lambda. Após esse período, o contato desce pela ramificação de erro.

Em cada invocação da função do Lambda de um fluxo, passe um conjunto padrão de informações relacionadas ao contato em andamento, bem como quaisquer atributos adicionais definidos na função Parâmetros de entrada da função para o bloco Invocar função do AWS Lambda adicionado ao seu fluxo de contato.

O seguinte é um exemplo de solicitação JSON para uma função do 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"
}

A solicitação é dividida em duas partes:

• Dados de contato: são sempre passados pelo Amazon Connect para todos os contatos. Alguns parâmetros são opcionais.

  Esta seção pode incluir atributos que eram associados anteriormente a um contato, como quando um bloco Definir atributos de contato é usado em um fluxo. Este mapa pode estar vazio se não houver nenhum atributo salvo.

  A imagem a seguir mostra onde esses atributos apareceriam na página de propriedades de Definir atributos de contato.

  

• Parâmetros: são os parâmetros específicos para esta chamada que foram definidos quando você criou a função do Lambda. A imagem a seguir mostra onde esses parâmetros apareceriam na página de propriedades do bloco Invocar função do AWS Lambda.

  

O bloco Invocar Lambda pode receber parâmetros de entrada no formato JSON, acomodando tipos de dados primitivos e JSON aninhado. Veja a seguir um exemplo de uma entrada JSON que pode ser usada no bloco Invocar Lambda.

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

Política de novas tentativas de invocação

Se a invocação do Lambda em um fluxo for limitada, será feita uma nova tentativa de solicitação Também será feita uma nova tentativa se ocorrer uma falha geral do serviço (erro 500).

Quando uma invocação síncrona retorna um erro, o Amazon Connect tenta novamente até três vezes por, no máximo, 8 segundos. Nesse ponto, o fluxo avançará para a ramificação Error (Erro).

Para saber mais sobre como o Lambda faz novas tentativas, consulte Tratamento de erros e novas tentativas automáticas no AWS Lambda.

Invocar várias funções do Lambda

Os clientes ouvem o silêncio enquanto uma função do Lambda é executada. Recomendamos adicionar um bloco Reproduzir mensagem entre as funções para manter os clientes engajados e cientes da interação longa.

Configurar a função do Lambda para analisar o evento

Para passar os atributos e parâmetros sem problemas entre a função do Lambda e o Amazon Connect, configure a função para analisar corretamente a solicitação JSON enviada do bloco Invocar função do AWS Lambda ou Definir atributos de contato e defina qualquer lógica de negócios que deva ser aplicada. Como o JSON será analisado, vai depender do tempo de execução usado para a função.

Por exemplo, o código a seguir mostra como acessar exampleParameterKey1 do bloco Invocar função do AWS Lambda e exampleAttributeKey1 do bloco Definir atributos de contato usando 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
// ...
}            
        

Verificar a resposta da função

dica

Não há suporte para referenciar uma matriz em um fluxo. As matrizes só podem ser usadas em outra função do Lambda.

A resposta da função do Lambda pode ser STRING_MAP ou JSON e precisa ser definida durante a configuração do bloco Invocar função do Lambda AWS no fluxo. Se a validação da resposta for definida como STRING_MAP, a função do Lambda deverá retornar um objeto plano de pares de chave/valor do tipo string. Caso contrário, se a validação da resposta for definida como JSON, a função do Lambda poderá retornar qualquer JSON válido, incluindo JSON aninhado.

A resposta do Lambda pode ser de até 32 KB. Se você não se conectar ao Lambda, a função gerará uma exceção, a resposta não será entendida ou a função do Lambda levará mais tempo do que o limite, o fluxo saltará para o rótulo Error.

Teste a saída retornada da função do Lambda para confirmar que ela será consumida corretamente quando for retornada para o Amazon Connect. O exemplo a seguir mostra uma resposta em 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);
}

Este exemplo mostra uma resposta usando 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

A saída retornada da função deve ser um objeto simples de pares de chave/valor, com valores que incluem apenas caracteres alfanuméricos, traço e sublinhado. O tamanho dos dados retornados deve ser menor que 32 KB de dados UTF-8.

O exemplo a seguir mostra a saída em JSON destas funções do Lambda:

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

Se a validação da resposta for definida como JSON, a função do Lambda poderá retornar até mesmo um JSON aninhado, por exemplo:

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

Você pode retornar qualquer resultado, desde que sejam pares simples de valores-chave.

Consumir a resposta da função do Lambda

Há duas maneiras de usar a resposta da função em seu fluxo. Você pode fazer referência diretamente às variáveis retornadas do Lambda ou armazenar os valores retornados da função como atributos de contato e, em seguida, fazer referência aos atributos armazenados. Quando você usar uma referência externa para a resposta de uma função do Lambda, a referência sempre receberá a resposta da função invocada mais recentemente. Para usar a resposta de uma função antes de uma função subsequente ser invocada, a resposta deve ser salva como um atributo de contato ou passada como um parâmetro para a próxima função.

1. Acessar variáveis diretamente

Se você acessa as variáveis diretamente, pode usá-las em blocos de fluxo, mas elas não são incluídas nos registros de contato. Para acessar essas variáveis diretamente em um bloco de fluxo, adicione o bloco depois do bloco Invocar função do AWS Lambda e faça referência aos atributos conforme mostrado no exemplo a seguir:

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

A imagem a seguir mostra a página Propriedades do bloco Reproduzir mensagem. As variáveis são especificadas no bloco de conversão de texto em fala.

Certifique-se de que o nome especificado para o atributo de origem corresponda ao nome da chave retornada do Lambda.

2. Armazenar as variáveis como atributos de contato

Se você armazenar as variáveis como atributos de contato, poderá usá-las em todo o fluxo e elas serão incluídas nos registros de contato.

Para armazenar os valores retornados como atributos de contato e, em seguida, fazer referência a eles, use um bloco Definir atributos de contato em seu fluxo depois do bloco Invocar função do AWS Lambda. Escolha Usar atributo, Externo para o Tipo. Seguindo o exemplo que estamos usando, defina o Atributo de destino como MyAccountId, defina o atributo como AccountId e faça o mesmo para MyBalance e Saldo. Essa configuração é mostrada na imagem a seguir.

Adicione o endereço como um Source attribute (Atributo de origem) e use returnedContactAddress como a Destination key (Chave de destino). Depois, adicione o CallerType como um Atributo de origem e use o returnedContactType para a Chave de destino, conforme mostrado na imagem a seguir.

Certifique-se de que o nome especificado para o atributo de origem externo corresponda ao nome da chave retornada do Lambda.

Tutorial: criar uma função do Lambda e invocar em um fluxo

Etapa 1: Criar o exemplo do Lambda

1. Faça login no AWS Management Console e abra o console AWS Lambda em https://console.aws.amazon.com/lambda/.

2. No AWS Lambda, escolha Criar função.

3. Escolha Autor do zero, se ainda não estiver selecionado. Em Informações básicas, em Nome da função, insira MyFirstConnectLambda. Para todas as outras opções, aceite os padrões. Essas opções são mostradas na imagem a seguir do console do AWS Lambda.

   

4. Escolha a opção Criar função.

5. Na caixa Origem do código, na guia index.js, exclua o código do modelo do editor de código.

6. Copie e cole o código a seguir no editor de código, como mostra a imagem a seguir:

   

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

   Esse código vai gerar um resultado aleatório para o customerBalance.

7. Escolha Implantar.

8. Depois de escolher Implantar, escolha Testar para iniciar o editor de teste.

9. Na caixa de diálogo Configurar evento de teste, selecione Criar novo evento. Em Nome do evento, insira ConnectMock como nome do teste.

10. Na caixa JSON do evento, exclua o código de exemplo e, em vez disso, insira o código a seguir.

    {
    "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. Escolha Save (Salvar).

12. Escolha Test (Testar). Você deverá ver algo semelhante à imagem a seguir:

    

    Seu saldo será diferente. O código gera um número aleatório.

Etapa 2: Adicionar o Lambda ao Amazon Connect

1. Acesse o console do Amazon Connect em https://console.aws.amazon.com/connect/.

2. Escolha o alias de instância do Amazon Connect.

   

3. No menu de navegação, escolha Fluxos.

4. Na seção AWS Lambda, use a caixa suspensa Funções do Lambda para selecionar MyFirstConnectLambda.

   

5. Escolha Adicionar função do Lambda.

Etapa 3: Criar o fluxo de contato

A imagem a seguir é um exemplo do fluxo que você criará usando as etapas deste procedimento. Ela contém os seguintes blocos: Definir atributos de contato, Reproduzir mensagem, Invocar função do AWS Lambda, outro bloco Definir atributos de contato, outro bloco Reproduzir mensagem e, finalmente, um bloco Desconectar.

1. Faça login no site de administração do Amazon Connect em https://nome da instância.my.connect.aws/.

2. No menu de navegação, vá para Roteamento, Fluxos, Criar um fluxo de contato.

3. Arraste um bloco Set contact attributes (Definir atributos do contato) para a grade e configure a página Propriedades mostrada na imagem a seguir:

   

   1. Namespace = Definido pelo usuário.

   2. Atributo = companyName.

   3. Escolha Definir manualmente. Valor = GGG.

   4. Escolha Save (Salvar).

4. Arraste um bloco Play prompt (Reproduzir aviso) para a grade e configure a página Propriedades conforme mostrado na imagem a seguir:

   

   1. Escolha Conversão de texto em fala ou texto de chat, Definir manualmente e defina Interpretar como SSML. Insira o seguinte texto na caixa para que o texto seja falado:

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

   2. Escolha Save (Salvar).

5. Arraste outro bloco Play prompt (Reproduzir aviso) para a grade e configure a página Propriedades conforme mostrado na imagem a seguir:

   

   1. Escolha Conversão de texto em fala ou texto de chat, Definir manualmente e defina Interpretar como Texto. Insira o seguinte texto na caixa para que o texto seja falado:

      Please try again later.

   2. Escolha Save (Salvar).

6. Arraste um bloco Invocar função do AWS Lambda para a grade e configure a página Propriedades conforme mostrado na imagem a seguir:

   

   1. Escolha Selecionar manualmente e, em seguida, escolha MyFirstConnectLambda no menu suspenso.

   2. Na caixa Chave de destino, insira companyName. (Isso é enviado para o Lambda.)

   3. Escolha a caixa Definir dinamicamente

   4. Em Namespace, selecione Definido pelo usuário.

   5. Em Atributo, insira companyName.

   6. Escolha Save (Salvar).

7. Arraste um bloco Set contact attributes (Definir atributos do contato) para a grade, escolha Adicionar outro atributo e configure a página Propriedades conforme mostrado na imagem a seguir:

   

   1. Namespace = Definido pelo usuário. Atributo = MyBalance.

   2. Escolha Definir dinamicamente.

   3. Namespace = Externo.

   4. Atributo = customerBalance. Esse é o resultado do Lambda.

   5. Escolha Add another attribute (Adicionar outro atributo).

   6. Namespace = Definido pelo usuário.

   7. Atributo = MyURL.

   8. Selecione Definir dinamicamente. Namespace = Externo.

   9. Atributo = websiteUrl. Esse é o resultado do Lambda.

   10. Escolha Save (Salvar).

8. Arraste um bloco Play prompt (Reproduzir aviso) para a grade e configure a página Propriedades conforme mostrado na imagem a seguir:

   

   1. Escolha Conversão de texto em fala ou texto de chat e defina Interpretar como como SSML. Insira o seguinte texto na caixa:

      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. Escolha Save (Salvar).

9. Arraste um bloco Disconnect/hang up (Desconectar/desligar) até a grade.

10. Conecte todos os blocos para que seu fluxo se pareça com a imagem mostrada na parte superior deste procedimento.

11. Insira MyFirstConnectFlow como nome e escolha Publicar.

12. No menu de navegação, vá para Canais, Números de telefone.

13. Selecione o número de telefone.

14. Selecione MyFirstConnectFlow e escolha Salvar.

Agora experimente. Ligue para o número. Você deve ouvir uma mensagem de saudação, seu saldo e o site a ser visitado.