チュートリアル:.NET SDK を使用して Azure SQL データにインデックスを付ける

2025-04-23

Azure SQL Database から検索可能なデータを抽出し、Azure AI Search の検索インデックスに送信するようにインデクサーを構成する方法について説明します。

このチュートリアルでは、C# と Azure SDK for .NET を使用して次の操作を行います。

Azure SQL Database に接続するデータソースを作成する
インデクサーの作成
インデクサーを実行してインデックスにデータを読み込む
検証ステップとしてインデックスを照会する

前提条件

アクティブなサブスクリプションを持つ Azure アカウント。無料でアカウントを作成できます。
SQL Server 認証を使用した Azure SQL Database。
Azure AI 検索. サービスを作成するか、現在のサブスクリプションで既存のサービスを検索します。
Visual Studio.

注

このチュートリアルには無料の検索サービスを使用できます。 Free レベルでは、3 つのインデックス、3 つのインデクサー、3 つのデータソースに制限されます。このチュートリアルでは、それぞれ 1 つずつ作成します。開始する前に、サービスで新しいリソースを受け入れる余裕があることを確認します。

ファイルのダウンロード

このチュートリアルのソースコードは、Azure-Samples/search-dotnet-getting-started GitHub リポジトリ内の DotNetHowToIndexer フォルダーにあります。

サービスを作成する

このチュートリアルでは、インデックス作成とクエリに Azure AI Search を使用し、Azure SQL Database を外部データソースとして使用します。可能である場合は、近接性と管理性を高めるために、両方のサービスを同じリージョンおよびリソースグループ内に作成してください。実際には、Azure SQL Database の場所はどのリージョンでもかまいません。

最初に Azure SQL Database で行う作業

このチュートリアルでは、サンプルダウンロードの hotels.sql ファイルを提供して、データベースを設定します。 Azure AI Search で使用されるのは、ビューやクエリから生成されるようなフラット化された行セットです。サンプルソリューションの SQL ファイルでは、単一のテーブルを作成してデータを投入します。

既存の Azure SQL Database リソースがある場合は、 Open クエリ ステップから hotels テーブルを追加できます。

Azure SQL データベースを作成します。データベースのサーバー構成は重要です。
- ユーザー名とパスワードの指定を求める SQL Server 認証オプションを選択します。これは、インデクサーによって使用される ADO.NET 接続文字列に必要です。
- パブリック接続を選択すると、このチュートリアルを簡単に完了できます。運用環境ではパブリックは推奨されません。このリソースは、チュートリアルの最後に削除することをお勧めします。
Azure portal で新しいリソースに移動します。
クライアントからのアクセスを許可するファイアウォール規則を追加します。コマンドプロンプトから ipconfig を実行して、IP アドレスを取得できます。
クエリエディターを使用して、サンプルデータを読み込みます。ナビゲーションウィンドウで、 クエリエディター (プレビュー) を選択し、サーバー管理者のユーザー名とパスワードを入力します。

アクセス拒否エラーが表示された場合は、エラーメッセージからクライアント IP アドレスをコピーし、サーバーのネットワークセキュリティページを開き、クライアントからのアクセスを許可する受信規則を追加します。
クエリエディターで [クエリを開く] を選択し、ローカルコンピューター上の hotels.sql ファイルの場所に移動します。
ファイルを選択し、[開く] を選択します。このスクリプトは次のスクリーンショットのようになります。
[実行] を選択して、クエリを実行します。 [結果] ウィンドウに、3 行のクエリに成功したメッセージが表示されます。
このテーブルから行セットが返されるようにするには、検証ステップとして次のクエリを実行します。
```
SELECT * FROM Hotels
```

データベース用の 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 Search

次のコンポーネントは Azure AI Search であり、Azure portal で作成できます。 Free レベルを使用して、このチュートリアルを完了できます。

Azure AI 検索のための管理者キーと URL を取得する

API 呼び出しには、サービス URL とアクセスキーが必要です。両方を使用して検索サービスが作成されるため、Azure AI Search をサブスクリプションに追加した場合は、こちらの手順に従って必要な情報を取得します。

Azure portal にサインインします。サービスの [概要] ページで、エンドポイントの URL をコピーします。たとえば、エンドポイントは https://mydemo.search.windows.net のようになります。
[設定]>[キー] で、サービスに対する完全な権限の管理キーを取得します。管理キーをロールオーバーする必要がある場合に備えて、2 つの交換可能な管理キーがビジネス継続性のために提供されています。オブジェクトの追加、変更、および削除の要求には、主キーまたはセカンダリキーのどちらかを使用できます。

環境を設定する

