C# のチュートリアル: Azure Cognitive Search インデクサーを使用して Azure SQL データベースをクロールするC# Tutorial: Crawl an Azure SQL database using Azure Cognitive Search indexers

検索可能なデータをサンプル Azure SQL データベースから抽出するためのインデクサーを構成する方法について説明します。Learn how to configure an indexer for extracting searchable data from a sample Azure SQL database. インデクサーは、外部データ ソースをクロールして検索インデックスにデータを投入する Azure Cognitive Search のコンポーネントです。Indexers are a component of Azure Cognitive Search that crawl external data sources, populating a search index with content. Azure SQL Database のインデクサーは、すべてのインデクサーの中で最も広く使用されています。Of all indexers, the indexer for Azure SQL Database is the most widely used.

インデクサーを構成することによって、記述すべきコードや保守すべきコードの量が少なくて済むため、そのスキルは身に付けておいて損はありません。Proficiency in indexer configuration is helpful because it simplifies the amount of code you have to write and maintain. スキーマに準拠した JSON データセットを作成して投入する代わりに、インデクサーをデータ ソースにアタッチし、データをインデクサーで抽出してインデックスに挿入することができるほか、必要に応じてインデクサーを定期実行し、基になるソースの変更を反映することもできます。Rather than preparing and pushing a schema-compliant JSON dataset, you can attach an indexer to a data source, have the indexer extract data and insert it into an index, and optionally run the indexer on a recurring schedule to pick up changes in the underlying source.

このチュートリアルでは、Azure Cognitive Search .NET クライアント ライブラリと .NET Core コンソール アプリケーションを使用して次のタスクを実行します。In this tutorial, use the Azure Cognitive Search .NET client libraries and a .NET Core console application to perform the following tasks:

  • Search サービスの情報をアプリケーション設定に追加するAdd search service information to application settings
  • 外部データセットを Azure SQL データベースに用意するPrepare an external dataset in Azure SQL database
  • サンプル コードでインデックスとインデクサーの定義を確認するReview the index and indexer definitions in sample code
  • インデクサーのコードを実行してデータをインポートするRun the indexer code to import data
  • インデックスを検索するSearch the index
  • インデクサーの構成をポータルで確認するView indexer configuration in the portal

Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。If you don't have an Azure subscription, create a free account before you begin.

前提条件Prerequisites

このクイック スタートでは、次のサービス、ツール、およびデータを使用します。The following services, tools, and data are used in this quickstart.

Azure Cognitive Search サービスを作成するか、現在のサブスクリプションから既存のサービスを見つけますCreate an Azure Cognitive Search service or find an existing service under your current subscription. このチュートリアル用には、無料のサービスを使用できます。You can use a free service for this tutorial.

Azure SQL Database は、インデクサーによって使用される外部データ ソースを格納します。Azure SQL Database stores the external data source used by an indexer. サンプル ソリューションでは、SQL データ ファイルを入力することにってテーブルを作成しています。The sample solution provides a SQL data file to create the table. このチュートリアルでは、サービスとデータベースを作成するための手順を説明しています。Steps for creating the service and database are provided in this tutorial.

Visual Studio 2017。サンプル ソリューションを実行するために、任意のエディションを使用できます。Visual Studio 2017, any edition, can be used to run the sample solution. サンプル コードと手順については、無料の Community エディションでテストされています。Sample code and instructions were tested on the free Community edition.

Azure サンプル GitHub リポジトリの Azure-Samples/search-dotnet-getting-started に、サンプル ソリューションが用意されています。Azure-Samples/search-dotnet-getting-started provides the sample solution, located in the Azure samples GitHub repository. そのソリューションをダウンロードして展開します。Download and extract the solution. 既定では、ソリューションは読み取り専用です。By default, solutions are read-only. ソリューションを右クリックし、読み取り専用属性をオフにして、ファイルを変更できるようにします。Right-click the solution and clear the read-only attribute so that you can modify files.

注意

