.NET 用Azure Cognitive Search クライアントライブラリ - バージョン 11.4.0

[アーティクル]
04/18/2023

Azure Cognitive Search は、Web、モバイル、およびエンタープライズアプリケーションのプライベートな異種コンテンツに対するリッチな検索機能を追加するための API とツールを開発者に提供する、サービスとしての検索クラウドソリューションです。

Azure Cognitive Search サービスは、次のアプリケーションシナリオに適しています。

さまざまなコンテンツタイプを 1 つの検索可能なインデックスに統合します。インデックスを設定するには、コンテンツを含む JSON ドキュメントをプッシュするか、データが既に Azure にある場合は、データを自動的にプルするインデクサーを作成します。
インデクサーにスキルセットをアタッチして、画像や大きなテキストドキュメントから検索可能なコンテンツを作成します。スキルセットは、組み込みの OCR、エンティティ認識、キーフレーズ抽出、言語検出、テキスト翻訳、センチメント分析のために、Cognitive Services の AI を活用します。データインジェスト中にコンテンツの外部処理を統合するためのカスタムスキルを追加することもできます。
検索クライアントアプリケーションで、商用 Web 検索エンジンと同様のクエリロジックとユーザーエクスペリエンスを実装します。

Azure.Search.Documents クライアントライブラリを使用して、次の手順を実行します。

あいまい検索、ワイルドカード検索、正規表現を含むシンプルで高度なクエリフォームのクエリを送信します。
ファセットナビゲーション、地理空間検索、またはフィルター条件に基づいて結果を絞り込むために、フィルター処理されたクエリを実装します。
検索インデックスを作成および管理します。
検索インデックス内のドキュメントをアップロードおよび更新します。
Azure からインデックスにデータをプルするインデクサーを作成および管理します。
データインジェストに AI エンリッチメントを追加するスキルセットを作成および管理します。
高度なテキスト分析または多言語コンテンツ用のアナライザーを作成および管理します。
スコアリングプロファイルを使用して結果を最適化し、ビジネスロジックまたは鮮度を考慮します。

作業の開始

パッケージをインストールする

NuGet を使用して .NET 用のAzure Cognitive Search クライアントライブラリをインストールします。

dotnet add package Azure.Search.Documents

前提条件

このパッケージを使用するには、 Azure サブスクリプションと検索サービスが必要です。

新しい検索サービスを作成するには、Azure portal、Azure PowerShell、または Azure CLI を使用できます。 Azure CLI を使用して開始するための無料インスタンスを作成する例を次に示します。

az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus

使用可能なオプションの詳細については、「価格レベルの選択」を参照してください。

クライアントを認証する

Search サービスへのすべての HTTP 要求には、対象のサービス用に生成された API キーが必要です。 api-key は、検索サービスエンドポイントへのアクセスを認証するための唯一のメカニズムです。 api-key は、Azure portalまたは Azure CLI から取得できます。

az search admin-key show --service-name <mysearch> --resource-group <mysearch-rg>

検索サービスにアクセスするために使用されるキーには、 admin(read-write) キーと query(read-only) キーの 2 種類があります。クライアントアプリでアクセスと操作を制限することは、サービスで検索アセットを保護するために不可欠です。クライアントアプリから発信されたクエリには、常に管理者キーではなくクエリキーを使用します。

注: 上記の Azure CLI スニペットの例では、API の探索を始めるのが簡単になるように管理キーを取得しますが、慎重に管理する必要があります。

api-key を使用して新しい SearchClientを作成できます。

string indexName = "nycjobs";

// Get the service endpoint and API key from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");

// Create a client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchClient client = new SearchClient(endpoint, indexName, credential);

ASP.NET Core

ASP.NET Core アプリに依存関係として挿入SearchClientするには、まずパッケージ Microsoft.Extensions.Azureをインストールします。次に、メソッドにクライアントを Startup.ConfigureServices 登録します。