Visual Studio を起動し、DotNetHowToIndexers.sln を開きます。
ソリューションエクスプローラーで appsettings.json を開き、接続情報を指定します。
SearchServiceEndPointの場合、サービスの [概要] ページの完全な URL がhttps://my-demo-service.search.windows.net場合は、URL 全体を指定します。
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",
}
```
SQL 接続文字列のユーザーパスワードを有効なパスワードに置き換えます。データベースとユーザー名はコピーオーバーされますが、パスワードを手動で入力する必要があります。

パイプラインを作成する

インデクサーには、データソースオブジェクトとインデックスが必要です。関連するコードは次の 2 つのファイルにあります。

hotel.cs には、インデックスを定義するスキーマが含まれています
Program.cs には、サービス内の構造を作成および管理するための関数が含まれています

hotel.cs の内容

インデックススキーマでは、次の HotelNameのフィールド定義に示すように、フィールドがフルテキスト検索可能、フィルター可能、または並べ替え可能かどうかなど、許可された操作を指定する属性を含むフィールドコレクションを定義します。 SearchableField は、定義上、フルテキスト検索可能です。その他の属性は明示的に割り当てられます。

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

スキーマには、検索スコアを向上させるスコアリングプロファイルやカスタムアナライザーなどの他の要素を含めることもできます。ただし、このチュートリアルでは、スキーマは疎に定義され、サンプルデータセット内のフィールドのみで構成されます。

Program.cs の内容

メインプログラムには、インデクサークライアント、インデックス、データソース、インデクサーを作成するためのロジックが含まれます。このコードは、このプログラムを複数回実行する可能性があると仮定して、同じ名前の既存のリソースをチェックして削除します。

データソースオブジェクトの構成には、Azure SQL に組み込まれている変更検出機能を使用するための部分インデックス作成または増分インデックス作成を含む、Azure SQL Database リソースに固有の設定が使用されます。 Azure SQL にあるソースのデモ hotels データベースには、IsDeleted という名前の "論理的な削除" 列があります。データベースでこの列を true に設定すると、インデクサーによって、Azure AI Search インデックスから対応するドキュメントが削除されます。

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);
}

ソリューションをビルドする

F5 キーを押してソリューションをビルドして実行します。プログラムがデバッグモードで実行されます。コンソールウィンドウで各操作の状態が報告されます。

コードは Visual Studio でローカルに実行され、Azure 上の検索サービスに接続されます。次に、それが Azure SQL Database に接続され、データセットが取得されます。このように多くの操作が伴うため、障害が発生し得るポイントがいくつも存在します。エラーが発生した場合は、まず次の条件を確認してください。

指定する検索サービスの接続情報は完全な URL です。サービス名のみを入力した場合、操作はインデックスの作成時に停止し、接続エラーが発生します。
appsettings.json のデータベース接続情報。これは、Azure portal から取得した ADO.NET 接続文字列に、実際のデータベースの有効なユーザー名とパスワードを反映したものであることが必要です。ユーザーアカウントには、データを取得するためのアクセス許可が必要です。ローカルクライアントの IP アドレスには、ファイアウォールを介したインバウンドアクセスが許可されている必要があります。
リソース制限。既に述べたように、Free レベルは、インデックス、インデクサー、データソースがいずれも 3 つまでに制限されています。上限に達した場合、新しいオブジェクトを作成できなくなります。

検索する

Azure portal を使用してオブジェクトの作成を確認し、 検索エクスプローラー を使用してインデックスのクエリを実行します。

Azure portal にサインインし、検索サービスに移動します。左側のウィンドウで各ページを開き、オブジェクトが作成されていることを確認します。 インデックス、 インデクサー、 およびデータソース には、 それぞれ hotels-sql-idx、 hotels-sql-indexer、 hotels-sql-ds が必要です。
[ インデックス ] タブで、 hotels-sql-idx インデックスを選択します。 hotels ページの先頭のタブは [検索エクスプローラー] です。
[検索] を選択して空のクエリを発行します。

インデックスの 3 つのエントリが JSON ドキュメントとして返されます。 Search エクスプローラーは、構造全体が見えるようにドキュメントを JSON 形式で返します。
クエリパラメーターを入力できるように、JSON ビューに切り替えます。
```
{
     "search": "river",
     "count": true
}
```
このクエリは、 riverという用語に対してフルテキスト検索を呼び出します。結果には、一致するドキュメントの数が含まれます。一致するドキュメントの数を返すのは、数千または数百万のドキュメントを含む大きなインデックスがあるシナリオをテストする場合に役立ちます。今回のケースで、このクエリに一致するドキュメントは 1 件だけです。
検索結果を対象フィールドに制限するパラメーターを入力します。
```
{
     "search": "river",
     "select": "hotelId, hotelName, baseRate, description",
     "count": true
}
```
クエリの応答が選択フィールドに制限され、より簡潔な出力内容が得られます。

リセットして再実行する

開発の初期の実験的な段階では、設計反復のための最も実用的なアプローチは、Azure AI Search からオブジェクトを削除してリビルドできるようにすることです。リソース名は一意です。オブジェクトを削除すると、同じ名前を使用して再作成することができます。

このチュートリアルのサンプルコードでは、コードを再実行できるよう、既存のオブジェクトをチェックしてそれらを削除しています。

Azure portal を使用して、インデックス、インデクサー、およびデータソースを削除することもできます。

リソースをクリーンアップする

所有するサブスクリプションを使用している場合は、プロジェクトの終了時に、不要になったリソースを削除することをお勧めします。リソースを実行したままにすると、お金がかかる場合があります。リソースを個別に削除するか、リソースグループを削除してリソースのセット全体を削除することができます。

Azure portal で、左側のナビゲーションウィンドウにある [すべてのリソース] または [リソースグループ] リンクを使って、リソースを検索および管理できます。

次のステップ

SQL Database のインデックス作成の基本を理解したら、インデクサーの構成を詳しく見てみましょう。

SQL Database のインデクサーを構成する