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

[アーティクル]
02/14/2023

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

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

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

クライアントライブラリを使用して、次の @azure/search-documents 手順を実行します。

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

作業の開始

`@azure/search-documents` パッケージのインストール

npm install @azure/search-documents

現在サポートされている環境

Node.js の LTS バージョン
Safari、Chrome、Edge、Firefox の最新バージョン。

詳細については、Microsoft のサポートポリシーを参照してください。

前提条件

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

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

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

クライアントを認証する

検索サービスに対するすべての要求には、サービス専用に生成された API キーが必要です。 API キーは、検索サービスエンドポイントへのアクセスを認証するための唯一のメカニズムです。

api-key は、Azure portalまたは Azure CLI から取得できます。

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

または、Azure Portal のリソース情報からエンドポイントと管理キーを取得することもできます。

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

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

API キーを取得したら、次のように使用できます。

const {
  SearchClient,
  SearchIndexClient,
  SearchIndexerClient,
  AzureKeyCredential,
} = require("@azure/search-documents");

// To query and manipulate documents
const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>")
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"));

// To manage indexers, datasources and skillsets
const indexerClient = new SearchIndexerClient("<endpoint>", new AzureKeyCredential("<apiKey>"));

National Cloud での認証

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

でを設定します。AudienceSearchClientOptions

const {
  SearchClient,
  SearchIndexClient,
  SearchIndexerClient,
  AzureKeyCredential,
  KnownSearchAudience,
} = require("@azure/search-documents");

// To query and manipulate documents
const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>"),
  {
    audience: KnownSearchAudience.AzureChina,
  }
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"), {
  audience: KnownSearchAudience.AzureChina,
});

// To manage indexers, datasources and skillsets
const indexerClient = new SearchIndexerClient("<endpoint>", new AzureKeyCredential("<apiKey>"), {
  audience: KnownSearchAudience.AzureChina,
});

主要な概念

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

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

注: 呼び出す API にはクロスオリジンリソース共有 (CORS) がサポートされていないため、これらのクライアントはブラウザーで機能できません。

TypeScript/JavaScript 固有の概念

ドキュメント

検索インデックス内に格納されている項目。このドキュメントの図形は、を使用して Fieldインデックスで説明されています。各フィールドには、名前、データ型、および検索可能またはフィルター可能な場合など、追加のメタデータがあります。

改ページ位置の自動修正

通常は、検索結果のサブセットを一度にユーザーに表示する必要があります。これをサポートするには、パラメーターと includeTotalCount パラメーターをtopskip使用して、検索結果の上にページングされたエクスペリエンスを提供できます。

ドキュメントフィールドのエンコード

インデックスでサポートされているデータ型は、API 要求/応答の JSON 型にマップされます。 JS クライアントライブラリは、いくつかの例外を除き、ほとんど同じ状態を維持します。

Edm.DateTimeOffset は JS Dateに変換されます。
Edm.GeographyPoint は、クライアントライブラリによってエクスポートされた型に変換されます GeographyPoint 。
型の number 特殊な値 (NaN、Infinity、-Infinity) は、REST API の文字列としてシリアル化されますが、クライアントライブラリによってに number 変換されます。

注: データ型は、インデックススキーマのフィールド型ではなく、値に基づいて変換されます。つまり、フィールドの値として ISO8601 日付文字列 (例: "2020-03-06T18:48:27.896Z") がある場合、スキーマに保存する方法に関係なく、日付に変換されます。

例

次の例では、基本を示しています。詳細については、サンプルを確認してください。

インデックスの作成
インデックスから特定のドキュメントを取得する
インデックスへのドキュメントの追加
ドキュメントで検索を実行する

インデックスを作成する

const { SearchIndexClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const result = await client.createIndex({
    name: "example-index",
    fields: [
      {
        type: "Edm.String",
        name: "id",
        key: true,
      },
      {
        type: "Edm.Double",
        name: "awesomenessLevel",
        sortable: true,
        filterable: true,
        facetable: true,
      },
      {
        type: "Edm.String",
        name: "description",
        searchable: true,
      },
      {
        type: "Edm.ComplexType",
        name: "details",
        fields: [
          {
            type: "Collection(Edm.String)",
            name: "tags",
            searchable: true,
          },
        ],
      },
      {
        type: "Edm.Int32",
        name: "hiddenWeight",
        hidden: true,
      },
    ],
  });

  console.log(result);
}

main();

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

特定のドキュメントは、主キー値によって取得できます。

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>")
);

async function main() {
  const result = await client.getDocument("1234");
  console.log(result);
}

main();

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

複数のドキュメントをバッチ内のインデックスにアップロードできます。

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>")
);

async function main() {
  const uploadResult = await client.uploadDocuments([
    // JSON objects matching the shape of the client's index
    {},
    {},
    {},
  ]);
  for (const result of uploadResult.results) {
    console.log(`Uploaded ${result.key}; succeeded? ${result.succeeded}`);
  }
}

main();

ドキュメントで検索を実行する

特定のクエリのすべての結果を一覧表示するには、単純なクエリ構文を使用する検索文字列でを使用searchできます。

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>")
);

async function main() {
  const searchResults = await client.search("wifi -luxury");
  for await (const result of searchResults.results) {
    console.log(result);
  }
}

