共用方式為

教學課程：使用 .NET SDK 為 Azure SQL 資料編製索引

  • 發行項

設定索引子，以從 Azure SQL Database 中擷取可搜尋的資料，並將其傳送至 Azure AI 搜尋服務中的搜尋索引。

本教學課程將使用 C# 和適用於 .NET 的 Azure SDK 執行下列工作：

  • 建立會連線到 Azure SQL Database 的資料來源
  • 建立索引子
  • 執行索引子以將資料載入至索引
  • 以驗證步驟的形式查詢索引

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

必要條件

注意

您可以使用免費搜尋服務來進行本教學課程。 免費層的限制為三個索引、三個索引子、以及三個資料來源。 本教學課程會各建立一個。 開始之前，請確定您的服務有空間可接受新的資源。

下載檔案

本教學課程的原始程式碼位於 Azure-Samples/search-dotnet-getting-started GitHub 存放庫中的 DotNetHowToIndexer 資料夾內。

1 - 建立服務

本教學課程將使用 Azure AI 搜尋服務進行索引編製和查詢，並以 Azure SQL Database 作為外部資料來源。 為具備鄰近性和管理方面的優勢，如果可能，請將這兩項服務建立在相同的區域和資源群組中。 在實務上，Azure SQL Database 可以位於任何區域中。

從 Azure SQL Database 開始著手

此教學課程在範例下載中提供 hotels.sql 檔案用於填入資料庫。 Azure AI 搜尋服務會取用扁平化資料列集，例如從檢視或查詢產生的資料列集。 範例方案中的 SQL 檔案會建立並填入單一資料表。

如果您有現有的 Azure SQL Database 資源，您可以在其中新增 hotels 資料表 (在開啟查詢步驟開始)。

  1. 建立 Azure SQL 資料庫，請參閱快速入門：建立單一資料庫中的指示。

    資料庫的伺服器組態很重要。

    • 選擇 SQL Server 驗證選項，該選項會提示您指定使用者名稱和密碼。 您需要提供此資訊，索引子才能使用 ADO.NET 連接字串。

    • 選擇公用連線。 這可讓本教學課程更容易完成。 生產環境中不建議使用公用連線，建議您在教學課程結束時刪除此資源。

    伺服器設定的螢幕擷取畫面。

  2. 在 Azure 入口網站中，移至您的新資源。

  3. 新增防火牆規則以允許來自您用戶端的存取，請參閱快速入門：在 Azure 入口網站中建立伺服器層級的防火牆規則中的指示。 您可以在命令提示字元執行 ipconfig 以取得您的 IP 位址。

  4. 使用查詢編輯器以載入範例資料。 在瀏覽窗格中，按一下 [查詢編輯器 (預覽)]，然後輸入伺服器管理員的使用者名稱和密碼。

    如果您遇到存取遭拒錯誤，請複製錯誤訊息的用戶端 IP 位址、開啟該伺服器的網路安全性頁面，並新增允許來自您用戶端存取的輸入規則。

  5. 在查詢編輯器中，選取 [開啟查詢]，然後瀏覽至本機電腦上「hotels.sql」檔案所在的位置。

  6. 選取該檔案並選取 [開啟]。 指令碼應該會看起來如下列螢幕擷取畫面所示：

    此螢幕擷取畫面顯示 [查詢編輯器] 視窗中的 SQL 指令碼。

  7. 選取 [執行] 以執行查詢。 在 [結果] 窗格中，您應會看到查詢成功訊息 (三個資料列)。

  8. 若要從這個資料表傳回資料列集，您可以執行下列查詢作為驗證步驟：

    SELECT * FROM Hotels

  9. 複製資料庫的 ADO.NET 連接字串。 在 [設定]>[連接字串] 底下，複製 ADO.NET 連接字串，如下列範例所示。

    Server=tcp:<YOUR-DATABASE-NAME>.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID=<YOUR-USER-NAME>;Password=<YOUR-PASSWORD>;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;

在下一個練習中，您需要此連接字串來設定您的環境。

下一個元件是 Azure AI 搜尋服務，您可以在入口網站中建立該服務。 您可以使用免費層來完成此逐步解說。

