教程:从 Power Apps 查询认知搜索索引Tutorial: Query a Cognitive Search index from Power Apps

利用 Power Apps 的快速应用程序开发环境,针对 Azure 认知搜索中的可搜索内容创建自定义应用。Leverage the rapid application development environment of Power Apps to create a custom app for your searchable content in Azure Cognitive Search.

本教程介绍如何执行下列操作:In this tutorial, you learn how to:

  • 连接到 Azure 认知搜索Connect to Azure Cognitive Search
  • 设置查询请求Set up a query request
  • 在画布应用中将结果可视化Visualize results in a canvas app

如果你没有 Azure 订阅,请在开始之前建立一个试用帐户If you don't have an Azure subscription, open a trial account before you begin.

先决条件Prerequisites

1 - 创建自定义连接器1 - Create a custom connector

Power Apps 中的连接器是一个数据源连接。A connector in Power Apps is a data source connection. 在此步骤中,你将创建一个自定义连接器,用以连接到云中的搜索索引。In this step, you'll create a custom connector to connect to a search index in the cloud.

  1. 登录到 Power Apps。Sign in to Power Apps.

  2. 在左侧,展开“数据” > “自定义连接器”。 On the left, expand Data > Custom Connectors.

    “自定义连接器”菜单

  3. 依次选择“+新建自定义连接器”、“从空白开始创建”。 Select + New custom connector, and then select Create from blank.

    “从空白开始创建”菜单

  4. 为自定义连接器命名(例如 AzureSearchQuery),然后单击“继续”。Give your custom connector a name (for example, AzureSearchQuery), and then click Continue.

  5. 在“常规”页中输入信息:Enter information in the General Page:

    • 图标背景色(例如 #007ee5)Icon background color (for instance, #007ee5)
    • 说明(例如“用于连接 Azure 认知搜索的连接器”)Description (for instance, "A connector to Azure Cognitive Search")
    • 在“主机”中,需要输入搜索服务 URL(例如 <yourservicename>.search.chinacloudapi.cnIn the Host, you will need to enter your search service URL (such as <yourservicename>.search.chinacloudapi.cn)
    • 对于“基 URL”,只需输入“/”For Base URL, simply enter "/"

    “常规信息”对话框

  6. 在“安全”页中,将“API 密钥”设置为“身份验证类型”,并将参数标签和参数名称都设置为“api-key”。In the Security Page, set API Key as the Authentication Type, set both the parameter label and parameter name to api-key. 对于“参数位置”,请选择“标头”,如下所示。For Parameter location, select Header as shown below.

    “身份验证类型”选项

  7. 在“定义”页中,选择“+ 新建操作”以创建用于查询索引的操作。In the Definitions Page, select + New Action to create an action that will query the index. 输入值“查询”作为操作 ID 的摘要和名称。Enter the value "Query" for the summary and the name of the operation ID. 输入说明,例如“查询搜索索引”。Enter a description like "Queries the search index".

    “新建操作”选项

  8. 向下滚动。Scroll down. 在“请求”中,选择“+ 从示例导入”按钮,以配置对你的搜索服务的查询请求:In Requests, select + Import from sample button to configure a query request to your search service:

    • 选择谓词 GETSelect the verb GET

    • 对于“URL”,请输入对你的搜索索引的示例查询(search=* 返回所有文档,$select= 可让你选择字段)。For the URL enter a sample query for your search index (search=* returns all documents, $select= lets you choose fields). “API 版本”是必需的。The API version is required. 完全指定后,URL 可能如下所示:https://mydemo.search.azure.cn/indexes/hotels-sample-index/docs?search=*&$select=HotelName,Description,Address/City&api-version=2019-05-06Fully specified, a URL might look like this: https://mydemo.search.azure.cn/indexes/hotels-sample-index/docs?search=*&$select=HotelName,Description,Address/City&api-version=2019-05-06

    • 对于“标头”,请键入 Content-TypeFor Headers, type Content-Type.

      Power Apps 将使用语法从查询中提取参数。Power Apps will use the syntax to extract parameters from the query. 请注意,我们显式定义了搜索字段。Notice we explicitly defined the search field.

      从示例导入

  9. 单击“导入”以自动填充请求。Click Import to auto-fill the Request. 通过单击每个参数旁边的“…”符号来完成参数元数据的设置。Complete setting the parameter metadata by clicking the ... symbol next to each of the parameters. 每次更新参数后,可以单击“后退”返回到“请求”页。Click Back to return to the Request page after each parameter update.

    “从示例导入”对话框

  10. 对于 search:将 * 设置为默认值,将 required 设置为 False,将 visibility 设置为 none。 For search: Set * as the default value, set required as False and set visibility to none.

    搜索参数元数据

  11. 对于 select:将 HotelName,Description,Address/City 设置为默认值,将 required 设置为 False,将 visibility 设置为 none。 For select: Set HotelName,Description,Address/City as the default value, set required to False, and set visibility to none.

    版本参数元数据

  12. 对于 api-version:将 2019-05-06 设置为默认值,将 required 设置为 True,将 visibility 设置为 internal。 For api-version: Set 2019-05-06 as the default value, set required to True, and set visibility as internal.

    版本参数元数据

  13. 对于 Content-Type:设置为 application/jsonFor Content-Type: Set to application/json.

  14. 进行这些更改后,切换到“Swagger 编辑器”视图。After making these changes, toggle to the Swagger Editor view. 在 parameters 节中,应会看到以下配置:In the parameters section you should see the following configuration:

    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: '2019-05-06',
        x-ms-visibility: internal}
      - {name: Content-Type, in: header, required: false, type: string}
    
  15. 返回到“3.请求”步骤,并向下滚动到“响应”部分。Return to the 3. Request step and scroll down to the Response section. 单击“添加默认响应”。Click "Add default response". 此操作至关重要,因为它会帮助 Power Apps 了解响应的架构。This is critical because it will help Power Apps understand the schema of the response.

  16. 粘贴示例响应。Paste a sample response. 通过 Azure 门户中的“搜索浏览器”可以轻松捕获示例响应。An easy way to capture a sample response is through Search Explorer in the Azure portal. 在“搜索浏览器”中,应该输入针对请求所提供的相同查询,但还要添加 $top=2,以将结果限制为仅包括两个文档:search=*&$select=HotelName,Description,Address/City&$top=2In Search Explorer, you should enter the same query as you did for the request, but add $top=2 to constrain results to just two documents: : search=*&$select=HotelName,Description,Address/City&$top=2.

    Power Apps 只需要几条结果即可检测到架构。Power Apps only needs a few results to detect the schema.

    {
        "@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"
                }
            }
        ]
    }
    

    Tip

    可以输入的 JSON 响应存在字符限制,因此建议在粘贴 JSON 之前先将其简化。There is a character limit to the JSON response you can enter, so you may want to simplify the JSON before pasting it. 响应的架构和格式比值本身更重要。The schema and format of the response is more important than the values themselves. 例如,可以简化“说明”字段,使其仅包含第一个句子。For example, the Description field could be simplified to just the first sentence.

  17. 单击右上角的“创建连接器”。Click Create connector on the top right.

