Java 用Azure Cognitive Search クライアントライブラリ - バージョン 11.5.12

[アーティクル]
10/21/2023

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

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

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

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

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

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

作業の開始

パッケージを組み込む

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-search-documents</artifactId>
    <version>11.5.12</version>
</dependency>

前提条件

バージョン 8 以降の Java Development Kit (JDK)
Azure サブスクリプション
Azure Cognitive Search サービス
新しい検索サービスを作成するには、Azure portal、Azure PowerShell、または Azure CLI を使用できます。 Azure CLI を使用して開始するための無料インスタンスを作成する例を次に示します。

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

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

クライアントを認証する

Azure Cognitive Search サービスを操作するには、Search Client クラスのインスタンスを作成する必要があります。これを可能にするには、

を指定します。 api-key は、検索サービスエンドポイントへのアクセスを認証するための唯一のメカニズムです。 api-key は、Azure portalまたは Azure CLI から取得できます。

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

注:

上記の Azure CLI スニペットの例では、管理者キーを取得します。これにより、API を探索するときに簡単にアクセスできますが、慎重に管理する必要があります。
検索サービスにアクセスするために使用されるキーには、admin(read-write) キーと query(読み取り専用) キーの 2 種類があります。クライアントアプリでアクセスと操作を制限することは、サービスで検索アセットを保護するために不可欠です。クライアントアプリから発信されたクエリには、常に管理者キーではなくクエリキーを使用します。

SDK には 3 つのクライアントが用意されています。

SearchIndexClient インデックスとシノニムマップに対する CRUD 操作の場合。
SearchIndexerClient インデクサー、日付ソース、スキルセットに対する CRUD 操作の場合。
SearchClient すべてのドキュメント操作に対して。

SearchIndexClient を作成する

をSearchIndexClient/SearchIndexAsyncClient作成するには、Azure Cognitive Search サービス URL エンドポイントと管理キーの値が必要です。

SearchIndexClient searchIndexClient = new SearchIndexClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(apiKey))
    .buildClient();

または

SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(apiKey))
    .buildAsyncClient();

SearchIndexerClient を作成する

をSearchIndexerClient/SearchIndexerAsyncClient作成するには、Azure Cognitive Search サービス URL エンドポイントと管理キーの値が必要です。

SearchIndexerClient searchIndexerClient = new SearchIndexerClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(apiKey))
    .buildClient();

または

SearchIndexerAsyncClient searchIndexerAsyncClient = new SearchIndexerClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(apiKey))
    .buildAsyncClient();

SearchClient を作成する

Azure Cognitive Search サービス URL エンドポイントと管理キーの値を取得したら、既存のインデックス名を使用してをSearchClient/SearchAsyncClient作成できます。

SearchClient searchClient = new SearchClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(adminKey))
    .indexName(indexName)
    .buildClient();

または

SearchAsyncClient searchAsyncClient = new SearchClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(adminKey))
    .indexName(indexName)
    .buildAsyncClient();

最初の検索クエリを送信する

Azure Cognitive Searchで実行するには、最初にこのガイドに従ってインデックスを作成します。インデックスを作成したら、次のサンプルを使用して SDK の使用を開始できます。

主要な概念

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

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

例

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

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

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

クエリ実行

検索クエリから返されるデータを操作するには、2 つの方法があります。

「高級」ホテルを検索してそれらを探索しましょう。

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

SearchDocument は、独自の型を指定しない場合にクエリから返される既定の型です。ここでは、検索を実行し、結果を列挙し、の辞書インデクサーを使用してデータを SearchDocument抽出します。

for (SearchResult searchResult : searchClient.search("luxury")) {
    SearchDocument doc = searchResult.getDocument(SearchDocument.class);
    String id = (String) doc.get("hotelId");
    String name = (String) doc.get("hotelName");
    System.out.printf("This is hotelId %s, and this is hotel name %s.%n", id, name);
}

検索結果に Java モデルクラスを使用する

Hotel クラスを定義します。

public class Hotel {
    private String id;
    private String name;

    public String getId() {
        return id;
    }

    public Hotel setId(String id) {
        this.id = id;
        return this;
    }

