チュートリアル: .NET SDK を使用してAzure SQLデータのインデックスを作成する

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

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

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

前提条件

アクティブなサブスクリプションを持つAzure アカウント。アカウントを無料で作成。
Azure SQL DatabaseSQL Server認証を使用します。
Azure AI Search。サービスの作成または現在のサブスクリプションの既存のサービスを確認します。
Visual Studio。

注

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

ファイルのダウンロード

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

サービスを作成する

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

Azure SQL Databaseから始める

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

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

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

access拒否エラーが発生した場合は、エラーメッセージからクライアント IP アドレスをコピーし、サーバーのネットワークセキュリティページを開き、クライアントからのaccessを許可する受信規則を追加します。
Query editorで、Open query を選択し、ローカルコンピューター上の hotels.sql ファイルの場所に移動します。
ファイルを選択し、[開く] を選択します。このスクリプトは次のスクリーンショットのようになります。

Query Editor window 内の SQL スクリプトのスクリーンショット。
[実行] を選択して、クエリを実行します。 [結果] ウィンドウに、3 行のクエリに成功したメッセージが表示されます。
このテーブルから行セットが返されるようにするには、検証ステップとして次のクエリを実行します。
```
SELECT * FROM Hotels
```

データベースの ADO.NET connection string をコピーします。 Settings>Connection Strings で ADO.NET connection string をコピーします。これは次の例のようになります。

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;

次の手順で環境を設定するには、このconnection stringが必要です。

Azure AI Search

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

Azure AI Searchの管理者キーと URL を取得する

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

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

環境を設定する

Visual Studioを開始し、DotNetHowToIndexers.sln を開きます。
Solution Explorerで、appsettings.json を開いて接続情報を指定します。
SearchServiceEndPointの場合、サービス Overview ページの完全な 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 connection stringのユーザーパスワードを有効なパスワードに置き換えます。データベースとユーザー名はコピーオーバーされますが、パスワードを手動で入力する必要があります。

パイプラインを作成する

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

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

hotel.cs の内容

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

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

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

Program.cs の内容

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

データソースオブジェクトは、Azure SQL Database リソースに特有の設定で構成されており、Azure SQLの組み込みの部分的または増分インデックス作成を含む変更検出機能を使用するために対応しています。 Azure SQLのソースデモホテルデータベースには、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の「Search Service」に接続し、さらにAzure SQL Databaseに接続してデータセットを取得します。このように多くの操作が伴うため、障害が発生し得るポイントがいくつも存在します。エラーが発生した場合は、まず次の条件を確認してください。

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

Search

Azure portalを使用してオブジェクトの作成を確認し、Search explorer を使用してインデックスのクエリを実行します。

Azure portalにサインインし、search serviceに移動します。左側のウィンドウで各ページを開き、オブジェクトが作成されていることを確認します。 インデックス、 インデクサー、 データソース には、 それぞれ hotels-sql-idx、 hotels-sql-idxr、 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を使用して、インデックス、インデクサー、データソースを削除することもできます。

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

独自のサブスクリプションで作業している場合は、projectの最後に、不要になったリソースを削除することをお勧めします。リソースを実行したままにすると、お金がかかる場合があります。リソースを個別に削除するか、リソースグループを削除してリソースのセット全体を削除することができます。

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

次のステップ

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

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

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-03-11