2 - 测试连接2 - Test the connection

首次创建连接器时,需从“自定义连接器”列表中将其重新打开,以便对其进行测试。When the connector is first created, you need to reopen it from the Custom Connectors list in order to test it. 以后如果做出了其他更新,可以在向导中进行测试。Later, if you make additional updates, you can test from within the wizard.

需要使用一个查询 API 密钥来完成此任务。You will need a query API key for this task. 每次创建连接时(无论是针对测试运行还是针对应用中包含的内容),连接器都需要用于连接到 Azure 认知搜索的查询 API 密钥。Each time a connection is created, whether for a test run or inclusion in an app, the connector needs the query API key used for connecting to Azure Cognitive Search.

  1. 在最左侧,单击“自定义连接器”。On the far left, click Custom Connectors.

  2. 按名称(在本教程中为“AzureSearchQuery”)搜索连接器。Search for the connector by name (in this tutorial, is "AzureSearchQuery").

  3. 选择该连接器,展开操作列表,然后选择“查看属性”。Select the connector, expand the actions list, and select View Properties.

    查看属性

  4. 选择右上角的“编辑”。Select Edit on the top right.

  5. 选择“4.测试”以打开测试页。Select 4. Test to open the test page.

  6. 在“测试操作”中,单击“+ 新建连接”。In Test Operation, click + New Connection.

  7. 输入一个查询 API 密钥。Enter a query API key. 这是一个对索引进行只读访问的 Azure 认知搜索查询。This is an Azure Cognitive Search query for read-only access to an index. 可以在 Azure 门户中找到该密钥You can find the key in the Azure portal.

  8. 在“操作”中,单击“测试操作”按钮。In Operations, click the Test operation button. 如果测试成功,应会看到 200 状态,并且在响应正文中,应会看到描述搜索结果的 JSON。If you are successful you should see a 200 status, and in the body of the response you should see JSON that describes the search results.

    JSON 响应

3 - 将结果可视化3 - Visualize results

