教學課程：從 Power Apps 查詢 Azure AI 搜尋服務索引

2025-04-30

使用 Power Apps 的快速應用程式開發環境，在 Azure AI 搜尋服務中為可搜尋的內容建立自訂應用程式。

在本教學課程中，您會了解如何：

連線至 Azure AI 搜尋服務
設定查詢要求
在畫布應用程式中將結果視覺化

如果您沒有 Azure 訂用帳戶，請在開始前開啟免費帳戶。

必要條件

具有 Premium 授權的 Power Apps 帳戶，例如 Power Apps 每個應用程式方案或 Power Apps 每個使用者方案。
在您搜尋服務上託管的 Hotels-sample 索引。
查詢 API 金鑰。

1 - 建立自訂連接器

Power Apps 中的連接器是資料來源連線。在此步驟中，建立自訂連接器，以連線至雲端中的搜尋索引。

登入 Power Apps。
在左邊，選取 [自訂連接器]。
選取 [+ 新增自訂連接器]，然後選取 [從空白建立]。
為自訂連接器命名 (例如，AzureSearchQuery)，然後選取 [繼續]。
在 [一般] 頁面中輸入資訊：
- 圖示背景色彩 (例如，#007ee5)
- 說明 (例如，「Azure AI 搜尋服務的連接器」)
- 在 [主機] 中，輸入您的搜尋服務 URL (例如 <yourservicename>.search.windows.net)
- 基底 URL 輸入「/」
在 [安全性] 頁面中，將 [API 金鑰] 設定為 [驗證類型]，並將參數標籤和參數名稱皆設定為 [api-key]。針對 [參數位置]，選取 [標頭]，如下列螢幕擷取畫面所示。
在 [定義] 頁面中，選取 [+ 新增動作] 以建立會查詢索引的動作。針對摘要和作業識別碼名稱，輸入「查詢」這個值。輸入說明，例如「查詢搜尋索引」。
向下捲動。在 [要求] 中選取 [+ 從範例匯入] 按鈕，以設定搜尋服務的查詢要求：
- 選取動詞 GET
- 針對 [URL]，輸入搜尋索引的範例查詢 (search=* 會傳回所有文件，$select= 則可讓您選擇欄位)。需要 API 版本。完全指定，URL 看起來可能如下列範例所示。請注意，省略前置 https:// 詞。
```
mydemo.search.windows.net/indexes/hotels-sample-index/docs?search=*&$select=HotelName,Description,Address/City&api-version=2024-07-01
```
- 在 [標頭] 中輸入 Content-Type application/json。
  
  Power Apps 會使用 URL 中的語法從查詢中擷取參數：search、select 和 api-version 參數會在您透過精靈進行作業的過程中變成可設定的。
選取 [匯入] 以自動填滿要求。按一下每個參數旁的 ... 符號，以完成參數中繼資料的設定。選取 [上一步] 以在每個參數更新之後返回 [要求] 頁面。
針對 search：將 * 設定為 [預設值]、將 [必要] 設定為 [False]，並將 [可見性] 設定為 [無]。
針對 select：將 HotelName,Description,Address/City 設定為 [預設值]、將 [必要] 設定為 [False]，並將 [可見性] 設定為 [無]。
針對 api-version：將 2024-07-01 設定為 [預設值]、將 [必要] 設定為 [True]，並將 [可見性] 設定為 [內部]。
針對 Content-Type：設為 application/json。

在進行這些變更後，切換至 [Swagger 編輯器] 檢視。在 [參數] 區段中，您應該會看到下列設定：

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}

切換回精靈並返回 [3.定義] 步驟。向下捲動到 [回應] 區段。選取 [新增預設回應]。這步驟很重要，因為這可協助 Power Apps 了解回應的結構描述。

貼上範例回應。若要擷取範例回應，有個簡單的方式是透過 Azure 入口網站中的「搜尋總管」。在 [搜尋總管] 中，您應該輸入與要求相同的查詢，但新增 $top=2 以將結果限制為只有兩個文件：search=*&$select=HotelName,Description,Address/City&$top=2。

Power Apps 只需要幾個結果即可偵測結構描述。您現在可以將下列回應複製到精靈中 (假設您使用的是 hotels-sample-index)。

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

貼士

您可以輸入的 JSON 回應有字元限制，因此您可能會想要在貼上 JSON 之前簡化 JSON。回應的結構和格式比其內容更重要。例如，[說明] 欄位可以簡化為只有第一個句子。

