クイックスタート: REST を使用したテキスト検索
Azure AI 検索の REST API を使用すると、プレビュー機能を含むすべての機能にプログラムでアクセスし、機能のしくみを簡単に学習できます。 このクイックスタートでは、Azure AI 検索で Search REST API を使用して検索インデックスの作成、読み込み、クエリを行う方法について説明します。
Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。
前提条件
- REST クライアントを使用する Visual Studio Code。
- Azure AI 検索. 現在のサブスクリプションで、既存の Azure AI 検索サービスを見つけるか、または作成します。 このクイック スタート用には、無料のサービスを使用できます。
ファイルのダウンロード
GitHub から REST サンプルをダウンロードして、このクイックスタートの要求を送信します。 詳細については、「GitHub からファイルをダウンロードする」を参照してください。
ローカル システムで新しいファイルを開始し、この記事の手順を使用して手動で要求を作成することもできます。
検索サービス キーと URL をコピーする
REST 呼び出しでは、すべての要求で検索サービス エンドポイントと API キーが必要です。 これらの値は Azure portal から取得できます。
Azure portal にサインインします。 次に、検索サービスの [概要] ページに移動し、URL をコピーします。 たとえば、エンドポイントは
https://mydemo.search.windows.netのようになります。[設定]>[キー] を選び、管理者キーをコピーします。 管理者キーは、オブジェクトの追加、変更、削除で使用します。 2 つの交換可能な管理者キーがあります。 どちらかをコピーします。
Visual Studio Code を設定する
Visual Studio Code 用の REST クライアントに慣れていない場合、このクイックスタートにはセットアップが含まれているため、タスクを完了することができます。
Visual Studio Code を起動し、[拡張機能] タイルを選択します。
REST クライアントを検索し、[インストール] を選択します。
![REST クライアントの [インストール] ボタンを示すスクリーンショット。](media/search-get-started-rest/rest-client-install.png)
ファイル拡張子が
.restまたは.httpの名前のファイルを開くか、または新規に作成します。次の例に貼り付けます。 ベース URL と API キーを、前にコピーした値に置き換えます。
@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE @apiKey = PUT-YOUR-SEARCH-SERVICE-API-KEY-HERE ### List existing indexes by name GET {{baseUrl}}/indexes?api-version=2023-11-01&$select=name HTTP/1.1 Content-Type: application/json api-key: {{apiKey}}[要求の送信] をクリックします。 隣接するウィンドウに応答が表示されます。 既存のインデックスがある場合、そのインデックスが一覧表示されます。 そうしないと、一覧は空です。 HTTP コードが
200 OKの場合は、次の手順に進むことができます。
重要なポイント:
- パラメーターは
@プレフィックスを使って指定されます。 ###によって REST 呼び出しが指定されます。 次の行には要求が含まれています。これにはHTTP/1.1が含まれていなければなりません。- 要求の上に
Send requestが表示されます。
- パラメーターは
インデックスを作成する
.rest ファイルに 2 番目の要求を追加します。 [インデックスの作成 (REST)] により検索インデックスが作成され、検索サービスに物理データ構造が設定されます。
次の例に貼り付けて、検索サービスに
hotels-quickstartインデックスを作成します。### Create a new index POST {{baseUrl}}/indexes?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "name": "hotels-quickstart", "fields": [ {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true}, {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false}, {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"}, {"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true}, {"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true}, {"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true}, {"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true}, {"name": "Address", "type": "Edm.ComplexType", "fields": [ {"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true}, {"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true} ] } ] }[要求の送信] をクリックします。
HTTP/1.1 201 Created応答が返され、その応答本文にはインデックス スキーマの JSON 表現が含まれているはずです。Header name must be a valid HTTP token ["{"]エラーが発生する場合は、要求のapi-keyと本文の間に空の行があることを確認します。 HTTP 504 が表示された場合は、URL で HTTPS の指定を確認してください。 HTTP 400 または 404 を確認するには、要求の本文をチェックして、コピーまたは貼り付けのエラーがないことを確認します。 HTTP 403 は、通常、API キーに問題があることを示します。 無効なキーか、API キーの指定方法に関する構文の問題です。これで、ファイルに複数の要求が含まれるようになりました。
###により新しい要求が開始され、各要求は個別に実行されることを思い出してください。
インデックスの定義について
インデックス スキーマ内では、フィールド コレクションにより、ドキュメントの構造を定義します。 アップロードする各ドキュメントには、これらのフィールドが必要です。 各フィールドには、Entity Data Model (EDM) データ型を割り当てる必要があります。 文字列フィールドは、フルテキスト検索に使用されます。 数値データを検索可能にする場合は、データ型が Edm.String であることを確認してください。 Edm.Int32 などの他のデータ型は、フィルター可能、並べ替え可能、ファセット可能、取得可能ですが、フルテキスト検索は可能ではありません。
フィールドの属性によって、使用できるアクションが決まります。 REST API では、多くのアクションが既定で使用できます。 たとえば、すべての文字列は既定で検索可能、取得可能です。 REST API では、動作をオフにする必要がある場合にのみ属性を指定できます。
{
"name": "hotels-quickstart",
"fields": [
{"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true},
{"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false},
{"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"},
{"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true},
{"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true},
{"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true},
{"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true},
{"name": "Address", "type": "Edm.ComplexType",
"fields": [
{"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true},
{"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}
]
}
]
}
ドキュメントを読み込む
インデックスの作成と読み込みは別の手順です。 Azure AI 検索では、インデックスには検索可能なすべてのデータと、検索サービスで実行されるクエリが含まれます。 REST 呼び出しでは、データは JSON ドキュメントとして提供されます。 このタスクでは Documents- Index REST API を使用します。
URI を拡張して、docs コレクションと index 操作を含めます。
次の例に貼り付けて JSON ドキュメントを検索インデックスにアップロードします。
### Upload documents POST {{baseUrl}}/indexes/hotels-quickstart/docs/index?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "value": [ { "@search.action": "upload", "HotelId": "1", "HotelName": "Secret Point Motel", "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.", "Category": "Boutique", "Tags": [ "pool", "air conditioning", "concierge" ], "ParkingIncluded": false, "LastRenovationDate": "1970-01-18T00:00:00Z", "Rating": 3.60, "Address": { "StreetAddress": "677 5th Ave", "City": "New York", "StateProvince": "NY", "PostalCode": "10022", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "2", "HotelName": "Twin Dome Motel", "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.", "Category": "Boutique", "Tags": [ "pool", "free wifi", "concierge" ], "ParkingIncluded": false, "LastRenovationDate": "1979-02-18T00:00:00Z", "Rating": 3.60, "Address": { "StreetAddress": "140 University Town Center Dr", "City": "Sarasota", "StateProvince": "FL", "PostalCode": "34243", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "3", "HotelName": "Triple Landscape Hotel", "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.", "Category": "Resort and Spa", "Tags": [ "air conditioning", "bar", "continental breakfast" ], "ParkingIncluded": true, "LastRenovationDate": "2015-09-20T00:00:00Z", "Rating": 4.80, "Address": { "StreetAddress": "3393 Peachtree Rd", "City": "Atlanta", "StateProvince": "GA", "PostalCode": "30326", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "4", "HotelName": "Sublime Cliff Hotel", "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.", "Category": "Boutique", "Tags": [ "concierge", "view", "24-hour front desk service" ], "ParkingIncluded": true, "LastRenovationDate": "1960-02-06T00:00:00Z", "Rating": 4.60, "Address": { "StreetAddress": "7400 San Pedro Ave", "City": "San Antonio", "StateProvince": "TX", "PostalCode": "78216", "Country": "USA" } } ] }[要求の送信] をクリックします。 数秒で、隣接するウィンドウに HTTP 201 応答が表示されます。
207 が表示された場合は、少なくとも 1 つのドキュメントのアップロードが失敗しています。 404 が表示された場合は、要求のヘッダーまたは本文に構文エラーがあります。
/docs/indexを含むようにエンドポイントを変更したことを確認します。
クエリを実行する
これでドキュメントが読み込まれたので、Documents - Search Post (REST) を使って、それらに対してクエリを発行できます。
URI を拡張して、/docs/search 演算子を使って指定されたクエリ式を含めます。
次の例を貼り付けて、検索インデックスのクエリを実行します。 次に、[要求の送信] を選びます。 テキスト検索要求には、常に
searchパラメータが含まれます。 この例では、テキスト検索を特定のフィールドに制限する省略可能なsearchFieldsパラメータが含まれています。### Run a query POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "search": "lake view", "select": "HotelId, HotelName, Tags, Description", "searchFields": "Description, Tags", "count": true }隣接するウィンドウで応答を確認します。 インデックスで見つかった一致の数、関連性を示す検索スコア、
selectステートメントに一覧表示されている各フィールドの値を示すカウントが返されるはずです。{ "@odata.context": "https://my-demo.search.windows.net/indexes('hotels-quickstart')/$metadata#docs(*)", "@odata.count": 1, "value": [ { "@search.score": 0.6189728, "HotelId": "4", "HotelName": "Sublime Cliff Hotel", "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.", "Tags": [ "concierge", "view", "24-hour front desk service" ] } ] }
インデックス プロパティの取得
統計情報の取得を使って、ドキュメント数とインデックス サイズを照会することもできます。
次の例を貼り付けて、検索インデックスのクエリを実行します。 次に、[要求の送信] を選びます。
### Get index statistics GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}}応答を確認します。 この操作は、インデックス ストレージに関する詳細を取得する簡単な方法です。
{ "@odata.context": "https://my-demo.search.windows.net/$metadata#Microsoft.Azure.Search.V2023_11_01.IndexStatistics", "documentCount": 4, "storageSize": 34707, "vectorIndexSize": 0 }
リソースをクリーンアップする
独自のサブスクリプションを使用している場合は、プロジェクトの最後に、作成したリソースがまだ必要かどうかを確認してください。 リソースを実行したままにすると、お金がかかる場合があります。 リソースを個別に削除するか、リソース グループを削除してリソースのセット全体を削除することができます。
ポータルの左端のペインにある [すべてのリソース] または [リソース グループ] リンクを使って、リソースを検索および管理できます。
次の DELETE コマンドを試すこともできます。
### Delete an index
DELETE {{baseUrl}}/indexes/hotels-quickstart?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
次のステップ
REST クライアントについて学習し、Azure AI 検索に対する REST 呼び出しを行いました。ベクトルのサポートを例示する別のクイック スタートを試してみてください。