無料の Azure Cognitive Search サービスを使用している場合、インデックス、インデクサー、データ ソースの数は、いずれも 3 つまでに制限されます。If you are using the free Azure Cognitive Search service, you are limited to three indexes, three indexers, and three data sources. このチュートリアルでは、それぞれ 1 つずつ作成します。This tutorial creates one of each. ご利用のサービスに、新しいリソースを作成できるだけの空き領域があることを確認してください。Make sure you have room on your service to accept the new resources.

キーと URL を入手するGet a key and URL

REST 呼び出しには、要求ごとにサービス URL とアクセス キーが必要です。REST calls require the service URL and an access key on every request. 両方を使用して検索サービスが作成されるので、Azure Cognitive Search をサブスクリプションに追加した場合は、次の手順に従って必要な情報を入手してください。A search service is created with both, so if you added Azure Cognitive Search to your subscription, follow these steps to get the necessary information:

  1. Azure portal にサインインし、ご使用の検索サービスの [概要] ページで、URL を入手します。Sign in to the Azure portal, and in your search service Overview page, get the URL. たとえば、エンドポイントは https://mydemo.search.windows.net のようになります。An example endpoint might look like https://mydemo.search.windows.net.

  2. [設定] > [キー] で、サービスに対する完全な権限の管理者キーを取得します。In Settings > Keys, get an admin key for full rights on the service. 管理キーをロールオーバーする必要がある場合に備えて、2 つの交換可能な管理キーがビジネス継続性のために提供されています。There are two interchangeable admin keys, provided for business continuity in case you need to roll one over. オブジェクトの追加、変更、および削除の要求には、主キーまたはセカンダリ キーのどちらかを使用できます。You can use either the primary or secondary key on requests for adding, modifying, and deleting objects.

HTTP エンドポイントとアクセス キーを取得するGet an HTTP endpoint and access key

すべての要求では、サービスに送信されるすべての要求に API キーが必要です。All requests require an api-key on every request sent to your service. 有効なキーがあれば、要求を送信するアプリケーションとそれを処理するサービスの間で、要求ごとに信頼を確立できます。Having a valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.

接続を設定するSet up connections

必要なサービスへの接続情報は、ソリューションの appsettings.json ファイルで指定します。Connection information to required services is specified in the appsettings.json file in the solution.

  1. Visual Studio で、DotNetHowToIndexers.sln ファイルを開きます。In Visual Studio, open the DotNetHowToIndexers.sln file.

  2. 各設定を指定できるように、ソリューション エクスプローラーで appsettings.json を開きます。In Solution Explorer, open appsettings.json so that you can populate each setting.

最初の 2 つのエントリは、Azure Cognitive Search サービスの URL と管理者キーを使用して、今すぐ指定できます。The first two entries you can fill in right now, using the URL and admin keys for your Azure Cognitive Search service. https://mydemo.search.windows.net のエンドポイントの場合、指定するサービス名は mydemo です。Given an endpoint of https://mydemo.search.windows.net, the service name to provide is mydemo.

{
  "SearchServiceName": "Put your search service name here",
  "SearchServiceAdminApiKey": "Put your primary or secondary API key here",
  "AzureSqlConnectionString": "Put your Azure SQL database connection string here",
}

最後のエントリには、既存のデータベースを指定する必要があります。The last entry requires an existing database. これは、次の手順で作成します。You'll create it in the next step.

サンプル データの準備Prepare sample data

この手順では、インデクサーがクロールできる外部データ ソースを作成します。In this step, create an external data source that an indexer can crawl. Azure Portal とサンプルの hotels.sql ファイルを使用して、Azure SQL Database にデータセットを作成することができます。You can use the Azure portal and the hotels.sql file from the sample to create the dataset in Azure SQL Database. Azure Cognitive Search で使用されるのは、ビューやクエリから生成されるようなフラット化された行セットです。Azure Cognitive Search consumes flattened rowsets, such as one generated from a view or query. サンプル ソリューションの SQL ファイルでは、単一のテーブルを作成してデータを投入します。The SQL file in the sample solution creates and populates a single table.

