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

これは、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 クラスのインスタンスを作成する必要があります。 これを可能にするには、

1. URL エンドポイント
2. API キー

を指定します。 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 データ セットを使用しています。これらはほんの一部の基本です。詳細については、サンプルをチェックしてください。

• クエリ実行
  • 検索結果の辞書のように使用 SearchDocument する
  • 検索結果に Java モデルを使用する
  • 検索オプション
• インデックスの作成
• インデックスへのドキュメントの追加
• インデックスから特定のドキュメントを取得する
• 非同期 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 クライアントの構成または変更に関する詳細情報が提供されます。

次の手順

• サンプルについては、 こちらを参照してください。
• デモまたは詳細なビデオを見る
• Azure Cognitive Search サービスの詳細を確認する

共同作成

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

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

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