クイックスタート: REST を使用したキーワード検索

[アーティクル]
10/31/2024

Azure AI 検索の REST API を使用すると、プレビュー機能を含むすべての機能にプログラムでアクセスし、機能のしくみを簡単に学習できます。このクイックスタートでは、Azure AI 検索で Search REST API を使用して検索インデックスの作成、読み込み、クエリを行う方法について説明します。

Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。

前提条件

REST クライアントを使用する Visual Studio Code。
Azure AI 検索. 現在のサブスクリプションで、既存の Azure AI 検索サービスを見つけるか、または作成します。このクイックスタート用には、無料のサービスを使用できます。

ファイルのダウンロード

GitHub から REST サンプルをダウンロードして、このクイックスタートの要求を送信します。手順については、「GitHub からファイルをダウンロードする」を参照してください。

ローカルシステムで新しいファイルを開始し、この記事の手順を使用して手動で要求を作成することもできます。

検索サービスエンドポイントを取得する

検索サービスエンドポイントは、Azure portal で確認できます。

Azure portal にサインインし、ご利用の検索サービスを探します。
[概要] ホームページで、URL を見つけます。たとえば、エンドポイントは https://mydemo.search.windows.net のようになります。

このエンドポイントは、後の手順で .rest または .http ファイルに貼り付けます。

アクセスを構成する

検索エンドポイントへの要求は、認証および承認する必要があります。このタスクには API キーまたはロールを使用できます。キーの方が簡単に使い始めることができますが、安全性が高いのはロールの方です。

ロールベースの接続の場合に使用する次の手順では、クライアントアプリの ID ではなく、自分の ID で Azure AI Search に接続することになります。

オプション 1: キーを使用する

[設定]>[キー] を選び、管理者キーをコピーします。管理者キーは、オブジェクトの追加、変更、削除で使用します。 2 つの交換可能な管理者キーがあります。どちらかをコピーします。詳細については、キー認証を使用して Azure AI Search に接続に関するページを参照してください。

このキーは、後の手順で .rest または .http ファイルに貼り付けます。

オプション 2: ロールを使用する

ご利用の検索サービスがロールベースのアクセス用に構成されていることを確認します。開発者アクセス用のロール割り当てが構成済みである必要があります。このロールの割り当てによって、検索インデックスの作成、読み込み、クエリを行うためのアクセス許可が付与される必要があります。

このセクションでは、Azure CLI、Azure PowerShell、または Azure portal を使用して、個人 ID トークンを取得します。

Azure CLI にサインインします。
```
az login
```

個人の ID トークンを取得します。

az account get-access-token --scope https://search.azure.com/.default

この個人 ID トークンは、後の手順で .rest または .http ファイルに貼り付けます。

Note

このセクションでは、Azure AI Search への接続をユーザーに代わって行うローカルクライアントを使用することを前提とします。他には、クライアントアプリのトークンを取得するという方法があります。この場合は、アプリケーションが Microsoft Entra ID に登録されていることが前提です。

Visual Studio Code を設定する

Visual Studio Code 用の REST クライアントに慣れていない場合、このクイックスタートにはセットアップが含まれているため、タスクを完了することができます。

Visual Studio Code を起動し、[拡張機能] タイルを選択します。
REST クライアントを検索し、[インストール] を選択します。
ファイル拡張子が .rest または .http の名前のファイルを開くか、または新規に作成します。

API キーを使用する場合は、次の例を貼り付けます。 @baseUrl および @apiKey プレースホルダーを、先程コピーした値に置き換えます。

@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=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}

または、ロールを使用している場合は、この例を貼り付けます。 @baseUrl および @token プレースホルダーを、先程コピーした値に置き換えます。

@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE

 ### List existing indexes by name
 GET  {{baseUrl}}/indexes?api-version=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{token}}

[要求の送信] をクリックします。隣接するウィンドウに応答が表示されます。既存のインデックスがある場合、そのインデックスが一覧表示されます。そうしないと、一覧は空です。 HTTP コードが 200 OK の場合は、次の手順に進むことができます。

重要なポイント:
- パラメーターは @ プレフィックスを使って指定されます。
- ### によって REST 呼び出しが指定されます。次の行には要求が含まれています。これには HTTP/1.1 が含まれていなければなりません。
- 要求の上に Send request が表示されます。

インデックスを作成する

.rest ファイルに 2 番目の要求を追加します。 [インデックスの作成 (REST)] により検索インデックスが作成され、検索サービスに物理データ構造が設定されます。

次の例に貼り付けて、検索サービスに hotels-quickstart インデックスを作成します。

### Create a new index
POST {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

    {
        "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=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

    {
        "value": [
        {
        "@search.action": "upload",
        "HotelId": "1",
        "HotelName": "Stay-Kay City Hotel",
        "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": "Old Century Hotel",
        "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": "Gastronomic 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 Palace Hotel",
        "Description": "Sublime Palace 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 Palace 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=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  {
      "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 Palace Hotel",
      "Description": "Sublime Palace 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 Palace 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=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

応答を確認します。この操作は、インデックスストレージに関する詳細を取得する簡単な方法です。

{
  "@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=2024-07-01 HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

次のステップ

REST クライアントについて学習し、Azure AI 検索に対する REST 呼び出しを行いました。ベクトルのサポートを例示する別のクイックスタートを試してみてください。

クイックスタート: REST を使用したベクトル検索

次の方法で共有

クイックスタート: REST を使用したキーワード検索

前提条件

ファイルのダウンロード

検索サービスエンドポイントを取得する

アクセスを構成する

オプション 1: キーを使用する

オプション 2: ロールを使用する

Visual Studio Code を設定する

インデックスを作成する

インデックスの定義について

ドキュメントを読み込む

クエリを実行する

インデックスプロパティの取得

リソースをクリーンアップする

次のステップ

フィードバック

その他のリソース

次の方法で共有

クイック スタート: REST を使用したキーワード検索

前提条件

ファイルのダウンロード

検索サービス エンドポイントを取得する

アクセスを構成する

オプション 1: キーを使用する

オプション 2: ロールを使用する

Visual Studio Code を設定する

インデックスを作成する

インデックスの定義について

ドキュメントを読み込む

クエリを実行する

インデックス プロパティの取得

リソースをクリーンアップする

次のステップ

フィードバック

その他のリソース

クイックスタート: REST を使用したキーワード検索

検索サービスエンドポイントを取得する

インデックスプロパティの取得