教程：从 Power Apps 查询 Azure AI 搜索索引

项目
04/06/2024

使用 Power Apps 的快速应用程序开发环境，针对 Azure AI 搜索中的可搜索内容创建自定义应用。

本教程介绍如何执行下列操作：

连接到 Azure AI 搜索
设置查询请求
在画布应用中将结果可视化

如果没有 Azure 订阅，请在开始前创建一个试用版订阅。

先决条件

Power Apps 帐户
你的搜索服务上托管的 Hotels-sample 索引。
查询 API 密钥。

1 - 创建自定义连接器

Power Apps 中的连接器是一个数据源连接。在此步骤中，创建一个自定义连接器，用于连接到云中的搜索索引。

登录到 Power Apps。
在左侧展开“...更多”。查找、固定，然后选择“自定义连接器”。
选择“+新建自定义连接器”，然后选择“从空白开始创建”。
为自定义连接器命名（例如 AzureSearchQuery），然后选择“继续”。
在“常规”页中输入信息：
- 图标背景色（例如 #007ee5）
- 说明（例如“用于连接 Azure AI 搜索的连接器”）
- 在“主机”中，输入搜索服务 URL（例如 <yourservicename>.search.azure.cn）
- 对于基 URL，请输入“/”
在“安全”页中，将“API 密钥”设置为“身份验证类型”，并将参数标签和参数名称都设置为“api-key”。对于“参数位置”，请选择“标头”，如以下屏幕截图所示。
在“定义”页中选择“+ 新建操作”，创建用于查询索引的操作。输入值“查询”作为操作 ID 的摘要和名称。输入说明，例如“查询搜索索引”。
向下滚动。在“请求”中，选择“+ 从示例导入”按钮，以配置对你的搜索服务的查询请求：
- 选择谓词 GET
- 对于“URL”，请输入对你的搜索索引的示例查询（search=* 返回所有文档，通过 $select= 可选择字段）。 “API 版本”是必需的。完全指定后，URL 可能如下所示：mydemo.search.azure.cn/indexes/hotels-sample-index/docs?search=*&$select=HotelName,Description,Address/City&api-version=2023-11-01。省略 https:// 前缀。
- 对于“标头”，请键入 Content-Type application/json。
  
  Power Apps 使用 URL 中的语法从查询中提取参数：随着向导的进展，search、select 和 api-version 参数将变为可配置。
选择“导入”以自动填充请求。通过单击每个参数旁边的“…”符号来完成参数元数据的设置。每次更新参数后，可选择“后退”以返回到“请求”页。
对于 search：将 * 设置为默认值，将 required 设置为 False，将 visibility 设置为 none。
对于 select：将 HotelName,Description,Address/City 设置为默认值，将 required 设置为 False，将 visibility 设置为 none。
对于 api-version：将 2023-11-01 设置为默认值，将 required 设置为 True，将 visibility 设置为 internal。
对于 Content-Type：设置为 application/json。

进行这些更改后，切换到“Swagger 编辑器”视图。在 parameters 节中，应会看到以下配置：

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: '2023-11-01',
    x-ms-visibility: internal}
  - {name: Content-Type, in: header, required: false, type: string}

切换回向导并返回到“3.定义”步骤。向下滚动到“响应”部分。选择“添加默认响应”。此步骤至关重要，因为它会帮助 Power Apps 了解响应的架构。

粘贴示例响应。通过 Azure 门户中的“搜索浏览器”可以轻松捕获示例响应。在搜索浏览器中，应输入针对请求所提供的相同查询，但还要添加 $top=2，将结果限制为仅包括两个文档：search=*&$select=HotelName,Description,Address/City&$top=2。

Power Apps 只需要几条结果即可检测到架构。现在可以将以下响应复制到向导中，前提是你使用的是 hotels-sample-index。

{
    "@odata.context": "https://mydemo.search.azure.cn/indexes('hotels-sample-index')/$metadata#docs(*)",
    "value": [
        {
            "@search.score": 1,
            "HotelName": "Arcadia 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": "Travel 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"
            }
        }
    ]
}

