Usar operações de API - Guia do desenvolvedor

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á.

Usar operações de API

Anexar uma função do Lambda a um alias de bot

Se você estiver criando um novo alias de bot, use a operação CreateBotAlias para anexar uma função do Lambda. Para anexar uma função do Lambda a um alias de bot existente, use a operação UpdateBotAlias. Modifique o campo botAliasLocaleSettings para conter as configurações corretas:

{
    "botAliasLocaleSettings" : {
        locale: {
            "codeHookSpecification": {
                "lambdaCodeHook": {
                    "codeHookInterfaceVersion": "1.0",
                    "lambdaARN": "arn:aws:lambda:region:account-id:function:function-name"
                }
            },
            "enabled": true
        },
        ...
    }
}

  1. O campo botAliasLocaleSettings é mapeado para um objeto cujas chaves são as localidades nas quais você deseja anexar a função do Lambda. Consulte Idiomas e locais compatíveis para obter uma lista das localidades com suporte e os códigos que são chaves válidas.

  2. Para encontrar o lambdaARN para uma função do Lambda, abra o console do AWS Lambda em https://console.aws.amazon.com/lambda/home, selecione Funções na barra lateral esquerda e escolha a função a ser associada ao alias do bot. No lado direito da Visão geral da função, encontre o lambdaARN em ARN da função. Ele deve conter uma região, o ID da conta e o nome da função.

  3. Para permitir que o Amazon Lex V2 invoque a função do Lambda para o alias, defina o campo enabled como true.

Defina uma intenção de invocar a função do Lambda

Para configurar a invocação da função do Lambda durante uma intenção, use a operação CreateIntent, se estiver criando uma nova intenção ou a operação UpdateIntent, se estiver invocando a função em uma intenção existente. Os campos que controlam a invocação da função do Lambda nas operações de intenção são dialogCodeHook, initialResponseSetting, intentConfirmationSetting e fulfillmentCodeHook.

Se você invocar a função durante a elicitação de um slot, use a operação CreateSlot, se estiver criando um novo slot ou a operação UpdateSlot para invocar a função em um slot existente. O campo que controla a invocação da função do Lambda nas operações do slot é o slotCaptureSetting do objeto valueElicitationSetting.

  1. Para configurar o gancho de código de diálogo do Lambda para ser executado após cada turno da conversa, defina o campo enabled do seguinte objeto DialogCodeHookSettings no campo dialogCodeHook como true:

    "dialogCodeHook": {
    "enabled": boolean
}

  2. Como alternativa, você pode definir o gancho de código de diálogo do Lambda para ser executado somente em pontos específicos das conversas, modificando o codeHook e/ou o campo elicitationCodeHook nas estruturas que correspondem aos estágios da conversa nos quais você deseja invocar a função. Para usar o gancho de código de diálogo do Lambda para cumprimento de intenções, use o campo fulfillmentCodeHook na operação CreateIntent ou UpdateIntent. As estruturas e os usos desses três tipos de ganchos de código são os seguintes:

O campo codeHook define as configurações para que o gancho de código seja executado em um determinado estágio da conversa. É um objeto DialogCodeHookInvocationSetting com a seguinte estrutura:

"codeHook": {
    "active": boolean,
    "enableCodeHookInvocation": boolean,
    "invocationLabel": string,
    "postCodeHookSpecification": PostDialogCodeHookInvocationSpecification object,
}

  • Altere o campo active para true para que o Amazon Lex V2 chame o gancho de código nesse ponto da conversa.

  • Altere o campo enableCodeHookInvocation para true para o Amazon Lex V2 permitir que o gancho de código seja executado normalmente. Se você marcá-lo como false, o Amazon Lex V2 age como se o gancho de código tivesse sido retornado com sucesso.

  • O invocationLabel indica a etapa da caixa de diálogo a partir da qual o gancho de código é invocado.

  • Use o campo postCodeHookSpecification para especificar as ações e mensagens que ocorrem após o gancho de código ser bem-sucedido, falhar ou atingir o tempo limite.

O campo elicitationCodeHook define as configurações para que o gancho de código seja executado no caso de um slot ou slots precisarem ser reutilizados. Esse cenário pode ocorrer se a elicitação do slot falhar ou a confirmação da intenção for negada. O campo elicitationCodeHook é um objeto ElicitationCodeHookInvocationSetting com a seguinte estrutura:

"elicitationCodeHook": {
    "enableCodeHookInvocation": boolean,
    "invocationLabel": string
}

  • Altere o campo enableCodeHookInvocation para true para o Amazon Lex V2 permitir que o gancho de código seja executado normalmente. Se você marcá-lo como false, o Amazon Lex V2 age como se o gancho de código tivesse sido retornado com sucesso.

  • O invocationLabel indica a etapa da caixa de diálogo a partir da qual o gancho de código é invocado.

O campo fulfillmentCodeHook define as configurações do gancho de código a ser executado para cumprir a intenção. Ele é mapeado para o seguinte objeto FulfillmentCodeHookSettings:

