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á.
# AMAZON.KendraSearchIntent
Para pesquisar documentos indexados com o Amazon Kendra, use a intenção `AMAZON.KendraSearchIntent`. Quando o Amazon Lex V2 não consegue determinar a próxima ação em uma conversa com o usuário, ele aciona a intenção de pesquisa.
O `AMAZON.KendraSearchIntent` está disponível somente em Inglês (EUA) (inglês-EUA) e nas regiões Leste dos EUA (N. da Virgínia), Oeste dos EUA (Oregon) e Europa (Irlanda).
O Amazon Kendra é machine-learning-based um serviço de pesquisa que indexa documentos em linguagem natural, como documentos PDF ou arquivos do Microsoft Word. Ele pode pesquisar documentos indexados e retornar os seguintes tipos de respostas a uma pergunta:
+ Uma resposta
+ Uma entrada de uma pergunta frequente que pode responder à pergunta
+ Um documento relacionado à pergunta
Para ver um exemplo de uso de `AMAZON.KendraSearchIntent`, consulte [Exemplo: criar um bot de perguntas frequentes para um índice do Amazon Kendra.](faq-bot-kendra-search.md).
Se você configurar uma intenção `AMAZON.KendraSearchIntent` para o bot, o Amazon Lex V2 chamará a intenção sempre que não conseguir determinar o enunciado do usuário para uma intenção. Se não houver resposta do Amazon Kendra, a conversa continuará conforme configurado no bot.
**nota**
No momento, o Amazon Lex V2 não oferece suporte ao `AMAZON.KendraSearchIntent` durante a elicitação de slots. Se o Amazon Lex V2 não puder determinar a expressão do usuário para um slot, ele chama o `AMAZON.FallbackIntent`.
Quando `AMAZON.KendraSearchIntent` é usado com o `AMAZON.FallbackIntent` no mesmo bot, o Amazon Lex V2 usa as intenções da seguinte forma:
1. O Amazon Lex V2 chama `AMAZON.KendraSearchIntent`. A intenção chama a operação `Query` do Amazon Kendra.
1. Se o Amazon Kendra retornar uma resposta, o Amazon Lex V2 exibirá o resultado para o usuário.
1. Se não houver resposta do Amazon Kendra, o Amazon Lex V2 avisará novamente o usuário. A próxima ação depende da resposta do usuário.
+ Se a resposta do usuário contiver um enunciado reconhecido pelo Amazon Lex V2, como preencher um valor de slot ou confirmar uma intenção, a conversa com o usuário prosseguirá conforme configurado para o bot.
+ Se a resposta do usuário não contiver um enunciado reconhecido pelo Amazon Lex V2, o Amazon Lex V2 fará outra chamada para a operação `Query`.
1. Se não houver resposta após o número configurado de novas tentativas, o Amazon Lex V2 chamará `AMAZON.FallbackIntent` e encerrará a conversa com o usuário.
Há três maneiras de usar `AMAZON.KendraSearchIntent` para fazer uma solicitação ao Amazon Kendra:
+ Deixe que a intenção da pesquisa faça a solicitação por você. O Amazon Lex V2 chama o Amazon Kendra com o enunciado do usuário como a string de pesquisa. Ao criar a intenção, você pode definir uma string de filtro de consulta que limite o número de respostas retornadas pelo Amazon Kendra. O Amazon Lex V2 usa o filtro na solicitação de consulta.
+ Adicione outros parâmetros de consulta à solicitação para restringir os resultados da pesquisa usando a função do Lambda. Adicione um campo `kendraQueryFilterString` que contém parâmetros de consulta do Amazon Kendra à ação de diálogo `delegate`. Quando parâmetros de consulta são adicionados à solicitação com a função do Lambda, eles têm precedência sobre o filtro de consulta definido quando a intenção foi criada.
+ Crie uma consulta usando a função do Lambda. É possível criar uma solicitação de consulta completa do Amazon Kendra enviada pelo Amazon Lex V2. Especifique a consulta no campo `kendraQueryRequestPayload` na ação de diálogo `delegate`. O campo `kendraQueryRequestPayload` tem precedência sobre o campo `kendraQueryFilterString`.
Para especificar o parâmetro `queryFilterString` ao criar um bot ou especificar o campo `kendraQueryFilterString` ao chamar a ação `delegate` em uma função do Lambda do diálogo, especifique uma string usada como filtro de atributo para a consulta do Amazon Kendra. Se a string não for um filtro de atributo válido, você receberá uma exceção `InvalidBotConfigException` em runtime. Para mais informações sobre filtros de atributo, consulte [Usar atributos de documento para filtrar consultas](https://docs.aws.amazon.com/kendra/latest/dg/filtering.html#search-filtering) no *Guia do desenvolvedor do Amazon Kendra*.
Para ter controle sobre a consulta enviada pelo Amazon Lex V2 para o Amazon Kendra, é possível especificar uma consulta no campo `kendraQueryRequestPayload` na função do Lambda. Se a consulta não for válida, o Amazon Lex V2 retornará uma exceção `InvalidLambdaResponseException`. Para mais informações, consulte a [Operação de consulta](https://docs.aws.amazon.com/kendra/latest/dg/API_Query.html) no *Guia do desenvolvedor do Amazon Kendra*.
Para obter um exemplo de como usar a `AMAZON.KendraSearchIntent`, consulte [Exemplo: criar um bot de perguntas frequentes para um índice do Amazon Kendra.](faq-bot-kendra-search.md).
## Política do IAM para pesquisa Amazon Kendra
Para usar a `AMAZON.KendraSearchIntent` intenção, você deve usar uma função que forneça políticas do AWS Identity and Access Management (IAM) que permitam que o Amazon Lex V2 assuma uma função de tempo de execução que tenha permissão para chamar a intenção do Amazon Kendra. `Query` As configurações do IAM que você usa dependem de você criá-las `AMAZON.KendraSearchIntent` usando o console Amazon Lex V2 ou usando um AWS SDK ou o ( AWS Command Line Interface AWS CLI). Quando o console é usado, é possível escolher entre adicionar permissão para chamar o Amazon Kendra para a função vinculada ao serviço do Amazon Lex V2 ou usar uma função especificamente para chamar a operação `Query` do Amazon Kendra. Ao usar a AWS CLI ou um SDK para criar a intenção, você deve usar uma função específica para chamar a operação. `Query`
### Anexar permissões
É possível usar o console para anexar permissões para acessar a operação `Query` do Amazon Kendra à função vinculada ao serviço padrão do Amazon Lex V2. Quando você anexa permissões à função vinculada ao serviço, não precisa criar e gerenciar uma função de runtime especificamente para se conectar ao índice do Amazon Kendra.
O usuário, a função ou o grupo usado para acessar o console do Amazon Lex V2 deve ter permissões para gerenciar políticas de função. Anexe a política do IAM à função de acesso do console. Quando essas permissões são concedidas, a função tem permissões para alterar a política de função vinculada ao serviço existente.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:AttachRolePolicy",
"iam:PutRolePolicy",
"iam:GetRolePolicy"
],
"Resource": "arn:aws:iam::*:role/aws-service-role/lexv2.amazonaws.com/AWSServiceRoleForLexBots*"
},
{
"Effect": "Allow",
"Action": "iam:ListRoles",
"Resource": "*"
}
]
}
```
------
### Especificar uma função
Você pode usar o console, a AWS CLI ou a API para especificar uma função de tempo de execução a ser usada ao chamar a operação Amazon Kendra. `Query`
O usuário, a função ou o grupo utilizado para especificar a função de runtime deve ter a permissão `iam:PassRole`. A política a seguir define a permissão. É possível usar as chaves de contexto de condição `iam:AssociatedResourceArn` e `iam:PassedToService` para limitar ainda mais o escopo das permissões. Para obter mais informações, consulte [IAM e AWS STS Condition Context Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html) no *Guia do usuário do AWS Identity and Access Management*.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::{{111122223333}}:role/{{role}}"
}
]
}
```
------
A função de runtime que o Amazon Lex V2 precisa usar para chamar o Amazon Kendra deve ter as permissões `kendra:Query`. Quando você usa um perfil do IAM existente para permissão para chamar a operação `Query` do Amazon Kendra, a função deve ter a política a seguir anexada.
Você pode usar o console do IAM, a API do IAM ou o AWS CLI para criar uma política e anexá-la a uma função. Essas instruções usam a CLI da AWS para criar a função e as políticas.
**nota**
O código a seguir é formatado para Linux e MacOS. Para Windows, substitua o caractere de continuação de linha do Linux (\\) pelo circunflexo (^).
**Como adicionar permissão de operação de consulta a uma função**
1. Crie um documento chamado **KendraQueryPolicy.json** no diretório atual, adicione a ele o código a seguir e salve-o.
1. Na AWS CLI, execute o comando a seguir para criar a política do IAM para executar a operação Amazon Kendra. `Query`
```
aws iam create-policy \
--policy-name {{query-policy-name}} \
--policy-document file://KendraQueryPolicy.json
```
1. Anexe a política ao perfil do IAM utilizado para chamar a operação `Query`.
```
aws iam attach-role-policy \
--policy-arn arn:aws:iam::{{account-id}}:policy/{{query-policy-name}}
--role-name {{role-name}}
```
É possível optar por atualizar a função vinculada ao serviço do Amazon Lex V2 ou usar uma função que você criou ao criar o `AMAZON.KendraSearchIntent` para o bot. O procedimento a seguir mostra como escolher o perfil do IAM a ser usado.
**Como especificar a função de runtime para AMAZON.KendraSearchIntent**
1. Faça login no AWS Management Console e abra o console do Amazon Lex em [https://console.aws.amazon.com/lex/](https://console.aws.amazon.com/lex/).
1. Escolha o bot ao qual você deseja adicionar a `AMAZON.KendraSearchIntent`.
1. Escolha o sinal de adição (\+) ao lado de **Intenções**.
1. Em **Adicionar intenção**, escolha **Pesquisar intenções existentes**.
1. Em **Intenções de pesquisa**, insira **AMAZON.KendraSearchIntent** e escolha **Adicionar**.
1. Em **Copiar intenção interna**, insira um nome para a intenção, como **KendraSearchIntent**, e escolha **Adicionar**.
1. Abra a seção **Consulta do Amazon Kendra**.
1. Para **Perfil do IAM**, escolha uma das seguintes opções:
+ Para atualizar a função vinculada ao serviço do Amazon Lex V2 para permitir que o bot consulte índices do Amazon Kendra, escolha **Adicionar permissões do Amazon Kendra**.
+ Para usar uma função que tenha permissão para chamar a operação `Query` do Amazon Kendra, escolha **Usar uma função existente**.
## Usar atributos de solicitação e sessão como filtros
Para filtrar a resposta do Amazon Kendra a itens relacionados à conversa atual, use atributos de sessão e solicitação como filtros adicionando o parâmetro `queryFilterString` ao criar o bot. Especifique um espaço reservado para o atributo ao criar a intenção e, depois, o Amazon Lex V2 substituirá um valor antes de chamar o Amazon Kendra. Para mais informações sobre atributos de solicitação, consulte [Definição de atributos de solicitação para seu bot do Lex V2](context-mgmt-request-attribs.md). Para mais informações sobre atributos de sessão, consulte [Definição de atributos de sessão para seu bot do Lex V2](context-mgmt-session-attribs.md).
Este é um exemplo de um parâmetro `queryFilterString` que usa uma string para filtrar a consulta do Amazon Kendra.
```
"{"equalsTo": {"key": "City", "value": {"stringValue": "Seattle"}}}"
```
Veja a seguir um exemplo de um parâmetro `queryFilterString` que usa um atributo de sessão chamado `"SourceURI"` para filtrar a consulta do Amazon Kendra.
```
"{"equalsTo": {"key": "SourceURI","value": {"stringValue": "[FileURL]"}}}"
```
Veja a seguir um exemplo de parâmetro `queryFilterString` que usa um atributo de solicitação chamado `"DepartmentName"` para filtrar a consulta do Amazon Kendra.
```
"{"equalsTo": {"key": "Department","value": {"stringValue": "((DepartmentName))"}}}"
```
Os filtros `AMAZON.KendraSearchInteng` usam o mesmo formato dos filtros de pesquisa do Amazon Kendra. Para obter mais informações, consulte [Usar atributos de documento para filtrar os resultados da pesquisa](https://docs.aws.amazon.com/kendra/latest/dg/filtering.html#search-filtering) no *Guia do desenvolvedor do Amazon Kendra*.
A string do filtro de consulta usada com o `AMAZON.KendraSearchIntent` deve usar letras minúsculas para a primeira letra de cada filtro. Por exemplo, veja a seguir um filtro de consulta válido para o `AMAZON.KendraSearchIntent`.
```
{
"andAllFilters": [
{
"equalsTo": {
"key": "City",
"value": {
"stringValue": "Seattle"
}
}
},
{
"equalsTo": {
"key": "State",
"value": {
"stringValue": "Washington"
}
}
}
]
}
```
## Usar a resposta da pesquisa
O Amazon Kendra retorna a resposta a uma pesquisa na instrução `IntentClosingSetting` da intenção. A intenção deve ter uma instrução `closingResponse`, a menos que uma função do Lambda produza uma mensagem de resposta de conclusão.
O Amazon Kendra tem cinco tipos de respostas.
+ As duas respostas a seguir exigem que uma pergunta frequente seja configurada para seu índice Amazon Kendra. Para obter mais detalhes, consulte [Adicionar perguntas e respostas diretamente a um índice](https://docs.aws.amazon.com/kendra/latest/dg/in-creating-faq.html).
+ `x-amz-lex:kendra-search-response-question_answer-question-`: a pergunta de uma pergunta frequente correspondente à pesquisa.
+ `x-amz-lex:kendra-search-response-question_answer-answer-`: a resposta de uma pergunta frequente correspondente à pesquisa.
+ As três respostas a seguir exigem que uma fonte de dados seja configurada para seu índice Amazon Kendra. Para obter mais detalhes, consulte [Criação de uma fonte de dados](https://docs.aws.amazon.com/kendra/latest/dg/data-source.html).
+ `x-amz-lex:kendra-search-response-document-`: um trecho de um documento no índice relacionado ao texto do enunciado.
+ `x-amz-lex:kendra-search-response-document-link-`: o URL de um documento no índice relacionado ao texto da declaração.
+ `x-amz-lex:kendra-search-response-answer-`: um trecho de um documento no índice que responde à pergunta.
As respostas são retornadas em atributos `request`. Pode haver até cinco respostas para cada atributo, numeradas de 1 a 5. Para obter mais informações sobre respostas, consulte [Tipos de resposta](https://docs.aws.amazon.com/kendra/latest/dg/response-types.html) no *Guia do desenvolvedor do Amazon Kendra*.
A instrução `closingResponse` deve ter um ou mais grupos de mensagens. Cada grupo de mensagens contém uma ou mais mensagens. Cada mensagem pode conter uma ou mais variáveis de espaço reservado que são substituídas por atributos de solicitação na resposta do Amazon Kendra. Deve haver pelo menos uma mensagem no grupo de mensagens em que todas as variáveis na mensagem são substituídas por valores de atributo de solicitação na resposta de runtime, ou deve haver uma mensagem no grupo sem variáveis de espaço reservado. Os atributos de solicitação são ativados com parênteses duplos ("((" "))"). As mensagens do grupo de mensagens a seguir correspondem a qualquer resposta do Amazon Kendra:
+ “Encontrei uma pergunta de FAQ para você: ((x-amz-lex: kendra-search-response-question \_resposta-pergunta-1)), e a resposta é ((x-amz-lex: \_resposta-resposta-1))” kendra-search-response-question
+ “Encontrei um trecho de um documento útil: ((x-amz-lex: kendra-search-response-document -1))”
+ “Acho que a resposta às suas perguntas é ((x-amz-lex: kendra-search-response-answer -1))”
## Usar uma função do Lambda para gerenciar a solicitação e a resposta
A intenção `AMAZON.KendraSearchIntent` pode usar o hook de código de diálogo e o hook de código de atendimento para gerenciar a solicitação ao Amazon Kendra e a resposta. Utilize a função do Lambda do hook de código de diálogo quando quiser modificar a consulta enviada ao Amazon Kendra e a função do Lambda de hook de código de atendimento quando quiser modificar a resposta.
### Criar uma consulta com o hook de código de diálogo
É possível usar o hook de código de diálogo para criar uma consulta para enviar ao Amazon Kendra. O uso do hook de código de diálogo é opcional. Se você não especificar um hook de código de diálogo, o Amazon Lex V2 criará uma consulta a partir do enunciado do usuário e usará a `queryFilterString` fornecida quando você configurou a intenção, se você a tiver fornecido.
É possível usar dois campos na resposta do hook de código de diálogo para modificar a solicitação ao Amazon Kendra:
+ `kendraQueryFilterString`: use essa string para especificar filtros de atributo para a solicitação do Amazon Kendra. É possível filtrar a consulta usando qualquer um dos campos de índice definidos no índice. Para obter a estrutura da string de filtro, consulte [Usar atributos de documento para filtrar consultas](https://docs.aws.amazon.com/kendra/latest/dg/filtering.html#search-filtering) no *Guia do desenvolvedor do Amazon Kendra*. Se a string de filtro especificada não for válida, você receberá uma exceção `InvalidLambdaResponseException`. A string `kendraQueryFilterString` substitui qualquer string de consulta especificada na `queryFilterString` configurada para a intenção.
+ `kendraQueryRequestPayload`: use essa string para especificar uma consulta do Amazon Kendra. Sua consulta pode usar qualquer um dos atributos do Amazon Kendra. Se você não especificar uma consulta válida, receberá uma exceção `InvalidLambdaResponseException`. Para mais informações, confira [Consulta](https://docs.aws.amazon.com/kendra/latest/dg/API_Query.html) no *Guia do desenvolvedor do Amazon Kendra*.
Depois de criar o filtro ou a sequência de caracteres de consulta, você envia a resposta para o Amazon Lex V2 com o `dialogAction` campo da resposta definido como `delegate`. O Amazon Lex V2 envia a consulta para a Amazon Kendra e, em seguida, retorna a resposta da consulta ao hook do código de atendimento.
### Usar o hook de código de atendimento para a resposta
Depois que o Amazon Lex V2 envia uma consulta ao Amazon Kendra, a resposta da consulta é retornada para a função de cumprimento `AMAZON.KendraSearchIntent` da função do Lambda. O evento de entrada para o hook de código contém a resposta completa do Amazon Kendra. Os dados da consulta estão na mesma estrutura que os retornados pela operação `Query` do Amazon Kendra. Para obter mais informações, consulte [Sintaxe de resposta de consulta](https://docs.aws.amazon.com/kendra/latest/dg/API_Query.html#API_Query_ResponseSyntax) no *Guia do desenvolvedor do Amazon Kendra*.
O hook de código de atendimento é opcional. Se não houver nenhum ou se o hook de código não retornar uma mensagem na resposta, o Amazon Lex V2 usará a instrução `closingResponse` para respostas.