    public String getName() {
        return name;
    }

    public Hotel setName(String name) {
        this.name = name;
        return this;
    }
}

クエリを実行する場合は、の SearchDocument 代わりに使用します。

for (SearchResult searchResult : searchClient.search("luxury")) {
    Hotel doc = searchResult.getDocument(Hotel.class);
    String id = doc.getId();
    String name = doc.getName();
    System.out.printf("This is hotelId %s, and this is hotel name %s.%n", id, name);
}

検索インデックスのスキーマがわかっている場合は、Java モデルクラスを作成することをお勧めします。

検索オプション

は SearchOptions 、クエリの動作を強力に制御します。

評価の良いラグジュアリーホテルトップ5を検索しましょう。

SearchOptions options = new SearchOptions()
    .setFilter("rating ge 4")
    .setOrderBy("rating desc")
    .setTop(5);
SearchPagedIterable searchResultsIterable = searchClient.search("luxury", options, Context.NONE);
// ...

インデックスの作成

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

検索インデックスの検索フィールドを準備するには、複数の方法があります。基本的なニーズに合わせて、およびにSearchIndexClient静的ヘルパーメソッドbuildSearchFieldsを提供しますSearchIndexAsyncClient。これは、Java POJO クラスをにList<SearchField>変換できます。には 3 つの注釈SimpleFieldPropertySearchFieldPropertyがあり、FieldBuilderIgnoreモデルクラスのフィールドを構成します。

List<SearchField> searchFields = SearchIndexClient.buildSearchFields(Hotel.class, null);
searchIndexClient.createIndex(new SearchIndex("index", searchFields));

高度なシナリオでは、を使用して検索フィールドを SearchField 直接作成できます。

List<SearchField> searchFieldList = new ArrayList<>();
searchFieldList.add(new SearchField("hotelId", SearchFieldDataType.STRING)
    .setKey(true)
    .setFilterable(true)
    .setSortable(true));

searchFieldList.add(new SearchField("hotelName", SearchFieldDataType.STRING)
    .setSearchable(true)
    .setFilterable(true)
    .setSortable(true));
searchFieldList.add(new SearchField("description", SearchFieldDataType.STRING)
    .setSearchable(true)
    .setAnalyzerName(LexicalAnalyzerName.EU_LUCENE));
searchFieldList.add(new SearchField("tags", SearchFieldDataType.collection(SearchFieldDataType.STRING))
    .setSearchable(true)
    .setFilterable(true)
    .setFacetable(true));
searchFieldList.add(new SearchField("address", SearchFieldDataType.COMPLEX)
    .setFields(new SearchField("streetAddress", SearchFieldDataType.STRING).setSearchable(true),
        new SearchField("city", SearchFieldDataType.STRING)
            .setSearchable(true)
            .setFilterable(true)
            .setFacetable(true)
            .setSortable(true),
        new SearchField("stateProvince", SearchFieldDataType.STRING)
            .setSearchable(true)
            .setFilterable(true)
            .setFacetable(true)
            .setSortable(true),
        new SearchField("country", SearchFieldDataType.STRING)
            .setSearchable(true)
            .setFilterable(true)
            .setFacetable(true)
            .setSortable(true),
        new SearchField("postalCode", SearchFieldDataType.STRING)
            .setSearchable(true)
            .setFilterable(true)
            .setFacetable(true)
            .setSortable(true)
    ));

// Prepare suggester.
SearchSuggester suggester = new SearchSuggester("sg", Collections.singletonList("hotelName"));
// Prepare SearchIndex with index name and search fields.
SearchIndex index = new SearchIndex("hotels").setFields(searchFieldList).setSuggesters(suggester);
// Create an index
searchIndexClient.createIndex(index);

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

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

Hotel hotel = searchClient.getDocument("1", Hotel.class);
System.out.printf("This is hotelId %s, and this is hotel name %s.%n", hotel.getId(), hotel.getName());

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

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

IndexDocumentsBatch<Hotel> batch = new IndexDocumentsBatch<>();
batch.addUploadActions(Collections.singletonList(new Hotel().setId("783").setName("Upload Inn")));
batch.addMergeActions(Collections.singletonList(new Hotel().setId("12").setName("Renovated Ranch")));
searchClient.indexDocuments(batch);