public void ConfigureServices(IServiceCollection services)
{
    services.AddAzureClients(builder =>
    {
        builder.AddSearchClient(Configuration.GetSection("SearchClient"));
    });
  
    services.AddControllers();
}

上記のコードを使用するには、これを構成に追加します。

{
    "SearchClient": {
      "endpoint": "https://<resource-name>.search.windows.net",
      "indexname": "nycjobs"
    }
}

また、クライアントを認証するためにリソースキーを指定する必要がありますが、その情報を構成に配置しないでください。代わりに、開発中はユーザーシークレットを使用します。次を secrets.json に追加します。

{
    "SearchClient": {
      "credential": { "key": "<you resource key>" }
    }
}

運用環境で実行する場合は、環境変数を使用することをお勧めします。

SEARCH__CREDENTIAL__KEY="..."

または、Azure Key Vault などのシークレットを格納する他の安全な方法を使用します。

ASP.NET Core アプリでの依存関係の挿入の詳細については、「Azure SDK for .NET を使用した依存関係の挿入」を参照してください。

主要な概念

Azure Cognitive Search サービスには、JSON ドキュメントの形式で検索可能なデータの永続的なストレージを提供する 1 つ以上のインデックスが含まれています。 (検索を初めて使用する場合は、インデックスとデータベーステーブルの間で非常に大まかな類似を行うことができます)。Azure.Search.Documents クライアントライブラリは、3 種類のメインクライアントを通じて、これらのリソースに対する操作を公開します。

SearchClient は次の場合に役立ちます。
- 豊富なクエリと強力なデータシェイプを使用してインデックス付きドキュメントを検索する
- インデックス内のドキュメントに基づいて部分的に型指定された検索語句をオートコンプリートする
- ユーザーの種類としてドキュメント内で最も一致する可能性の高いテキストを提案する
- インデックスからドキュメントドキュメントを追加、更新、または削除する
SearchIndexClient を使用すると、次のことを実行できます。
- 検索インデックスを作成、削除、更新、または構成する
- クエリを展開または書き換えるカスタムシノニムマップを宣言する
SearchIndexerClient を使用すると、次のことを実行できます。
- インデクサーを作成してデータソースを自動的にクロールする
- AI を活用したスキルセットを定義してデータを変換および強化する

Azure.Search.Documentsクライアントライブラリ (v11) は、アプリケーションで検索テクノロジを使用する .NET 開発者向けのまったく新しいオファリングです。似たような API を備えた古いフル機能 Microsoft.Azure.Search のクライアントライブラリ (v10) があるため、オンラインリソースを探索する際の混乱を避けるために注意してください。私たちを探している場合は、名前空間using Azure.Search.Documents;をチェックすることをお勧めします。

スレッドセーフ

すべてのクライアントインスタンスメソッドがスレッドセーフであり、相互に独立していることを保証します (ガイドライン)。これにより、クライアントインスタンスの再利用に関する推奨事項は、スレッド間でも常に安全になります。

その他の概念

例

次の例では、すべて、Azure portalから独自のインデックスにインポートできる単純な Hotel データセットを使用しています。これらはほんの一部の基本です。詳細については、サンプルをチェックしてください。

クエリ実行
インデックスの作成
インデックスへのドキュメントの追加
インデックスから特定のドキュメントを取得する
非同期 API

高度な認証

国内クラウドで認証できるクライアントを作成する

クエリ実行

まず、名前空間をインポートします。

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;

次に、を SearchClient 作成してホテル検索インデックスにアクセスします。

// Get the service endpoint and API key from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");
string indexName = "hotels";

// Create a client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchClient client = new SearchClient(endpoint, indexName, credential);

検索クエリから返されるデータを操作するには、2 つの方法があります。「高級」ホテルを検索してそれらを探索しましょう。

検索結果に C# の種類を使用する

独自の C# 型をからSystem.Text.Json属性で装飾できます。

