Tutorial: Consultar um índice do Azure AI Search do Power Apps

2025-04-18

Use o ambiente de desenvolvimento rápido de aplicativos do Power Apps para a criação de um aplicativo personalizado para seu conteúdo de pesquisa na Pesquisa do Azure AI.

Neste tutorial, você aprenderá a:

Conectar-se ao Azure AI Search
Configurar uma solicitação de consulta
Visualize resultados em um app canvas

Caso não tenha uma assinatura do Azure, abra uma conta gratuita antes de começar.

Pré-requisitos

Conta do Power Apps com uma licença premium, como, por exemplo, um plano do Power Apps por aplicativo ou um plano do Power Apps por usuário.
Índice de hotels-sample hospedado no seu serviço de pesquisa.
Chave da API de consulta.

1 – Criar um conector personalizado

Um conector no Power Apps é uma conexão de fonte de dados. Nesta etapa, crie um conector personalizado para se conectar a um índice de pesquisa na nuvem.

Entre no Power Apps.
À esquerda, selecione Conectores personalizados.
Selecione + Novo conector personalizado e, em seguida, selecione Criar em branco.
Dê um nome ao seu conector personalizado (por exemplo, AzureSearchQuery) depois selecione Continuar.
Insira as informações na página Geral:
- Cor da tela de fundo do ícone (por exemplo, #007ee5)
- Descrição (por exemplo, "Um conector para o Azure AI Search")
- No host, insira sua URL do serviço de pesquisa (como <yourservicename>.search.windows.net)
- Como URL base, insira "/"
Na Página Segurança, defina Chave da API como o Tipo de Autenticação, defina o rótulo do parâmetro e o nome do parâmetro para api-key. Em Local do parâmetro, selecione Cabeçalho, conforme mostrado na captura de tela a seguir.
Na página Definições, selecione + Nova Ação para criar uma ação que confira o índice. Insira o valor "Consulta" para o resumo e o nome da ID da operação. Insira uma descrição como "Consulta o índice de pesquisa" .
Role para baixo. Em solicitações, selecione + Importar do exemplo para configurar uma solicitação de consulta para o serviço de pesquisa:
- Selecione o verbo GET
- Para a URL, insira uma consulta de exemplo para o índice de pesquisa (search=* retorna todos os documentos, $select= permite que você escolha campos). A versão da API é um campo obrigatório. Totalmente especificada, uma URL pode ser semelhante ao exemplo a seguir. Observe que o https:// prefixo é omitido.
```
mydemo.search.windows.net/indexes/hotels-sample-index/docs?search=*&$select=HotelName,Description,Address/City&api-version=2024-07-01
```
- Para Cabeçalhos, digite Content-Type application/json.
  
  O Power Apps usa a sintaxe na URL para extrair parâmetros da consulta: os parâmetros search, select e api-version se tornam configuráveis à medida que você avança no assistente.
Selecione Importar para preencher automaticamente a Solicitação. Conclua a configuração dos metadados do parâmetro clicando no símbolo ... ao lado de cada um dos parâmetros. Selecione Voltar para retornar à página de solicitação após cada atualização de parâmetro.
Para pesquisar: Defina * como o valor padrão, defina necessário como Falso e defina visibilidade para nenhuma.
Para selecionar: Defina HotelName,Description,Address/City como o valor padrão, defina necessário como Falso e defina visibilidade para nenhuma.
Para api-version: Defina 2024-07-01 como o valor padrão, defina necessário como Verdadeiro e defina visibilidade para interna.
Para Content-Type: Defina como application/json.

Depois de fazer essas alterações, alterne para a exibição do Editor do Swagger. Na seção de parâmetros, você deverá ver a seguinte configuração:

parameters:
  - {name: search, in: query, required: false, type: string, default: '*'}
  - {name: $select, in: query, required: false, type: string, default: 'HotelName,Description,Address/City'}
  - {name: api-version, in: query, required: true, type: string, default: '2024-07-01',
    x-ms-visibility: internal}
  - {name: Content-Type, in: header, required: false, type: string}

Volte para o assistente e retorne para a etapa 3. Etapa de definição. Role para baixo até a seção Resposta. Selecione “Adicionar resposta padrão”. Essa etapa é crítica porque ajuda o Power Apps a compreender o esquema da resposta.

Cole uma resposta de exemplo. Um modo fácil de capturar uma resposta de exemplo é por meio do Gerenciador de Pesquisa no portal do Azure. No Gerenciador de Pesquisa, você deve inserir a mesma consulta que inseriu para a solicitação, mas adicionar $top=2 para restringir os resultados a apenas dois documentos: search=*&$select=HotelName,Description,Address/City&$top=2.

O Power Apps precisa de apenas de alguns resultados para detectar o esquema. Agora você copiar a resposta a seguir para o assistente, supondo que você esteja usando o índice hotels-sample.

{
    "@odata.context": "https://mydemo.search.windows.net/indexes('hotels-sample-index')/$metadata#docs(*)",
    "value": [
        {
            "@search.score": 1,
            "HotelName": "Happy Lake Resort & Restaurant",
            "Description": "The largest year-round resort in the area offering more of everything for your vacation – at the best value!  What can you enjoy while at the resort, aside from the mile-long sandy beaches of the lake? Check out our activities sure to excite both young and young-at-heart guests. We have it all, including being named “Property of the Year” and a “Top Ten Resort” by top publications.",
            "Address": {
                "City": "Seattle"
            }
        },
        {
            "@search.score": 1,
            "HotelName": "Grand Gaming Resort",
            "Description": "The Best Gaming Resort in the area.  With elegant rooms & suites, pool, cabanas, spa, brewery & world-class gaming.  This is the best place to play, stay & dine.",
            "Address": {
                "City": "Albuquerque"
            }
        }
    ]
}

Dica

Há um limite de caractere para a resposta JSON que você pode inserir, portanto, talvez você queira simplificar o JSON antes de colá-lo. O esquema e o formato da resposta são mais importantes do que os valores propriamente ditos. Por exemplo, o campo Descrição pode ser simplificado apenas para a primeira frase.

Selecione Importar para adicionar a resposta padrão.
Selecione Criar conector no canto superior direito para salvar a definição.
Selecione Fechar para fechar o conector.

2 – Testar a conexão

Quando o conector é criado pela primeira vez, você precisa reabri-lo na lista de Conectores Personalizados para testá-lo. Posteriormente, se você fizer mais atualizações, poderá testar de dentro do assistente.

Forneça uma chave de API de consulta para essa tarefa. Cada vez que uma conexão é criada, seja para uma execução de teste ou inclusão em um aplicativo, o conector precisa da chave de API de consulta usada para conexão com o Azure AI Search.

Na extrema esquerda, selecione Conectores Personalizados.
Encontre seu conector na lista (neste tutorial, é "AzureSearchQuery").
Selecione o conector, expanda a lista de ações e selecione Exibir Propriedades.
Na lista suspensa de operações, selecione 6. Testar.
Em Testar Operação, selecione + Nova Conexão.
Insira uma chave de API de consulta. Esta é uma consulta do Azure AI Search para acesso somente leitura a um índice. Você pode encontrar a chave no portal do Azure.
Em Operações, selecione o botão Operação de teste. Se tiver êxito, você verá um status 200 e, no corpo da resposta, deverá ver um JSON que descreve os resultados da pesquisa.

Se o teste falhar, verifique as entradas novamente. Em especial, reanalise a resposta de exemplo e verifique se ela foi criada corretamente. A definição do conector deve mostrar os itens esperados para a resposta.

Se você estiver bloqueado por um erro de política de Prevenção contra Perda de Dados (DLP), examine a mensagem de erro para obter diretrizes. Você pode modificar a política ou tornar o conector não desbloqueável.

3 – Visualizar os resultados

Nesta etapa, crie um Power App com uma caixa de pesquisa, um botão de pesquisa e uma área de exibição para os resultados. O Power App será conectado ao conector personalizado criado recentemente para obter os dados do Azure Search.

No lado esquerdo, expanda Aplicativos>Novo aplicativo>Começar com um design de página.
Selecione uma Tela em branco com o Layout do Telefone. Dê um nome ao aplicativo, como “Localizador de hotel”. Selecione Criar. O Power Apps Studio é exibido.
No estúdio, selecione a guia Dados, selecione Adicionar dados e, a seguir, localize o novo Conector que você acabou de criar. Neste tutorial, ele é chamado de AzureSearchQuery. Selecione Adicionar uma conexão.

Insira a chave de API de consulta.

Agora o AzureSearchQuery é uma fonte de dados que está disponível para ser usada em seu aplicativo.
Na guia Inserir, adicione alguns controles à tela.
Insira os seguintes elementos:
- Um rótulo de texto com o valor "Consulta:"
- Um elemento de entrada de texto (nomeie-o txtQuery, valor padrão: "*")
- Um botão com o texto "Pesquisar"
- Uma galeria vertical chamada (chame-a galleryResults)
A tela deverá ter aparência semelhante à seguinte:
Para fazer com que o botão Pesquisar emita uma consulta, cole a seguinte ação em OnSelect:
```
If(!IsBlank(txtQuery.Text),
    ClearCollect(azResult, AzureSearchQuery.Query({search: txtQuery.Text}).value))
```
A captura de tela a seguir mostra a barra de fórmulas para a ação OnSelect.

Essa ação faz com que o botão atualize uma nova coleção chamada azResult com o resultado da consulta de pesquisa, usando o texto na caixa de texto txtQuery como o termo de consulta.
Observação

Experimente isso se você receber um erro de sintaxe de fórmula "A função 'ClearCollect' tem algumas funções inválidas":
- Primeiro, verifique se a referência do conector está correta. Limpe o nome do conector e comece a digitá-lo. O IntelliSense deverá sugerir o conector e o verbo corretos.
- Se o erro persistir, exclua e recrie o conector. Se houver várias instâncias de um conector, o aplicativo poderá estar usando uma errada.
Vincule o controle Galeria Vertical à coleção azResult que foi criada quando você concluiu a etapa anterior.

Selecione o controle de galeria e execute as ações a seguir no painel de propriedades.
- Defina DataSource como azResult.
- Selecione um Layout que funcione para você com base no tipo de dados no índice. Nesse caso, usamos o layout Título, subtítulo e corpo.
- Escolha Editar Campos e selecione os campos que deseja visualizar.
Já que fornecemos um exemplo de resultado quando definimos o conector, o aplicativo está ciente dos campos disponíveis no índice.
Pressione F5 para visualizar o aplicativo.

Limpar os recursos

Quando você está trabalhando em sua própria assinatura, é uma boa ideia identificar, no final de um projeto, se você ainda precisa dos recursos criados. Recursos deixados em execução podem custar dinheiro. É possível excluir os recursos individualmente ou excluir o grupo de recursos para excluir todo o conjunto de recursos.

Encontre e gerencie recursos no portal do Azure usando o link Todos os recursos ou Grupos de recursos no painel de navegação à esquerda.

Lembre-se de que um serviço de pesquisa gratuito é limitado a três índices, indexadores e fontes de dados. Você pode excluir itens individuais no portal do Azure para permanecer abaixo do limite.

Próximas etapas

O Power Apps permite o desenvolvimento rápido de aplicativos personalizados. Agora que você sabe como se conectar a um índice de pesquisa, saiba mais sobre como criar uma experiência de visualização rica em um Power App personalizado.

Catálogo de aprendizado do Power Apps