個々のアクションのいずれかが失敗した場合、要求は既定でスロー IndexBatchException され、失敗したドキュメントで再試行するためにを使用 findFailedActionsToRetry できます。オプションもあります throwOnAnyError 。これをに false 設定して、検査用のを使用して成功した応答を IndexDocumentsResult 得ることができます。

非同期 API

これまでの例では同期 API を使用してきましたが、非同期 API の完全なサポートも提供しています。 SearchAsyncClient を使用する必要があります。

searchAsyncClient.search("luxury")
    .subscribe(result -> {
        Hotel hotel = result.getDocument(Hotel.class);
        System.out.printf("This is hotelId %s, and this is hotel name %s.%n", hotel.getId(), hotel.getName());
    });

National Cloud での認証

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

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

// Create a SearchClient that will authenticate through AAD in the China national cloud.
SearchClient searchClient = new SearchClientBuilder()
    .endpoint(endpoint)
    .indexName(indexName)
    .credential(new DefaultAzureCredentialBuilder()
        .authorityHost(AzureAuthorityHosts.AZURE_CHINA)
        .build())
    .audience(SearchAudience.AZURE_CHINA)
    .buildClient();

トラブルシューティング

全般

この Java クライアントライブラリを使用してAzure Cognitive Searchを操作すると、サービスによって返されるエラーは、REST API 要求に対して返されるのと同じ HTTP 状態コードに対応します。たとえば、インデックスに存在しないドキュメントを取得しようとすると、サービスからエラーが返 404 されます。

検索エラー応答の処理

失敗した Search API 操作は、と共に HttpResponseException をスローします Status codes。これらのエラーの多くは回復可能です。

try {
    Iterable<SearchResult> results = searchClient.search("hotel");
} catch (HttpResponseException ex) {
    // The exception contains the HTTP status code and the detailed message
    // returned from the search service
    HttpResponse response = ex.getResponse();
    System.out.println("Status Code: " + response.getStatusCode());
    System.out.println("Message: " + ex.getMessage());
}

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

ログ記録の有効化

Azure SDK for Java には、アプリケーションエラーのトラブルシューティングと解決の迅速化に役立つ一貫したログ記録のストーリーが用意されています。生成されたログでは、最終状態に達する前のアプリケーションのフローがキャプチャされ、根本原因を特定するのに役立ちます。ログ記録の有効化に関するガイダンスについては、ログ Wiki を参照してください。

既定の HTTP クライアント

既定では、Netty ベースの HTTP クライアントが使用されます。 HTTP クライアント Wiki では、HTTP クライアントの構成または変更に関する詳細情報が提供されます。

次の手順

共同作成

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

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

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

Java 用Azure Cognitive Search クライアントライブラリ - バージョン 11.5.12

作業の開始

パッケージを組み込む

前提条件

クライアントを認証する

SearchIndexClient を作成する

SearchIndexerClient を作成する

SearchClient を作成する

最初の検索クエリを送信する

主要な概念

例

クエリ実行

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

検索結果に Java モデルクラスを使用する

検索オプション

インデックスの作成

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

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

非同期 API

National Cloud での認証

トラブルシューティング

全般

検索エラー応答の処理

ログ記録の有効化

既定の HTTP クライアント

次の手順

共同作成

フィードバック

フィードバック

その他のリソース

Java 用Azure Cognitive Search クライアント ライブラリ - バージョン 11.5.12

作業の開始

パッケージを組み込む

前提条件

クライアントを認証する

SearchIndexClient を作成する

SearchIndexerClient を作成する

SearchClient を作成する

最初の検索クエリを送信する

主要な概念

例

クエリ実行

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

検索結果に Java モデル クラスを使用する

検索オプション

インデックスの作成

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

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

非同期 API

National Cloud での認証

トラブルシューティング

全般

検索エラー応答の処理

ログ記録の有効化

既定の HTTP クライアント

次の手順

共同作成

フィードバック

フィードバック

その他のリソース

Java 用Azure Cognitive Search クライアントライブラリ - バージョン 11.5.12

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

検索結果に Java モデルクラスを使用する