"fulfillmentCodeHook": {
    "active": boolean,
    "enabled": boolean,
    "fulfillmentUpdatesSpecification": FulfillmentUpdatesSpecification object,
    "postFulfillmentStatusSpecification": PostFulfillmentStatusSpecification object
}

  • Altere o campo active para true para que o Amazon Lex V2 chame o gancho de código nesse ponto da conversa.

  • Altere o campo enabled para true para o Amazon Lex V2 permitir que o gancho de código seja executado normalmente. Se você marcá-lo como false, o Amazon Lex V2 age como se o gancho de código tivesse sido retornado com sucesso.

  • Use o campo fulfillmentUpdatesSpecification para especificar as mensagens que aparecem para atualizar o usuário durante o cumprimento da intenção e o tempo associado a elas.

  • Use o campo postFulfillmentStatusSpecification para especificar as mensagens e ações que ocorrem após o gancho de código ser bem-sucedido, falhar ou atingir o tempo limite.

Você pode invocar o gancho de código do Lambda nos seguintes pontos de uma conversa definindo os campos active e enableCodeHookInvocation/enabled como true:

Para invocar a função do Lambda na resposta inicial após o reconhecimento da intenção, use a estrutura codeHook no campo initialResponse da operação CreateIntent ou UpdateIntent. O campo initialResponse é mapeado para o seguinte objeto InitialResponseSetting:

"initialResponse": {
    "codeHook": {
        "active": boolean,
        "enableCodeHookInvocation": boolean,
        "invocationLabel": string,
        "postCodeHookSpecification": PostDialogCodeHookInvocationSpecification object,
    },
    "initialResponse": FulfillmentUpdatesSpecification object,
    "nextStep": PostFulfillmentStatusSpecification object,
    "conditional": ConditionalSpecification object
}

Para invocar a função do Lambda depois de obter um valor de slot, use o campo slotCaptureSetting dentro do campo valueElicitation da operação CreateSlot ou UpdateSlot. O campo slotCaptureSetting é mapeado para o seguinte objeto SlotCaptureSetting:

"slotCaptureSetting": {
    "captureConditional": ConditionalSpecification object,
    "captureNextStep": DialogState object,
    "captureResponse": ResponseSpecification object,
    "codeHook": {
        "active": true,
        "enableCodeHookInvocation": true,
        "invocationLabel": string,
        "postCodeHookSpecification": PostDialogCodeHookInvocationSpecification object,
    },
    "elicitationCodeHook": {
        "enableCodeHookInvocation": boolean,
        "invocationLabel": string
    },
    "failureConditional": ConditionalSpecification object,
    "failureNextStep": DialogState object,
    "failureResponse": ResponseSpecification object
}

  • Para invocar a função do Lambda depois que a elicitação do slot for bem-sucedida, use o campo codeHook.

  • Para invocar a função do Lambda depois que a elicitação de slots falhar e o Amazon Lex V2 tentar novamente a elicitação de slots, use o campo elicitationCodeHook.

Para invocar a função do Lambda ao confirmar uma intenção, use o campo intentConfirmationSetting da operação CreateIntent ou UpdateIntent. O campo intentConfirmation é mapeado para o seguinte objeto IntentConfirmationSetting:

"intentConfirmationSetting": {
    "active": boolean,
    "codeHook": {
        "active": boolean,
        "enableCodeHookInvocation": boolean,
        "invocationLabel": string,
        "postCodeHookSpecification": PostDialogCodeHookInvocationSpecification object,
    },
    "confirmationConditional": ConditionalSpecification object,
    "confirmationNextStep": DialogState object,
    "confirmationResponse": ResponseSpecification object,
    "declinationConditional": ConditionalSpecification object,
    "declinationNextStep": FulfillmentUpdatesSpecification object,
    "declinationResponse": PostFulfillmentStatusSpecification object,
    "elicitationCodeHook": {
        "enableCodeHookInvocation": boolean,
        "invocationLabel": string,
    },
    "failureConditional": ConditionalSpecification object,
    "failureNextStep": DialogState object,
    "failureResponse": ResponseSpecification object,
    "promptSpecification": PromptSpecification object
}

  • Para invocar a função do Lambda após o usuário confirmar a intenção e seus slots, use o campo codeHook.

  • Para invocar a função do Lambda depois que o usuário negar a confirmação da intenção e o Amazon Lex V2 tentar novamente a elicitação de slots, use o campo elicitationCodeHook.

Para invocar a função do Lambda para cumprir uma intenção, use o campo fulfillmentCodeHook na operação CreateIntent ou UpdateIntent. O campo fulfillmentCodeHook é mapeado para o seguinte objeto FulfillmentCodeHookSettings:

{
    "active": boolean,
    "enabled": boolean,
    "fulfillmentUpdatesSpecification": FulfillmentUpdatesSpecification object,
    "postFulfillmentStatusSpecification": PostFulfillmentStatusSpecification object
}

3. Depois de definir os estágios da conversa nos quais invocar a função do Lambda, use a operação BuildBotLocale para reconstruir o bot a fim de testar a função.