public class Hotel
{
    [JsonPropertyName("HotelId")]
    [SimpleField(IsKey = true, IsFilterable = true, IsSortable = true)]
    public string Id { get; set; }

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

次に、厳密に型指定された検索結果を返すためにクエリを実行するときに、それらを型パラメーターとして使用します。

SearchResults<Hotel> response = client.Search<Hotel>("luxury");
foreach (SearchResult<Hotel> result in response.GetResults())
{
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.Id}: {doc.Name}");
}

検索インデックスを使用していてスキーマがわかっている場合は、C# 型を作成することをお勧めします。

検索結果の辞書のように使用 `SearchDocument` する

検索結果に独自の種類がない場合は、 SearchDocument 代わりにを使用できます。ここでは、検索を実行し、結果を列挙し、の辞書インデクサーを使用してデータを SearchDocument抽出します。

SearchResults<SearchDocument> response = client.Search<SearchDocument>("luxury");
foreach (SearchResult<SearchDocument> result in response.GetResults())
{
    SearchDocument doc = result.Document;
    string id = (string)doc["HotelId"];
    string name = (string)doc["HotelName"];
    Console.WriteLine("{id}: {name}");
}

SearchOptions

は SearchOptions 、クエリの動作を強力に制御します。評価の良いラグジュアリーホテルトップ5を検索しましょう。

int stars = 4;
SearchOptions options = new SearchOptions
{
    // Filter to only Rating greater than or equal our preference
    Filter = SearchFilter.Create($"Rating ge {stars}"),
    Size = 5, // Take only 5 results
    OrderBy = { "Rating desc" } // Sort by Rating from high to low
};
SearchResults<Hotel> response = client.Search<Hotel>("luxury", options);
// ...

インデックスの作成

を SearchIndexClient 使用して検索インデックスを作成できます。フィールドは、FieldBuilder を使用してモデルクラスから定義できます。インデックスでは、suggester、字句アナライザーなどを定義することもできます。

Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");

// Create a service client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchIndexClient client = new SearchIndexClient(endpoint, credential);

// Create the index using FieldBuilder.
SearchIndex index = new SearchIndex("hotels")
{
    Fields = new FieldBuilder().Build(typeof(Hotel)),
    Suggesters =
    {
        // Suggest query terms from the hotelName field.
        new SearchSuggester("sg", "hotelName")
    }
};

client.CreateIndex(index);

モデルが不明または変更できないシナリオでは、便利な SimpleField、 SearchableField、または ComplexField クラスを使用してフィールドを明示的に作成することもできます。

// Create the index using field definitions.
SearchIndex index = new SearchIndex("hotels")
{
    Fields =
    {
        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
        new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
        new SearchableField("tags", collection: true) { IsFilterable = true, IsFacetable = true },
        new ComplexField("address")
        {
            Fields =
            {
                new SearchableField("streetAddress"),
                new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("country") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
            }
        }
    },
    Suggesters =
    {
        // Suggest query terms from the hotelName field.
        new SearchSuggester("sg", "hotelName")
    }
};

client.CreateIndex(index);

インデックスへのドキュメントの追加

1 つのバッチ要求で、インデックスから、、、およびDelete複数のドキュメントを作成できます。UploadMergeMergeOrUpload マージには、注意すべき特別な規則がいくつかあります。

IndexDocumentsBatch<Hotel> batch = IndexDocumentsBatch.Create(
    IndexDocumentsAction.Upload(new Hotel { Id = "783", Name = "Upload Inn" }),
    IndexDocumentsAction.Merge(new Hotel { Id = "12", Name = "Renovated Ranch" }));

IndexDocumentsOptions options = new IndexDocumentsOptions { ThrowOnAnyError = true };
client.IndexDocuments(batch, options);

個々のアクションのいずれかが失敗し、検査のためにが返された場合でも、要求は IndexDocumentsResult 成功します。バッチ全体の成功または失敗のみを気にする場合は、オプションもあります ThrowOnAnyError 。

インデックスから特定のドキュメントを取得する