main();

Lucene 構文を使用するより高度な検索の場合は、をにfull指定queryTypeします。

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>")
);

async function main() {
  const searchResults = await client.search('Category:budget AND "recently renovated"^3', {
    queryType: "full",
    searchMode: "all",
  });
  for await (const result of searchResults.results) {
    console.log(result);
  }
}

main();

TypeScript を使用したクエリ

TypeScript SearchClient では、インデックスドキュメントのモデル形状であるジェネリックパラメーターを受け取ります。これにより、結果で返されるフィールドの厳密に型指定された検索を実行できます。 TypeScript は、パラメーターを指定するときに返されるフィールドを select 確認することもできます。

import { SearchClient, AzureKeyCredential } from "@azure/search-documents";

// An example schema for documents in the index
interface Hotel {
  HotelId: string;
  HotelName: string;
  Description: string;
  ParkingIncluded: boolean;
  LastRenovationDate: Date;
  Rating: number;
}

const client = new SearchClient<Hotel>(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>")
);

async function main() {
  const searchResults = await client.search("wifi -luxury", {
    // Only fields in Hotel can be added to this array.
    // TS will complain if one is misspelled.
    select: ["HotelId", "HotelName", "Rating"],
  });

  for await (const result of searchResults.results) {
    // result.document has HotelId, HotelName, and Rating.
    // Trying to access result.document.Description would emit a TS error.
    console.log(result.document.HotelName);
  }
}

main();

OData フィルターを使用したクエリ

クエリパラメーターを filter 使用すると、 OData $filter 式の構文を使用してインデックスに対してクエリを実行できます。

const { SearchClient, AzureKeyCredential, odata } = require("@azure/search-documents");

const client = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>")
);

async function main() {
  const baseRateMax = 200;
  const ratingMin = 4;
  const searchResults = await client.search("WiFi", {
    filter: odata`Rooms/any(room: room/BaseRate lt ${baseRateMax}) and Rating ge ${ratingMin}`,
    orderBy: ["Rating desc"],
    select: ["HotelId", "HotelName", "Rating"],
  });
  for await (const result of searchResults.results) {
    // Each result will have "HotelId", "HotelName", and "Rating"
    // in addition to the standard search result property "score"
    console.log(result);
  }
}

main();

ファセットは、アプリケーションのユーザーが事前に構成されたディメンションに沿って検索を絞り込むのに役立ちます。ファセット構文には、ファセット値の並べ替えとバケット化を行うオプションが用意されています。

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>")
);

async function main() {
  const searchResults = await client.search("WiFi", {
    facets: ["Category,count:3,sort:count", "Rooms/BaseRate,interval:100"],
  });
  console.log(searchResults.facets);
  // Output will look like:
  // {
  //   'Rooms/BaseRate': [
  //     { count: 16, value: 0 },
  //     { count: 17, value: 100 },
  //     { count: 17, value: 200 }
  //   ],
  //   Category: [
  //     { count: 5, value: 'Budget' },
  //     { count: 5, value: 'Luxury' },
  //     { count: 5, value: 'Resort and Spa' }
  //   ]
  // }
}

main();

結果を取得するときに、 facets 各ファセットバケットに含まれる結果の数を示すプロパティを使用できます。これは、絞り込みを促進するために使用できます (たとえば、が 3 以上 4 未満であることをフィルター処理 Rating するフォローアップ検索を発行します)。

トラブルシューティング

ログ記録

ログの記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、環境変数 AZURE_LOG_LEVEL を info に設定します。または、@azure/logger で setLogLevel を呼び出して、実行時にログ記録を有効にすることもできます。

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

ログを有効にする方法の詳細については、@azure/logger パッケージに関するドキュメントを参照してください。

次のステップ

共同作成

このライブラリに投稿する場合、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

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

このプロジェクトでは、 Microsoft オープンソースの行動規範が採用されています。詳細については、「行動規範に関する FAQ」を参照するか、追加の質問やコメントに問い合わせてください opencode@microsoft.com 。

Microsoft Azure SDK for Javascript

インプレッション数

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

作業の開始

`@azure/search-documents` パッケージのインストール

現在サポートされている環境

前提条件

クライアントを認証する

National Cloud での認証

主要な概念

TypeScript/JavaScript 固有の概念

ドキュメント

ドキュメントフィールドのエンコード

例

インデックスを作成する

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

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

ドキュメントで検索を実行する

TypeScript を使用したクエリ

OData フィルターを使用したクエリ

ファセットを使用したクエリ

トラブルシューティング

ログ記録

次のステップ

共同作成

その他のリソース

その他のリソース

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

作業の開始

@azure/search-documents パッケージのインストール

現在サポートされている環境

前提条件

クライアントを認証する

National Cloud での認証

主要な概念

TypeScript/JavaScript 固有の概念

ドキュメント

改ページ位置の自動修正

ドキュメント フィールドのエンコード

例

インデックスを作成する

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

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

ドキュメントで検索を実行する

TypeScript を使用したクエリ

OData フィルターを使用したクエリ

ファセットを使用したクエリ

トラブルシューティング

ログ記録

次のステップ

共同作成

関連プロジェクト

その他のリソース

その他のリソース

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

`@azure/search-documents` パッケージのインストール

ドキュメントフィールドのエンコード