次の演習では、サーバーもデータベースも存在していないことを想定しています。どちらも手順 2. で作成することになります。The following exercise assumes no existing server or database, and instructs you to create both in step 2. 既にリソースがある場合には、hotels テーブルをそこに追加して、手順 4. から始めることができます。Optionally, if you have an existing resource, you can add the hotels table to it, starting at step 4.

  1. Azure portal にサインインします。Sign in to the Azure portal.

  2. データベース、サーバー、およびリソース グループを作成する Azure SQL Database を見つけるか作成します。Find or create an Azure SQL Database to create a database, server, and resource group. 既定値および一番低い価格レベルを使用してかまいません。You can use defaults and the lowest level pricing tier. サーバーを作成する利点は、後の手順でテーブルを作成して読み込むために必要な管理者ユーザー名とパスワードを指定できることです。One advantage to creating a server is that you can specify an administrator user name and password, necessary for creating and loading tables in a later step.

    [新しいデータベース] ページ

  3. [作成] をクリックして、新しいサーバーとデータベースをデプロイします。Click Create to deploy the new server and database. サーバーとデータベースがデプロイされるまで待ちます。Wait for the server and database to deploy.

  4. 新しいデータベースの [SQL Database] ページをまだ開いていない場合は開きます。Open the SQL Database page for your new database, if it's not already open. リソース名は SQL Server ではなく "SQL データベース" になっている必要があります。The resource name should say SQL database and not SQL Server.

    [SQL Database] ページ

  5. ナビゲーション ウィンドウで、 [クエリ エディター (プレビュー)] をクリックします。On the navigation pane, click Query editor (preview).

  6. [ログイン] をクリックし、サーバー管理者のユーザー名とパスワードを入力します。Click Login and enter the user name and password of server admin.

  7. [クエリを開く] をクリックし、hotels.sql の場所に移動します。Click Open query and navigate to the location of hotels.sql.

  8. ファイルを選択し、 [開く] をクリックします。Select the file and click Open. このスクリプトは次のスクリーンショットのようになります。The script should look similar to the following screenshot:

    SQL スクリプト

  9. [実行] をクリックしてクエリを実行します。Click Run to execute the query. 3 つの行について、クエリが正常に実行されたことを示すメッセージが [結果] ウィンドウに表示されます。In the Results pane, you should see a query succeeded message, for 3 rows.

  10. このテーブルから行セットが返されるようにするには、検証ステップとして次のクエリを実行します。To return a rowset from this table, you can execute the following query as a verification step:

    SELECT HotelId, HotelName, Tags FROM Hotels
    

    クエリ エディターでは、典型的なクエリである SELECT * FROM Hotels が正しく動作しません。The prototypical query, SELECT * FROM Hotels, doesn't work in the Query Editor. サンプル データでは、Location フィールドに地理座標が格納されていますが、このフィールドが現時点のエディターでは処理されません。The sample data includes geographic coordinates in the Location field, which is not handled in the editor at this time. その他の一連の列を照会するには、SELECT * FROM sys.columns WHERE object_id = OBJECT_ID('dbo.Hotels') ステートメントを実行できます。For a list of other columns to query, you can execute this statement: SELECT * FROM sys.columns WHERE object_id = OBJECT_ID('dbo.Hotels')

  11. これで外部データセットが揃ったので、データベースの ADO.NET 接続文字列をコピーします。Now that you have an external dataset, copy the ADO.NET connection string for the database. データベースの [SQL Database] ページで [設定] > [接続文字列] に移動し、ADO.NET 接続文字列をコピーします。On the SQL Database page of your database, go to Settings > Connection Strings, and copy the ADO.NET connection string.

    ADO.NET 接続文字列は次のようになります。有効なデータベース名、ユーザー名、パスワードに置き換えて使用してください。An ADO.NET connection string looks like the following example, modified to use a valid database name, user name, and password.

    Server=tcp:hotels-db.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID={your_username};Password={your_password};MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;
    
  12. Visual Studio で appsettings.json ファイルの 3 つ目のエントリとして、接続文字列を "AzureSqlConnectionString" に貼り付けます。Paste the connection string into "AzureSqlConnectionString" as the third entry in appsettings.json file in Visual Studio.

    {
      "SearchServiceName": "<placeholder-Azure-Search-service-name>",
      "SearchServiceAdminApiKey": "<placeholder-admin-key-for-Azure-Search>",
      "AzureSqlConnectionString": "Server=tcp:hotels-db.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security  Info=False;User ID={your_username};Password={your_password};MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;",
    }
    