キーワードと省略可能なフィルターを使用してドキュメントのクエリを実行するだけでなく、キーがわかっている場合は、インデックスから特定のドキュメントを取得できます。たとえば、クエリからキーを取得し、それに関する詳細情報を表示したり、顧客をそのドキュメントに移動したりできます。

Hotel doc = client.GetDocument<Hotel>("1");
Console.WriteLine($"{doc.Id}: {doc.Name}");

非同期 API

これまでの例はすべて同期 API を使用してきましたが、非同期 API も完全にサポートしています。通常は、メソッドと await メソッドの名前にサフィックスを追加Asyncするだけです。

SearchResults<Hotel> response = await client.SearchAsync<Hotel>("luxury");
await foreach (SearchResult<Hotel> result in response.GetResultsAsync())
{
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.Id}: {doc.Name}");
}

National Cloud での認証

National Cloud で認証するには、クライアント構成に次の追加を行う必要があります。

AuthorityHost資格情報オプションまたは環境変数を使用して、を設定しますAZURE_AUTHORITY_HOST
でを設定するAudienceSearchClientOptions

// Create a SearchClient that will authenticate through AAD in the China national cloud
string indexName = "nycjobs";
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
SearchClient client = new SearchClient(endpoint, indexName,
    new DefaultAzureCredential(
        new DefaultAzureCredentialOptions()
        {
            AuthorityHost = AzureAuthorityHosts.AzureChina
        }),
    new SearchClientOptions()
    {
        Audience = SearchAudience.AzureChina
    });

トラブルシューティング

失敗した Azure.Search.Documents 操作では、役に立つStatusコードを含むがRequestFailedExceptionスローされます。これらのエラーの多くは回復可能です。

try
{
    return client.GetDocument<Hotel>("12345");
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    Console.WriteLine("We couldn't find the hotel you are looking for!");
    Console.WriteLine("Please try selecting another.");
    return null;
}

また、サービスに対して行う要求の詳細を確認する場合は、コンソールのログ記録を簡単に有効にすることもできます。

さまざまな障害シナリオを診断する方法の詳細については、トラブルシューティングガイドを参照してください。

次の手順

Azure.Search.Documents とサンプルをさらに詳しく見る
デモまたは詳細なビデオを見る
Azure Cognitive Search サービスの詳細を読む

共同作成

このライブラリの構築、テスト、および投稿の詳細については、検索 CONTRIBUTING.md を参照してください。

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。詳細については、「 cla.microsoft.com」を参照してください。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

次の方法で共有

.NET 用Azure Cognitive Search クライアントライブラリ - バージョン 11.4.0

作業の開始

パッケージをインストールする

前提条件

クライアントを認証する

ASP.NET Core

主要な概念

スレッドセーフ

その他の概念

例

高度な認証

クエリ実行

検索結果に C# の種類を使用する

検索結果の辞書のように使用 `SearchDocument` する

SearchOptions

インデックスの作成

インデックスへのドキュメントの追加

インデックスから特定のドキュメントを取得する

非同期 API

National Cloud での認証

トラブルシューティング

次の手順

共同作成

フィードバック

その他のリソース

次の方法で共有

.NET 用Azure Cognitive Search クライアント ライブラリ - バージョン 11.4.0

作業の開始

パッケージをインストールする

前提条件

クライアントを認証する

ASP.NET Core

主要な概念

スレッド セーフ

その他の概念

例

高度な認証

クエリ実行

検索結果に C# の種類を使用する

検索結果の辞書のように使用 SearchDocument する

SearchOptions

インデックスの作成

インデックスへのドキュメントの追加

インデックスから特定のドキュメントを取得する

非同期 API

National Cloud での認証

トラブルシューティング

次の手順

共同作成

フィードバック

その他のリソース

.NET 用Azure Cognitive Search クライアントライブラリ - バージョン 11.4.0

スレッドセーフ

検索結果の辞書のように使用 `SearchDocument` する