選取 [匯入] 來新增預設回應。
選取右上方的 [建立連接器] 來儲存定義。
選取 [關閉] 即可關閉連接器。

2 - 測試連線

第一次建立連接器時，您必須從 [自訂連接器] 清單將其重新開啟才能進行測試。之後，如果您進行其他更新，則可以從精靈內進行測試。

您需要有查詢 API 金鑰才能進行此工作。每次建立連線時 (無論是測試執行還是包含在應用程式中)，連接器都需要使用查詢 API 金鑰來連線到 Azure AI 搜尋服務。

在最左邊選取 [自訂連接器]。
在清單中尋找您的連接器 (在本教學課程中為 "AzureSearchQuery")。
選取連接器、展開 [動作] 清單，然後選取 [檢視屬性]。
在作業的下拉式清單中，選取 [6.測試]。
在 [測試作業] 中，選取 [+ 新增連線]。
輸入查詢 API 金鑰。這是用於對索引進行唯讀存取的 Azure AI 搜尋查詢。您可以在 Azure 入口網站中尋找金鑰。
在 [作業] 中，選取 [測試作業] 按鈕。如果成功，您應該會看到 200 狀態，並在回應內容中看到描述搜尋結果的 JSON。

如果測試失敗，請重新檢查輸入。特別是，重新瀏覽範例回應並確定已正確建立。連接器定義應該會顯示回應的預期項目。

如果您遭到數據外洩防護（DLP）原則錯誤封鎖，請檢閱錯誤訊息以取得指引。您可以修改原則，或讓您的連接器無法封鎖。

3 - 將結果視覺化

在此步驟中，請建立具有搜尋方塊、搜尋按鈕和結果顯示區域的 Power App。 Power App 會連線到最近建立的自訂連接器，以從 Azure 搜尋服務取得資料。

在左側展開 [應用程式]>[新增應用程式]>[從頁面設計開始]。
選取 [空白畫布] 搭配 [電話版面配置]。為應用程式命名，例如「旅館搜尋工具」。選取 [建立]。隨即會出現 [Power Apps Studio]。
進入 Power Apps Studio 後，選取 [資料] 索引標籤，選取 [新增資料]，然後尋找您剛才建立的新連接器。在本教學課程中，其稱為 AzureSearchQuery。選取新增連線。

輸入查詢 API 金鑰。

現在 AzureSearchQuery 是可從應用程式使用的資料來源。
在 [插入] 索引標籤上，將一些控制項新增到畫布中。
插入下列元素：
- 具有值「Query:」的文字標籤
- 文字輸入元素 (將其稱為 txtQuery，預設值："*")
- 具有文字「搜尋」的按鈕
- 所呼叫的垂直資源庫 (將其稱為 galleryResults)
畫布應該會看起來像這樣：
若要讓 [搜尋] 按鈕發出查詢，請將下列動作貼入 OnSelect：
```
If(!IsBlank(txtQuery.Text),
    ClearCollect(azResult, AzureSearchQuery.Query({search: txtQuery.Text}).value))
```
下列螢幕擷取畫面顯示了 OnSelect 動作的公式欄。

此動作會讓按鈕使用 [txtQuery] 文字方塊中的文字作為查詢字詞，以搜尋查詢的結果更新名為 azResult 的新集合。
注意

如果您收到公式語法錯誤「函數 'ClearCollect' 包含一些無效的函數」，請嘗試如下方法：
- 首先，請確定連接器參考是否正確。清除連接器名稱，然後開始輸入連接器的名稱。 Intellisense 應該會建議正確的連接器和動詞。
- 若錯誤持續發生，請刪除連接器再重新建立。如果有多個連接器的實例，應用程式可能正在使用錯誤的連接器。
將「垂直資源庫」控制項連結至您完成上一個步驟時所建立的 azResult 集合。

選取資源庫控制項，然後在 [屬性] 窗格中執行下列動作。
- 將 [資料來源] 設定為 [azResult]。
- 根據索引資料的類型，選擇一個適合您的版面配置。在本案例中，我們使用的是 [標題、副標題和主體] 配置。
- [編輯欄位]，然後選取您想要視覺化的欄位。
由於我們在定義連接器時提供了範例結果，因此應用程式會知道索引中可用的欄位。
按 F5 以預覽應用程式。