コードの理解Understand the code

データと構成設定が済んだら、DotNetHowToIndexers.sln 内のサンプル プログラムをビルドして実行する準備は完了です。Once the data and configuration settings are in place, the sample program in DotNetHowToIndexers.sln is ready to build and run. その前に、このサンプルで使用するインデックスとインデクサーの定義を詳しく見てみましょう。Before doing that, take a minute to study the index and indexer definitions for this sample. 関連するコードは次の 2 つのファイルにあります。The relevant code is in two files:

  • hotel.cs: インデックスを定義するスキーマが含まれています。hotel.cs, containing the schema that defines the index
  • Program.cs: サービスの構造を作成したり管理したりするための関数が含まれています。Program.cs, containing the functions for creating and managing structures in your service

hotel.cs の内容In hotel.cs

インデックス スキーマは、フィールドのコレクションを定義します。この定義には、次の HotelName のフィールドの定義に見られるように、フィールドがフルテキスト検索可能かどうか、フィルター処理可能かどうか、並べ替え可能かどうかなど、許可される操作を指定する属性も含まれています。The index schema defines the fields collection, including attributes specifying allowed operations, such as whether a field is full-text searchable, filterable, or sortable as shown in the following field definition for HotelName.

. . . 
[IsSearchable, IsFilterable, IsSortable]
public string HotelName { get; set; }
. . .

その他にも、スキーマにはさまざまな要素が存在します。検索スコアを高めるためのスコア付けプロファイルやカスタム アナライザーなど、各種コンストラクトがその例です。A schema can also include other elements, including scoring profiles for boosting a search score, custom analyzers, and other constructs. ただし、このドキュメントの目的上、スキーマに含まれている定義はごくわずかで、サンプル データセットに含まれているフィールドのみがその構成要素となります。However, for our purposes, the schema is sparsely defined, consisting only of fields found in the sample datasets.

このチュートリアルでは、インデクサーで単一のデータ ソースからデータをプルしています。In this tutorial, the indexer pulls data from one data source. 実際には、同じインデックスに複数のインデクサーをアタッチして、さまざまなデータ ソースから統合された検索可能なインデックスを作成することができます。In practice, you can attach multiple indexers to the same index, creating a consolidated searchable index from multiple data sources. 必要に応じて柔軟に、データ ソースだけを変えながら同じインデックス/インデクサー ペアを使用したり、インデクサーとデータ ソースの組み合わせを変えながら 1 つのインデックスを使用したりすることができます。You can use the same index-indexer pair, varying just the data sources, or one index with various indexer and data source combinations, depending on where you need the flexibility.

Program.cs の内容In Program.cs

メイン プログラムには、クライアント、インデックス、データ ソース、インデクサーを作成するためのロジックが含まれます。The main program includes logic for creating a client, an index, a data source, and an indexer. このコードは、読者がこのプログラムを繰り返し実行する可能性を考慮し、同じ名前のリソースが既に存在しているかどうかを調べて、削除します。The code checks for and deletes existing resources of the same name, under the assumption that you might run this program multiple times.

データ ソース オブジェクトの構成には、Azure SQL に組み込まれている変更検出機能を活用するために、インデックスの増分作成を含め、Azure SQL データベース リソースに固有の設定が使用されます。The data source object is configured with settings that are specific to Azure SQL database resources, including incremental indexing for leveraging the built-in change detection features of Azure SQL. Azure SQL にあるデモ hotels データベースには、IsDeleted という名前の "論理的な削除" 列があります。The demo hotels database in Azure SQL has a "soft delete" column named IsDeleted. データベースでこの列を true に設定すると、インデクサーによって、Azure Cognitive Search インデックスから対応するドキュメントが削除されます。When this column is set to true in the database, the indexer removes the corresponding document from the Azure Cognitive Search index.

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

