Share via


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

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

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

前提条件

ファイルのダウンロード

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

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

検索サービス キーと URL をコピーする

REST 呼び出しでは、すべての要求で検索サービス エンドポイントと API キーが必要です。 これらの値は Azure portal から取得できます。

  1. Azure portal にサインインします。 次に、検索サービスの [概要] ページに移動し、URL をコピーします。 たとえば、エンドポイントは https://mydemo.search.windows.net のようになります。

  2. [設定]>[キー] を選び、管理者キーをコピーします。 管理者キーは、オブジェクトの追加、変更、削除で使用します。 2 つの交換可能な管理者キーがあります。 どちらかをコピーします。

    Azure portal の URL と API キーを示すスクリーンショット。

Visual Studio Code を設定する

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

  1. Visual Studio Code を起動し、[拡張機能] タイルを選択します。

  2. REST クライアントを検索し、[インストール] を選択します。

    REST クライアントの [インストール] ボタンを示すスクリーンショット。

  3. ファイル拡張子が .rest または .http の名前のファイルを開くか、または新規に作成します。

  4. 次の例に貼り付けます。 ベース 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}}
    
  5. [要求の送信] をクリックします。 隣接するウィンドウに応答が表示されます。 既存のインデックスがある場合、そのインデックスが一覧表示されます。 そうしないと、一覧は空です。 HTTP コードが 200 OK の場合は、次の手順に進むことができます。

    検索サービス要求用に構成された REST クライアントを示すスクリーンショット。

    重要なポイント:

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

インデックスを作成する

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

  1. 次の例に貼り付けて、検索サービスに 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}
                    ]
                }
            ]
        }
    
  2. [要求の送信] をクリックします。 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 キーの指定方法に関する構文の問題です。

    これで、ファイルに複数の要求が含まれるようになりました。 ### により新しい要求が開始され、各要求は個別に実行されることを思い出してください。

    複数の要求がある REST クライアントを示すスクリーンショット。

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

インデックス スキーマ内では、フィールド コレクションにより、ドキュメントの構造を定義します。 アップロードする各ドキュメントには、これらのフィールドが必要です。 各フィールドには、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 操作を含めます。

  1. 次の例に貼り付けて 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"
                }
            }
          ]
        }
    
  2. [要求の送信] をクリックします。 数秒で、隣接するウィンドウに HTTP 201 応答が表示されます。

    207 が表示された場合は、少なくとも 1 つのドキュメントのアップロードが失敗しています。 404 が表示された場合は、要求のヘッダーまたは本文に構文エラーがあります。 /docs/index を含むようにエンドポイントを変更したことを確認します。

クエリを実行する

これでドキュメントが読み込まれたので、Documents - Search Post (REST) を使って、それらに対してクエリを発行できます。

URI を拡張して、/docs/search 演算子を使って指定されたクエリ式を含めます。

  1. 次の例を貼り付けて、検索インデックスのクエリを実行します。 次に、[要求の送信] を選びます。 テキスト検索要求には、常に 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
        }
    
  2. 隣接するウィンドウで応答を確認します。 インデックスで見つかった一致の数、関連性を示す検索スコア、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"
          ]
        }
      ]
    }
    

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

統計情報の取得を使って、ドキュメント数とインデックス サイズを照会することもできます。

  1. 次の例を貼り付けて、検索インデックスのクエリを実行します。 次に、[要求の送信] を選びます。

    ### Get index statistics
    GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2023-11-01  HTTP/1.1
      Content-Type: application/json
      api-key: {{apiKey}}
    
  2. 応答を確認します。 この操作は、インデックス ストレージに関する詳細を取得する簡単な方法です。

    {
      "@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 呼び出しを行いました。ベクトルのサポートを例示する別のクイック スタートを試してみてください。