API 呼叫需要用到服務 URL 和存取金鑰。 搜尋服務是同時建立，因此如果您將 Azure AI 搜尋服務新增至您的訂用帳戶，請遵循下列步驟來取得必要的資訊：

  1. 登入 Azure 入口網站，並在搜尋服務的 [概觀] 頁面上取得 URL。 範例端點看起來會像是 https://mydemo.search.windows.net。

  2. 在 [設定]> [金鑰] 中，取得服務上完整權限的管理金鑰。 可互換的管理金鑰有兩個，可在您需要變換金鑰時提供商務持續性。 您可以在新增、修改及刪除物件的要求上使用主要或次要金鑰。

    Azure 入口網站頁面的螢幕擷取畫面，其中顯示搜尋服務的 HTTP 端點和存取金鑰位置。

2 - 設定您的環境

  1. 啟動 Visual Studio 並開啟 DotNetHowToIndexers.sln。

  2. 在方案總管中開啟 appsettings.json，以提供連線資訊。

  3. 針對 SearchServiceEndPoint，如果服務概觀頁面上的完整 URL 為 "https://my-demo-service.search.windows.net"，則要提供的值就是整個 URL。

  4. AzureSqlConnectionString 的字串格式如下所示："Server=tcp:<your-database-name>.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID=<your-user-name>;Password=<your-password>;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

    {
  "SearchServiceEndPoint": "<placeholder-search-full-url>",
  "SearchServiceAdminApiKey": "<placeholder-admin-key-for-search-service>",
  "AzureSqlConnectionString": "<placeholder-ADO.NET-connection-string",
}

  5. 將 SQL 連接字串中的使用者密碼取代為有效密碼。 雖然資料庫和使用者名稱會複製過去，但密碼必須手動輸入。

3 - 建立管線

索引子需要資料來源物件和索引。 相關程式碼位於兩個檔案中：

  • hotel.cs，內含可定義索引的結構描述

  • Program.cs，內含用於建立和管理您服務中結構的函式

在 hotel.cs 中

索引結構描述會定義欄位集合，包括用於指定允許作業的屬性，例如欄位是否可全文檢索搜尋、可篩選，或可排序 (如 HotelName 的下列欄位定義中所示)。 SearchableField 根據定義可以進行全文搜尋。 其他屬性會明確指派。

. . . 
[SearchableField(IsFilterable = true, IsSortable = true)]
[JsonPropertyName("hotelName")]
public string HotelName { get; set; }
. . .

結構描述也可以包含其他元素，包括提高搜尋分數、自訂分析城市和其他建構的評分設定檔。 不過，基於我們的目的，結構描述並未嚴密定義，只包含在範例資料集中找到的欄位。

在 Program.cs 中

主要程式包含用於建立索引子用戶端、索引、資料來源和索引子的邏輯。 在您可能會執行此程式多次的假設之下，此程式碼會檢查並刪除現有的同名資源。

資料來源物件上會配置專屬於 Azure SQL Database 資源的設定，包括部份或增量索引編製，以使用 Azure SQL 的內建變更偵測功能。 在 Azure SQL 中，來源示範用的飯店資料庫具有名為 IsDeleted 的「虛刪除」資料行。 當此資料行在資料庫中設定為 true 時，索引子就會從 Azure AI 搜尋服務索引中移除對應文件。

Console.WriteLine("Creating data source...");

var dataSource =
      new SearchIndexerDataSourceConnection(
         "hotels-sql-ds",
         SearchIndexerDataSourceType.AzureSql,
         configuration["AzureSQLConnectionString"],
         new SearchIndexerDataContainer("hotels"));

indexerClient.CreateOrUpdateDataSourceConnection(dataSource);

索引子物件可跨平台使用，不論來源為何，其中的設定、排程和引動過程都相同。 此索引子範例包括排程及用於清除索引子記錄的重設選項，並且會呼叫方法來立即建立並執行索引子。 若要建立或更新索引子，請使用 CreateOrUpdateIndexerAsync。

Console.WriteLine("Creating Azure SQL indexer...");

var schedule = new IndexingSchedule(TimeSpan.FromDays(1))
{
      StartTime = DateTimeOffset.Now
};

var parameters = new IndexingParameters()
{
      BatchSize = 100,
      MaxFailedItems = 0,
      MaxFailedItemsPerBatch = 0
};