提示

可以输入的 JSON 响应存在字符限制，因此建议在粘贴 JSON 之前先将其简化。响应的架构和格式比值本身更重要。例如，可以简化“说明”字段，使其仅包含第一个句子。

选择“导入”来添加默认响应。
选择右上角的“创建连接器”来保存定义。
选择“关闭”来关闭连接器。

2 - 测试连接

首次创建连接器时，需从“自定义连接器”列表中将其重新打开，以便对其进行测试。以后，如果进行了更多更新，可在向导中进行测试。

请为此任务提供一个查询 API 密钥。每次创建连接时（无论是针对测试运行还是针对应用中包含的内容），连接器都需要用于连接到 Azure AI 搜索的查询 API 密钥。

在最左侧，选择“自定义连接器”。
在列表中（在本教程中为 "AzureSearchQuery"）找到你的连接器。
选择该连接器，展开操作列表，然后选择“查看属性”。
在操作下拉列表中，选择“6.测试”。
在“测试操作”中，选择“+ 新建连接”。
输入一个查询 API 密钥。这是一个对索引进行只读访问的 Azure AI 搜索查询。可以在 Azure 门户中找到该密钥。
在“操作”中，选择“测试操作”按钮。如果测试成功，应会看到 200 状态，并且在响应正文中，应会看到描述搜索结果的 JSON。

如果测试失败，请重新检查输入。具体而言，请重新访问示例响应，并确保它已正确创建。连接器定义应会显示响应的预期项。

3 - 将结果可视化

在此步骤中，创建一个带有搜索框、搜索按钮和结果显示区域的 Power App。该 Power App 将连接到最近创建的自定义连接器，以从 Azure 搜索中获取数据。

在左侧，展开“应用”>“新建应用”>“从页面设计开始”。
选择带有“电话布局”的空白画布。为应用命名，例如“酒店查找器”。选择“创建”。此时会显示“Power Apps Studio”。
在工作室中，选择“数据”选项卡，选择“添加数据”，然后找到你刚才创建的新连接器。在本教程中，它称为 AzureSearchQuery。选择“添加连接”。

输入查询 API 密钥。

现在，AzureSearchQuery 是可从应用程序使用的数据源。
在“插入”选项卡上，将几个控件添加到画布。
插入以下元素：
- 值为“查询:”的一个文本标签
- 一个文本输入元素（将其命名为 txtQuery，默认值："*"）
- 带有文本“搜索”的一个按钮
- 垂直库（将其命名为 galleryResults）
画布应如下所示：
要使“搜索”按钮发出查询，请将以下操作粘贴到 OnSelect 中：
```
If(!IsBlank(txtQuery.Text),
    ClearCollect(azResult, AzureSearchQuery.Query({search: txtQuery.Text}).value))
```
以下屏幕截图显示了 OnSelect 操作的公式栏。

此操作会导致按钮使用 txtQuery 文本框中的文本作为查询词，使用搜索查询结果更新名为 azResult 的新集合。
注意

如果收到公式语法错误“函数 'ClearCollect' 包含一些无效函数”，请尝试以下解决方法：
- 首先，请确保连接器引用正确。清除连接器名称，然后开始键入连接器的名称。 Intellisense 应会建议正确的连接器和谓词。
- 如果该错误依然出现，请删除并重新创建连接器。如果有多个连接器实例，应用可能会使用错误的实例。
将“垂直库”控件链接到完成上一步骤时创建的 azResult 集合。

选择库控件，并在属性窗格中执行以下操作。
- 将“DataSource”设置为“azResult”。
- 根据索引中的数据类型，选择合适的布局。在本例中，我们使用了“标题、副标题和正文”布局。
- 单击“编辑字段”，并选择要可视化的字段。
由于我们在定义连接器时提供了示例结果，因此该应用能够识别到索引中可用的字段。
按 F5 预览应用。