クイックスタート: REST API を使用して PowerShell で検索インデックスを作成する
この Azure AI 検索クイックスタートでは、PowerShell と Azure AI Search REST API を使用して検索インデックスの作成、読み込み、クエリを行う方法について学習します。 この記事では、PowerShell コマンドを対話的に実行する方法について説明します。 または、同じ操作を実行する PowerShell スクリプトをダウンロードして実行することもできます。
Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。
前提条件
このクイックスタートでは、次のサービスとツールが必要です。
- PowerShell 7.3 以降 (シーケンシャルおよび対話型の手順で Invoke-RestMethod を使用します)。
- Azure AI Search Service を作成するか、現在のサブスクリプションで既存のサービス を検索します。 このクイック スタート用には、無料のサービスを使用できます。
検索サービス キーと URL をコピーする
このクイック スタートでは、REST 呼び出しには、要求ごとにサービス URL とアクセス キーが含まれます。 両方を使用して検索サービスが作成されるため、Azure AI 検索をサブスクリプションに追加した場合は、これらの手順に従って必要な情報を取得します。
Azure portal にサインインします。 検索サービスの [概要] ページで、URL を取得します。 たとえば、エンドポイントは
https://mydemo.search.windows.netのようになります。[設定]>[キー] を選択し、サービスに対する完全な権限の管理キーを取得します。 管理キーをロールオーバーする必要がある場合、2 つの交換可能な管理キーがビジネス継続性のために提供されます。 オブジェクトの追加、変更、および削除の要求には、主キーまたはセカンダリ キーのどちらかを使用できます。
すべての要求では、サービスに送信されるすべての要求に API キーが必要です。 有効なキーがあれば、要求を送信するアプリケーションとそれを処理するサービスの間で、要求ごとに信頼を確立できます。
Azure AI Search に接続する
PowerShell では、
$headersオブジェクトを作成して、コンテンツ タイプと API キーを格納します。 管理 API キー (YOUR-ADMIN-API-KEY) を、検索サービスに対して有効なキーに置き換えます。 このヘッダーはセッション中に 1 回設定するだけで済みますが、すべての要求に追加します。$headers = @{ 'api-key' = '<YOUR-ADMIN-API-KEY>' 'Content-Type' = 'application/json' 'Accept' = 'application/json' }サービスのインデックス コレクションを指定する
$urlオブジェクトを作成します。 サービス名 (YOUR-SEARCH-SERVICE-NAME) を有効な検索サービスに置き換えます。$url = "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2023-11-01&`$select=name"Invoke-RestMethodを実行して、サービスに GET 要求を送信し、接続を確認します。ConvertTo-Jsonを追加して、サービスから返信された応答を表示できるようにします。Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Jsonサービスが空で、インデックスが含まれていない場合、結果は次の例のようになります。 それ以外の場合は、インデックス定義の JSON 表現が表示されます。
{ "@odata.context": "https://mydemo.search.windows.net/$metadata#indexes", "value": [ ] }
インデックスを作成する
ポータルを使用している場合を除き、データを読み込むには、サービスにインデックスが存在する必要があります。 この手順では、インデックスを定義して、それをサービスにプッシュします。 この手順ではインデックスの作成 REST API を使用します。
インデックスの必要な要素には、名前とフィールド コレクションが含まれます。 フィールド コレクションはドキュメントの構造を定義します。 各フィールドには、名前、型、およびその使用方法を決定する属性 (たとえば、フルテキスト検索可能、フィルター可能、または検索結果で取得可能) があります。 インデックス内には、Edm.String 型のフィールドのいずれかをドキュメント ID のキーとして指定する必要があります。
このインデックスには hotels-quickstart という名前が付けられ、次のコードに示されるフィールド定義があります。 これは、他のチュートリアル記事で使用されている、より大きい Hotels インデックスのサブセットです。 このクイックスタートでは、簡潔にするためにフィールド定義がトリミングされています。
この例を PowerShell に貼り付けて、インデックス スキーマを含む
$bodyオブジェクトを作成します。$body = @" { "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} ] } ] } "@サービスのインデックス コレクションと
hotels-quickstartインデックスへの URI を設定します。$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart?api-version=2023-11-01"$url、$headers、$bodyを指定してコマンドを実行し、サービスにインデックスを作成します。Invoke-RestMethod -Uri $url -Headers $headers -Method Put -Body $body | ConvertTo-Json結果はこの例のようになるはずです。簡潔にするために最初の 2 つのフィールドのみが表示されています。
{ "@odata.context": "https://mydemo.search.windows.net/$metadata#indexes/$entity", "@odata.etag": "\"0x8D6EDE28CFEABDA\"", "name": "hotels-quickstart", "defaultScoringProfile": null, "fields": [ { "name": "HotelId", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "sortable": true, "facetable": true, "key": true, "indexAnalyzer": null, "searchAnalyzer": null, "analyzer": null, "synonymMaps": "" }, { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "sortable": true, "facetable": false, "key": false, "indexAnalyzer": null, "searchAnalyzer": null, "analyzer": null, "synonymMaps": "" }, . . . ] }
ヒント
検証のため、ポータルで [インデックス] 一覧を確認することもできます。
ドキュメントを読み込む
ドキュメントをプッシュするには、インデックスの URL エンドポイントに対する HTTP POST 要求を使用します。 このタスクの REST API は、ドキュメントの追加、更新、または削除です。
この例を PowerShell に貼り付けて、アップロードするドキュメントを含む
$bodyオブジェクトを作成します。この要求には、2 つの完全なレコードと 1 つの部分的なレコードが含まれています。 部分的なレコードは、不完全なドキュメントをアップロードすることを示します。
@search.actionパラメーターは、インデックス作成を行う方法を指定します。 有効な値には、upload、merge、mergeOrUpload、およびdeleteがあります。mergeOrUploadの動作では、hotelId = 3の新しいドキュメントが作成されるか、内容が既に存在している場合はそれが更新されます。$body = @" { "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" } } ] } "@hotels-quickstartドキュメント コレクションへのエンドポイントを設定し、インデックス操作 (indexes/hotels-quickstart/docs/index) を含めます。$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2023-11-01"$url、$headers、$bodyを指定してコマンドを実行し、ドキュメントをhotels-quickstartインデックスに読み込みます。Invoke-RestMethod -Uri $url -Headers $headers -Method Post -Body $body | ConvertTo-Json結果は次の例のようになります。 状態コード 201 が表示されます。
{ "@odata.context": "https://mydemo.search.windows.net/indexes(\u0027hotels-quickstart\u0027)/$metadata#Collection(Microsoft.Azure.Search.V2019_05_06.IndexResult)", "value": [ { "key": "1", "status": true, "errorMessage": null, "statusCode": 201 }, { "key": "2", "status": true, "errorMessage": null, "statusCode": 201 }, { "key": "3", "status": true, "errorMessage": null, "statusCode": 201 }, { "key": "4", "status": true, "errorMessage": null, "statusCode": 201 } ] }
インデックスを検索する
この手順では、Search Documents API を使用してインデックスのクエリを実行する方法を示します。
$urls の検索では必ず単一引用符を使用してください。 クエリ文字列に $ 文字が含まれているときに、文字列全体を単一引用符で囲むと、それらをエスケープする必要がなくなります。
hotels-quickstartドキュメント コレクションへのエンドポイントを設定し、searchパラメーターを追加してクエリ文字列を渡します。この文字列では、空の検索が実行され (
search=*)、任意のドキュメントのランクなしの一覧 (search score = 1.0) が返されます。 既定では、Azure AI Search によって一度に 50 件の結果が返されます。 構造化されているので、このクエリではドキュメント全体の構造と値が返されます。$count=trueを追加して、結果に含まれるすべてのドキュメントの数を取得します。$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=*&$count=true'コマンドを実行して
$urlをサービスに送信します。Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json結果は次の出力のようになります。
{ "@odata.context": "https://mydemo.search.windows.net/indexes(\u0027hotels-quickstart\u0027)/$metadata#docs(*)", "@odata.count": 4, "value": [ { "@search.score": 0.1547872, "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.6, "Address": "@{StreetAddress=140 University Town Center Dr; City=Sarasota; StateProvince=FL; PostalCode=34243; Country=USA}" }, { "@search.score": 0.009068266, "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\u0027s restaurant services.", "Category": "Resort and Spa", "Tags": "air conditioning bar continental breakfast", "ParkingIncluded": true, "LastRenovationDate": "2015-09-20T00:00:00Z", "Rating": 4.8, "Address": "@{StreetAddress=3393 Peachtree Rd; City=Atlanta; StateProvince=GA; PostalCode=30326; Country=USA}" }, . . . ] }
構文について大まかに把握するため、その他のクエリ例をいくつか試してください。 文字列の検索、逐語的な $filter クエリの実行、結果セットの制限、特定のフィールドへの検索範囲の設定などを行うことができます。
# Query example 1
# Search the entire index for the terms 'restaurant' and 'wifi'
# Return only the HotelName, Description, and Tags fields
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=restaurant wifi&$count=true&$select=HotelName,Description,Tags'
# Query example 2
# Apply a filter to the index to find hotels rated 4 or higher
# Returns the HotelName and Rating. Two documents match.
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=*&$filter=Rating gt 4&$select=HotelName,Rating'
# Query example 3
# Take the top two results, and show only HotelName and Category in the results
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=boutique&$top=2&$select=HotelName,Category'
# Query example 4
# Sort by a specific field (Address/City) in ascending order
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=pool&$orderby=Address/City asc&$select=HotelName, Address/City, Tags, Rating'
リソースをクリーンアップする
独自のサブスクリプションを使用している場合は、プロジェクトの最後に、作成したリソースがまだ必要かどうかを確認してください。 リソースを実行したままにすると、お金がかかる場合があります。 リソースを個別に削除するか、リソース グループを削除してリソースのセット全体を削除することができます。
ポータルの左端のペインにある [すべてのリソース] または [リソース グループ] リンクを使って、リソースを検索および管理できます。
無料サービスを使っている場合は、3 つのインデックス、インデクサー、およびデータソースに制限されることに注意してください。 ポータルで個別の項目を削除して、制限を超えないようにすることができます。
次のステップ
このクイックスタートでは、PowerShell を使用して、Azure AI Search でコンテンツを作成してアクセスするための基本的なワークフローをステップ実行しました。 この概念を考慮に入れて、Azure データ ソースからインデックスを付けるなど、より高度なシナリオに進むことをお勧めします。