DataSource dataSource = DataSource.AzureSql(
    name: "azure-sql",
    sqlConnectionString: configuration["AzureSQLConnectionString"],
    tableOrViewName: "hotels",
    deletionDetectionPolicy: new SoftDeleteColumnDeletionDetectionPolicy(
        softDeleteColumnName: "IsDeleted",
        softDeleteMarkerValue: "true"));
dataSource.DataChangeDetectionPolicy = new SqlIntegratedChangeTrackingPolicy();

searchService.DataSources.CreateOrUpdateAsync(dataSource).Wait();

インデクサー オブジェクトはプラットフォームに依存しません。構成、スケジュール、起動は、ソースに関係なく同じです。An indexer object is platform-agnostic, where configuration, scheduling, and invocation are the same regardless of the source. この例のインデクサーには、スケジュールのほか、インデクサーの履歴を消去するリセット オプション、インデクサーを直ちに作成して実行するためのメソッドの呼び出しが含まれています。This example indexer includes a schedule, a reset option that clears indexer history, and calls a method to create and run the indexer immediately.

Console.WriteLine("Creating Azure SQL indexer...");
Indexer indexer = new Indexer(
    name: "azure-sql-indexer",
    dataSourceName: dataSource.Name,
    targetIndexName: index.Name,
    schedule: new IndexingSchedule(TimeSpan.FromDays(1)));
// Indexers contain metadata about how much they have already indexed
// If we already ran the sample, the indexer will remember that it already
// indexed the sample data and not run again
// To avoid this, reset the indexer if it exists
exists = await searchService.Indexers.ExistsAsync(indexer.Name);
if (exists)
{
    await searchService.Indexers.ResetAsync(indexer.Name);
}

await searchService.Indexers.CreateOrUpdateAsync(indexer);

// We created the indexer with a schedule, but we also
// want to run it immediately
Console.WriteLine("Running Azure SQL indexer...");

try
{
    await searchService.Indexers.RunAsync(indexer.Name);
}
catch (CloudException e) when (e.Response.StatusCode == (HttpStatusCode)429)
{
    Console.WriteLine("Failed to run indexer: {0}", e.Response.Content);
}

インデクサーを実行するRun the indexer

この手順では、プログラムをコンパイルして実行します。In this step, compile and run the program.

  1. ソリューション エクスプローラーで [DotNetHowToIndexers] を右クリックし、 [ビルド] を選択します。In Solution Explorer, right-click DotNetHowToIndexers and select Build.
  2. もう一度 [DotNetHowToIndexers] を右クリックし、 [デバッグ] > [新しいインスタンスを開始] の順に選択します。Again, right-click DotNetHowToIndexers, followed by Debug > Start new instance.

プログラムがデバッグ モードで実行されます。The program executes in debug mode. コンソール ウィンドウで各操作の状態が報告されます。A console window reports the status of each operation.

SQL スクリプト

コードは、Visual Studio からローカルで実行され、Azure 上の Search サービスに接続します。次に、このサービスが接続文字列を使用して Azure SQL Database に接続し、データセットを取得します。Your code runs locally in Visual Studio, connecting to your search service on Azure, which in turn uses the connection string to connect to Azure SQL Database and retrieve the dataset. このように多くの操作が伴うため、障害点となり得る箇所は複数存在しますが、エラーが発生した場合は、まず次の状況を確認してください。With this many operations, there are several potential points of failure, but if you get an error, check the following conditions first:

  • 指定する Search サービスの接続情報は、このチュートリアルのサービス名に限定されます。Search service connection information that you provide is limited to the service name in this tutorial. 完全な URL を入力した場合、インデックスの作成時に接続エラーで操作が停止します。If you entered the full URL, operations stop at index creation, with a failure to connect error.

  • appsettings.json のデータベース接続情報。Database connection information in appsettings.json. これは、ポータルから取得した ADO.NET 接続文字列に、実際のデータベースの有効なユーザー名とパスワードを反映したものであることが必要です。It should be the ADO.NET connection string obtained from the portal, modified to include a username and password that are valid for your database. ユーザー アカウントには、データを取得するためのアクセス許可が必要です。The user account must have permission to retrieve data.

  • リソース制限。Resource limits. 既に述べたように、Free レベルは、インデックス、インデクサー、データ ソースがいずれも 3 つまでに制限されています。Recall that the Free tier has limits of 3 indexes, indexers, and data sources. 上限に達した場合、新しいオブジェクトを作成できなくなります。A service at the maximum limit cannot create new objects.