在此步骤中,创建一个带有搜索框、搜索按钮和结果显示区域的 Power App。In this step, create a Power App with a search box, a search button, and a display area for the results. 该 Power App 将连接到最近创建的自定义连接器,以从 Azure 搜索中获取数据。The Power App will connect to the recently created custom connector to get the data from Azure Search.

  1. 在左侧,展开“应用” > “+ 新建应用” > “画布”。 On the left, expand Apps > + New app > Canvas.

    创建画布应用

  2. 选择应用程序的类型。Select the type of application. 对于本教程,请创建采用“手机布局”的空白应用。 For this tutorial, create a Blank App with the Phone Layout. 此时会显示“Power Apps Studio”。The Power Apps Studio will appear.

  3. 进入 Studio 后,选择“数据源”选项卡,然后单击刚刚创建的新连接器。Once in the studio, select the Data Sources tab, and click on the new Connector you have just created. 在本例中,该连接器名为 AzureSearchQuery。In our case, it is called AzureSearchQuery. 单击“添加连接”。Click Add a connection.

    输入查询 API 密钥。Enter the query API key.

    连接连接器

    现在,AzureSearchQuery 是可从应用程序使用的数据源。Now AzureSearchQuery is a data source that is available to be used from your application.

  4. 在“插入”选项卡上,将几个控件添加到画布。On the Insert tab, add a few controls to the canvas.

    插入控件

  5. 插入以下元素:Insert the following elements:

    • 值为“查询:”的一个文本标签A Text Label with the value "Query:"
    • 一个文本输入元素(将其命名为 txtQuery,默认值:"*")A Text Input element (call it txtQuery, default value: "*")
    • 带有文本“搜索”的一个按钮A button with the text "Search"
    • 垂直库(将其命名为 galleryResults)A Vertical Gallery called (call it galleryResults)

    画布应如下所示:The canvas should look something like this:

    控件布局

  6. 要使“搜索”按钮发出查询,请将以下操作粘贴到 OnSelect 中: To make the Search button issue a query, paste the following action into OnSelect:

    If(!IsBlank(txtQuery.Text),
        ClearCollect(azResult, AzureSearchQuery.Query({search: txtQuery.Text}).value))
    

    以下屏幕截图显示了 OnSelect 操作的公式栏。The following screenshot shows the formula bar for the OnSelect action.

    OnSelect 按钮

    此操作会导致按钮使用 txtQuery 文本框中的文本作为查询词,使用搜索查询结果更新名为 azResult 的新集合。 This action will cause the button to update a new collection called azResult with the result of the search query, using the text in the txtQuery text box as the query term.

    Note

    如果收到公式语法错误“函数 'ClearCollect' 包含一些无效函数”,请尝试以下解决方法:Try this if you get a formula syntax error "The function 'ClearCollect' has some invalid functions":

    • 首先,请确保连接器引用正确。First, make sure the connector reference is correct. 清除连接器名称,然后开始键入连接器的名称。Clear the connector name and begin typing the name of your connector. Intellisense 应会建议正确的连接器和谓词。Intellisense should suggest the right connector and verb.

    • 如果该错误依然出现,请删除并重新创建连接器。If the error persists, delete and recreate the connector. 如果有多个连接器实例,应用可能会使用错误的实例。If there are multiple instances of a connector, the app might be using the wrong one.

  7. 将“垂直库”控件链接到完成上一步骤时创建的 azResult 集合。Link the Vertical Gallery control to the azResult collection that was created when you completed the previous step.

    选择库控件,并在属性窗格中执行以下操作。Select the gallery control, and perform the following actions in the properties pane.

    • 将“DataSource”设置为“azResult”。Set DataSource to azResult.
    • 根据索引中的数据类型,选择合适的布局。Select a Layout that works for you based on the type of data in your index. 在本例中,我们使用了“标题、副标题和正文”布局。In this case, we used the Title, subtitle and body layout.
    • 单击“编辑字段”,并选择要可视化的字段。Edit Fields, and select the fields you would like to visualize.

    由于我们在定义连接器时提供了示例结果,因此该应用能够识别到索引中可用的字段。Since we provided a sample result when we defined the connector, the app is aware of the fields available in your index.

    库字段

  8. 按 F5 预览应用。Press F5 to preview the app.

    最终的应用

清理资源Clean up resources

在自己的订阅中操作时,最好在项目结束时确定是否仍需要已创建的资源。When you're working in your own subscription, it's a good idea at the end of a project to identify whether you still need the resources you created. 持续运行资源可能会产生费用。Resources left running can cost you money. 可以逐个删除资源,也可以删除资源组以删除整个资源集。You can delete resources individually or delete the resource group to delete the entire set of resources.

可以使用左侧导航窗格中的“所有资源”或“资源组”链接 ,在门户中查找和管理资源。You can find and manage resources in the portal, using the All resources or Resource groups link in the left-navigation pane.

如果使用的是免费服务,请记住只能设置三个索引、索引器和数据源。If you are using a free service, remember that you are limited to three indexes, indexers, and data sources. 可以在门户中删除单个项目,以不超出此限制。You can delete individual items in the portal to stay under the limit.