次の方法で共有


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

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

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

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

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

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

ソースコード | パッケージ (NuGet) | API リファレンス ドキュメント | REST API のドキュメント | 製品ドキュメント | サンプル

作業の開始

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

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

dotnet add package Azure.Search.Documents

前提条件

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

新しい検索サービスを作成するには、Azure portalAzure 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 種類のメインクライアントを通じて、これらのリソースに対する操作を公開します。

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

スレッド セーフ

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

その他の概念

クライアント オプション | 応答 | へのアクセス実行時間の長い操作 | エラーの | 処理診断 | あざける | クライアントの有効期間

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

高度な認証

クエリ実行

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

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

モデルが不明または変更できないシナリオでは、便利な SimpleFieldSearchableField、または 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;
}

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

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

次の手順

共同作成

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

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

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

インプレッション数