インデックスを検索するSearch the index

Azure Portal にアクセスし、Search サービスの [概要] ページで、一番上の [Search エクスプローラー] をクリックし、新しいインデックスに対するクエリをいくつか送信します。In the Azure portal, in the search service Overview page, click Search explorer at the top to submit a few queries on the new index.

  1. 一番上にある [インデックスの変更] をクリックして hotels インデックスを選択します。Click Change index at the top to select the hotels index.

  2. [検索] ボタンをクリックして空の検索を実行します。Click the Search button to issue an empty search.

    インデックスの 3 つのエントリが JSON ドキュメントとして返されます。The three entries in your index are returned as JSON documents. Search エクスプローラーは、構造全体が見えるようにドキュメントを JSON 形式で返します。Search explorer returns documents in JSON so that you can view the entire structure.

  3. 次に、検索文字列として「search=river&$count=true」を入力します。Next, enter a search string: search=river&$count=true.

    このクエリは、river という語についてフルテキスト検索を呼び出すもので、その結果には、一致したドキュメントの件数が含まれます。This query invokes full text search on the term river, and the result includes a count of the matching documents. 一致したドキュメントの件数は、インデックスが大きく数千から数百万のドキュメントが含まれている場合のテストで役立ちます。Returning the count of matching documents is helpful in testing scenarios when you have a large index with thousands or millions of documents. 今回のケースで、このクエリに一致するドキュメントは 1 件だけです。In this case, only one document matches the query.

  4. 最後に、JSON 出力を必要なフィールドに限定するため、検索文字列として「search=river&$count=true&$select=hotelId, baseRate, description」を入力します。Lastly, enter a search string that limits the JSON output to fields of interest: search=river&$count=true&$select=hotelId, baseRate, description.

    クエリの応答が選択フィールドに制限され、より簡潔な出力内容が得られます。The query response is reduced to selected fields, resulting in more concise output.

インデクサーの構成を確認するView indexer configuration

ポータルには、先ほどプログラムで作成したものも含むすべてのインデクサーが一覧表示されます。All indexers, including the one you just created programmatically, are listed in the portal. インデクサーの定義を開いてそのデータ ソースを確認したり、新たに追加された行や変更された行を取得するための更新スケジュールを構成したりすることができます。You can open an indexer definition and view its data source, or configure a refresh schedule to pick up new and changed rows.

  1. Azure portal にサインインし、検索サービスの [概要] ページで、 [インデックス][インデクサー][データ ソース] のリンクをクリックします。Sign in to the Azure portal, and in your search service Overview page, click the links for Indexes, Indexers, and Data Sources.

  2. 各オブジェクトを選択して構成設定を表示または変更します。Select individual objects to view or modify configuration settings.

    インデクサーとデータ ソースのタイル

リソースのクリーンアップClean up resources

チュートリアルの後で最も速くクリーンアップする方法は、Azure Cognitive Search サービスが含まれているリソース グループを削除することです。The fastest way to clean up after a tutorial is by deleting the resource group containing the Azure Cognitive Search service. リソース グループを削除することで、そのすべての内容を完全に削除することができます。You can delete the resource group now to permanently delete everything in it. ポータルでは、リソース グループ名は Azure Cognitive Search サービスの [概要] ページに表示されます。In the portal, the resource group name is on the Overview page of Azure Cognitive Search service.

次の手順Next steps

インデクサー パイプラインには、AI エンリッチメント アルゴリズムをアタッチすることができます。You can attach AI enrichment algorithms to an indexer pipeline. 引き続き次のチュートリアルに進んでください。As a next step, continue on with the following tutorial.