// Indexer declarations require a data source and search index.
// Common optional properties include a schedule, parameters, and field mappings
// The field mappings below are redundant due to how the Hotel class is defined, but 
// we included them anyway to show the syntax 
var indexer = new SearchIndexer("hotels-sql-idxr", dataSource.Name, searchIndex.Name)
{
      Description = "Data indexer",
      Schedule = schedule,
      Parameters = parameters,
      FieldMappings =
      {
         new FieldMapping("_id") {TargetFieldName = "HotelId"},
         new FieldMapping("Amenities") {TargetFieldName = "Tags"}
      }
};

await indexerClient.CreateOrUpdateIndexerAsync(indexer);

索引子執行通常已排程，但在開發期間，您可以使用 RunIndexerAsync 立即執行索引子。

Console.WriteLine("Running Azure SQL indexer...");

try
{
      await indexerClient.RunIndexerAsync(indexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 429)
{
      Console.WriteLine("Failed to run indexer: {0}", ex.Message);
}

4 - 建置解決方案

按 F5 以建置及執行方案。 此程式會在偵錯模式中執行。 主控台視窗會報告每項作業的狀態。

此螢幕擷取畫面顯示程式的主控台輸出。

您的程式碼會在 Visual Studio 本機執行，並連線到您在 Azure 上的搜尋服務，搜尋服務再連線到 Azure SQL Database 並擷取資料集。 由於要進行的作業很多，所以會有數個潛在的失敗點。 如果您收到錯誤，請先檢查下列條件：

  • 您需要提供的搜尋服務連線資訊為完整 URL。 如果您僅輸入服務名稱，作業會在索引建立時停止，出現連線失敗錯誤。

  • appsettings.json 中的資料庫連線資訊。 它應該是從入口網站取得的 ADO.NET 連接字串，已修改成包含您的資料庫適用的使用者名稱和密碼。 使用者帳戶必須具有擷取資料的權限。 您的本機用戶端 IP 位址必須獲允許透過防火牆的傳入存取。

  • 資源限制。 回想一下，免費層有三個索引、索引子和資料來源的限制。 最大限制的服務無法建立新的物件。

5 - 搜尋

使用 Azure 入口網站來確認物件的建立，然後使用搜尋總管來查詢索引。

  1. 登入 Azure 入口網站，然後在搜尋服務的左側瀏覽窗格中，依序開啟每個頁面以確認物件已完成建立。 [索引]、[索引子] 和 [資料來源] 分別會有 "hotels-sql-idx"、"hotels-sql-indexer" 和 "hotels-sql-ds"。

  2. 在 [索引子] 索引標籤上，選取 hotels-sql-idx 索引。 在 [hotels] 頁面上，第一個索引標籤是 [搜尋總管]。

  3. 選取 [搜尋] 以發出空白查詢。

    您的索引中的三個項目會以 JSON 文件形式傳回。 搜尋總管會以 JSON 傳回文件，以便您檢視整個結構。

    此螢幕擷取畫面顯示目標索引的搜尋總管查詢。

  4. 接著，切換至 [JSON 檢視]，以便輸入查詢參數：

    {
     "search": "river",
     "count": true
}

    此查詢會叫用 river 字詞的全文檢索搜尋，而結果會包含相符文件的計數。 在測試包含數千甚至數百萬份文件的大型索引案例時，傳回相符文件的計數很實用。 在此情況下，只有一份文件符合查詢。

  5. 最後，輸入參數將搜尋結果限制為感興趣的欄位：

    {
     "search": "river",
     "select": "hotelId, hotelName, baseRate, description",
     "count": true
}

    查詢回應會縮減為選取的欄位，導致更簡潔的輸出。

重設並重新執行

在開發的早期實驗階段中，若要設計反覆項目，最實用的方法是從 Azure AI 搜尋服務中刪除物件，並讓您的程式碼重建這些物件。 資源名稱是唯一的。 刪除物件可讓您使用相同的名稱加以重新建立。

本教學課程的範例程式碼會檢查是否有現有的物件，並將其刪除，以便您重新執行程式碼。

您也可以使用入口網站來刪除索引、索引子和資料來源。

清除資源

如果您使用自己的訂用帳戶，當專案結束時，建議您移除不再需要的資源。 資源若繼續執行，將需付費。 您可以個別刪除資源，或刪除資源群組以刪除整組資源。

您可以使用左導覽窗格中的 [所有資源] 或 [資源群組] 連結，在入口網站中尋找和管理資源。

下一步

現在您已熟悉 SQL Database 編製索引的基本概念，接下來我們將進一步了解索引子設定。

設定 SQL 資料庫索引子