Fiddler または Postman を使用して Azure Search REST API を探索するExplore Azure Search REST APIs using Fiddler or Postman

Azure Search REST API を探索する最も簡単な方法の 1 つは、Fiddler または Postman を使用して HTTP 要求を作成し、応答を検査することです。One of the easiest ways to explore the Azure Search REST API is using Fiddler or Postman to formulate HTTP requests and inspect the responses. 適切なツールと以下の手順を利用すると、コードを記述する前に要求を送信して応答を確認できます。With the right tools and these instructions, you can send requests and view responses before writing any code.

  • Web API テスト プール ツールをダウンロードするDownload a web api test tool
  • 検索サービスの API キーとエンドポイントを取得するGet the api-key and endpoint for your search service
  • 要求ヘッダーを構成するConfigure request headers
  • インデックスを作成するCreate an index
  • インデックスを読み込むLoad an index
  • インデックスを検索するSearch an index

Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成し、Azure Search にサインアップしてください。If you don't have an Azure subscription, create a free account before you begin and then sign up for Azure Search.

ツールのダウンロードとインストールDownload and install tools

Web 開発では次のツールが幅広く使用されていますが、別の使い慣れたツールでも、多くの場合はこの記事の手順が適用されます。The following tools are widely used in web development, but if you are familiar with another tool, the instructions in this article should still apply.

API キーとエンドポイントを取得するGet the api-key and endpoint

REST 呼び出しには、要求ごとにサービス URL とアクセス キーが必要です。REST calls require the service URL and an access key on every request. 両方を使用して検索サービスが作成されるので、Azure Search をサブスクリプションに追加した場合は、次の手順に従って必要な情報を入手してください。A search service is created with both, so if you added Azure Search to your subscription, follow these steps to get the necessary information:

  1. Azure Portal でダッシュボードから検索サービス ページを開くか、サービス一覧からご利用のサービスを探しますIn the Azure portal, open the search service page from the dashboard or find your service in the service list.
  2. [概要] > [要点] > [URL] でエンドポイントを取得します。Get the endpoint at Overview > Essentials > Url. たとえば、エンドポイントは https://my-service-name.search.windows.net のようになります。An example endpoint might look like https://my-service-name.search.windows.net.
  3. [設定] > [キー] で API キーを取得します。Get the api-key in Settings > Keys. キーをロール オーバーする場合に備えて冗長性のために 2 つの管理者キーがあります。There are two admin keys for redundancy in case you want to roll over keys. 管理者キーは、サービスに対する書き込みアクセス許可を付与します。これはインデックスの作成と読み込みに必要です。Admin keys grant the write permissions on your service, necessary for creating and loading indexes. 書き込み操作には、プライマリ キーまたはセカンダリ キーのどちらでも使用できます。You can use either the primary or secondary key for write operations.

要求ヘッダーを構成するConfigure request headers

各ツールには、セッションの要求ヘッダー情報が保持されます。つまり、URL エンドポイント、API バージョン、API キー、およびコンテンツタイプの入力は 1 度だけで済みます。Each tool persists request header information for the session, which means you only have to enter the URL endpoint, api-version, api-key, and content-type once.

完全な URL は次の例のようになります。my-app プレースホルダー名は、実際の有効な値で置き換える必要があります。https://my-app.search.windows.net/indexes/hotels?api-version=2017-11-11The full URL should look similar to the following example, only yours should have a valid replacement for the my-app placeholder name: https://my-app.search.windows.net/indexes/hotels?api-version=2017-11-11

サービス URL の構成には、次の要素が含まれます。Service URL composition includes the following elements:

  • HTTPS プレフィックス。HTTPS prefix.
  • サービス URL。ポータルから取得します。Service URL, obtained from the portal.
  • リソース。サービスでオブジェクトを作成する操作です。Resource, an operation that creates an object on your service. この手順では、hotels というインデックスです。In this step, it is an index named hotels.
  • API バージョン。現在のバージョンでは、"?api-version=2017-11-11" のように指定された必須の小文字の文字列。api-version, a required lowercase string specified as "?api-version=2017-11-11" for the current version. API バージョンは定期的に更新されます。API versions are updated regularly. 各要求に API バージョンを含めるので、使用するバージョンが完全に制御されます。Including the api-version on each request gives you full control over which one is used.

要求ヘッダーの構成には、前のセクションで説明したコンテンツ タイプと API キーという 2 つの要素が含まれます。Request header composition includes two elements, content type and the api-key described in the previous section:

     content-type: application/json
     api-key: <placeholder>

FiddlerFiddler

次のスクリーン ショットのように要求を作成します。Formulate a request that looks like the following screen shot. 動詞として PUT を選択します。Choose PUT as the verb. User-Agent=Fiddler が自動的に追加されます。Fiddler adds User-Agent=Fiddler. その下の新しい行に 2 つの追加の要求ヘッダーを貼り付けることができます。You can paste the two additional request headers on new lines below it. サービスの管理者アクセス キーを使用して、サービスのコンテンツ タイプと API キーを含めます。Include the content type and api-key for your service, using the admin access key for your service.

Fiddler の要求ヘッダー

ヒント

Web トラフィックを無効にして、実行しているタスクに関係がない余計な HTTP アクティビティを非表示にすることができます。You can turn off web traffic to hide extraneous HTTP activity unrelated to the tasks you are performing. Fiddler で [File](ファイル) メニューに移動し、[Capture Traffic](トラフィックのキャプチャ) をオフにします。In Fiddler, go to the File menu and turn off Capture Traffic.

postmanPostman

次のスクリーン ショットのように要求を作成します。Formulate a request that looks like the following screen shot. 動詞として PUT を選択します。Choose PUT as the verb.

Postman の要求ヘッダー

インデックスの作成Create the index

要求の本文には、インデックス定義が含まれています。The body of the request contains the index definition. 要求本文を追加すると、インデックスを生成する要求が完成します。Adding the request body completes the request that produces your index.

要求で最も重要なコンポーネントは、インデックス名を除くと、フィールド コレクションです。Besides the index name, the most important component in the request is the fields collection. フィールド コレクションは、インデックス スキーマを定義します。The fields collection defines the index schema. 各フィールドでその型を指定します。On each field, specify its type. 文字列フィールドは全文検索に使用されるので、コンテンツを検索可能にする必要がある場合は、数値データを文字列としてキャストすることができます。String fields are used in full text search, so you might want to cast numeric data as strings if you need that content to be searchable.

フィールドの属性によって、使用できるアクションが決まります。Attributes on the field determine allowed action. REST API は、既定で多くのアクションを使用できます。The REST APIs allow many actions by default. たとえば、すべての文字列は既定で検索可能、取得可能、フィルター可能、およびファセット可能です。For example, all strings are searchable, retrievable, filterable, and facetable by default. 動作を無効にする必要がある場合は、属性を設定するだけで済むことがよくあります。Often, you only have to set attributes when you need to turn a behavior off. 属性の詳細詳細については、インデックスの作成 (REST) に関するページを参照してください。For more information about attributes, see Create Index (REST).

      {
     "name": "hotels",  
     "fields": [
       {"name": "hotelId", "type": "Edm.String", "key":true, "searchable": false},
       {"name": "baseRate", "type": "Edm.Double"},
       {"name": "description", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false},
       {"name": "hotelName", "type": "Edm.String"},
       {"name": "category", "type": "Edm.String"},
       {"name": "tags", "type": "Collection(Edm.String)"},
       {"name": "parkingIncluded", "type": "Edm.Boolean"},
       {"name": "smokingAllowed", "type": "Edm.Boolean"},
       {"name": "lastRenovationDate", "type": "Edm.DateTimeOffset"},
       {"name": "rating", "type": "Edm.Int32"},
       {"name": "location", "type": "Edm.GeographyPoint"}
      ]
     }

この要求を送信すると、インデックスが正常に作成されたことを示す HTTP 201 応答が返されます。When you submit this request, you should get an HTTP 201 response, indicating the index was created successfully. ポータルでこのアクションを確認することもできますが、ポータル ページには更新間隔があるので、最新情報が表示されるまでに 1 ~ 2 分かかる可能性があります。You can verify this action in the portal, but note that the portal page has refresh intervals so it could take a minute or two to catch up.

HTTP 504 が表示された場合は、URL で HTTPS の指定を確認してください。If you get HTTP 504, verify the URL specifies HTTPS. HTTP 400 または 404 を確認するには、要求の本文をチェックして、コピーまたは貼り付けのエラーがないことを確認します。If you see HTTP 400 or 404, check the request body to verify there were no copy-paste errors. HTTP 403 は、API キーに問題があることを示しています (キーが無効か、または API キーの指定方法に構文エラーがあります)。An HTTP 403 typically indicates a problem with the api-key (either an invalid key or a syntax problem with how the api-key is specified).

FiddlerFiddler

次のスクリーン ショットのようにインデックス定義を要求本文にコピーし、右上の [Execute](実行) をクリックして完成した要求を送信します。Copy the index definition to the request body, similar to the following screen shot, and then click Execute on the top right to send the completed request.

Fiddler の要求本文

postmanPostman

次のスクリーン ショットのようにインデックス定義を要求本文にコピーし、右上の [Send](送信) をクリックして完成した要求を送信します。Copy the index definition to the request body, similar to the following screen shot, and then click Send on the top right to send the completed request.

Postman の要求本文

ドキュメントを読み込むLoad documents

インデックスの作成とインデックスの設定は別の手順です。Creating the index and populating the index are separate steps. Azure Search では、インデックスにはすべての検索可能なデータが含まれており、それを JSON ドキュメントとして提供できます。In Azure Search, the index contains all searchable data, which you can provide as JSON documents. この操作の API の詳細については、ドキュメントの追加、更新、または削除 (REST) に関するページを参照してください。To review the API for this operation, see Add, update, or delete documents (REST).

  • この手順では動詞を POST に変更します。Change the verb to POST for this step.
  • /docs/index を含めるようにエンドポイントを変更します。Change the endpoint to include /docs/index. 完全な URL は https://my-app.search.windows.net/indexes/hotels/docs/index?api-version=2017-11-11 のようになります。The full URL should look like https://my-app.search.windows.net/indexes/hotels/docs/index?api-version=2017-11-11
  • 要求ヘッダーは変更しないでください。Keep the request headers as-is.

要求の本文には、hotels インデックスに追加する 4 つのドキュメントが含まれています。The Request Body contains four documents to be added to the hotels index.

     {
     "value": [
     {
         "@search.action": "upload",
         "hotelId": "1",
         "baseRate": 199.0,
         "description": "Best hotel in town",
         "hotelName": "Fancy Stay",
         "category": "Luxury",
         "tags": ["pool", "view", "wifi", "concierge"],
         "parkingIncluded": false,
         "smokingAllowed": false,
         "lastRenovationDate": "2010-06-27T00:00:00Z",
         "rating": 5,
         "location": { "type": "Point", "coordinates": [-122.131577, 47.678581] }
       },
       {
         "@search.action": "upload",
         "hotelId": "2",
         "baseRate": 79.99,
         "description": "Cheapest hotel in town",
         "hotelName": "Roach Motel",
         "category": "Budget",
         "tags": ["motel", "budget"],
         "parkingIncluded": true,
         "smokingAllowed": true,
         "lastRenovationDate": "1982-04-28T00:00:00Z",
         "rating": 1,
         "location": { "type": "Point", "coordinates": [-122.131577, 49.678581] }
       },
       {
         "@search.action": "upload",
         "hotelId": "3",
         "baseRate": 279.99,
         "description": "Surprisingly expensive",
         "hotelName": "Dew Drop Inn",
         "category": "Bed and Breakfast",
         "tags": ["charming", "quaint"],
         "parkingIncluded": true,
         "smokingAllowed": false,
         "lastRenovationDate": null,
         "rating": 4,
         "location": { "type": "Point", "coordinates": [-122.33207, 47.60621] }
       },
       {
         "@search.action": "upload",
         "hotelId": "4",
         "baseRate": 220.00,
         "description": "This could be the one",
         "hotelName": "A Hotel for Everyone",
         "category": "Basic hotel",
         "tags": ["pool", "wifi"],
         "parkingIncluded": true,
         "smokingAllowed": false,
         "lastRenovationDate": null,
         "rating": 4,
         "location": { "type": "Point", "coordinates": [-122.12151, 47.67399] }
       }
      ]
     }

数秒で、セッション一覧に HTTP 200 応答が表示されます。In a few seconds, you should see an HTTP 200 response in the session list. この応答は、ドキュメントが正常に作成されたことを示します。This indicates the documents were created successfully.

207 が表示された場合は、少なくとも 1 つのドキュメントのアップロードが失敗しています。If you get a 207, at least one document failed to upload. 404 が表示された場合は、要求のヘッダーまたは本文に構文エラーがあります。/docs/index を含めるようにエンドポイントを変更したことを確認してください。If you get a 404, you have a syntax error in either the header or body of the request: verify you changed the endpoint to include /docs/index.

ヒント

選択したデータ ソースについて、インデックス作成に必要なコードを簡易化してコード量を減らすことができる別のインデクサー アプローチを選択することができます。For selected data sources, you can choose the alternative indexer approach which simplifies and reduces the amount of code required for indexing. 詳細については、インデクサーの操作に関するページを参照してください。For more information, see Indexer operations.

FiddlerFiddler

動詞を POST に変更します。Change the verb to POST. /docs/index を含めるように URL を変更します。Change the URL to include /docs/index. 次のスクリーン ショットのようにドキュメントを要求本文にコピーし、要求を実行します。Copy the documents into the request body, similar to the following screen shot, and then execute the request.

Fiddler の要求ペイロード

postmanPostman

動詞を POST に変更します。Change the verb to POST. /docs/index を含めるように URL を変更します。Change the URL to include /docs/index. 次のスクリーン ショットのようにドキュメントを要求本文にコピーし、要求を実行します。Copy the documents into the request body, similar to the following screen shot, and then execute the request.

Postman の要求ペイロード

インデックスのクエリを実行するQuery the index

インデックスとドキュメントが読み込まれたら、クエリを発行することができます。Now that an index and documents are loaded, you can issue queries against them. この API の詳細については、ドキュメントの検索 (REST) に関するページを参照してください。For more information about this API, see Search Documents (REST)

  • この手順では動詞を GET に変更します。Change the verb to GET for this step.
  • 検索文字列など、クエリ パラメーターを含めるようにエンドポイントを変更します。Change the endpoint to include query parameters, including search strings. クエリの URL は https://my-app.search.windows.net/indexes/hotels/docs?search=motel&$count=true&api-version=2017-11-11 のようになりますA query URL might look like https://my-app.search.windows.net/indexes/hotels/docs?search=motel&$count=true&api-version=2017-11-11
  • 要求ヘッダーは変更しないでくださいKeep the request headers as-is

このクエリでは、"motel" という用語を検索し、検索結果でドキュメント数を返します。This query searches on the term "motel" and returns a count of the documents in the search results. Postman で [Send](送信) をクリックすると、要求と応答は次のスクリーン ショットのようになります。The request and response should look similar to the following screen shot for Postman after you click Send. 状態コードは 200 になります。The status code should be 200.

Postman のクエリ応答

Fiddler で Microsoft のサンプル クエリを実行するためのヒントTips for running our sample queries in Fiddler

次のクエリは、検索インデックス操作 (Azure Search API) に関する記事に掲載されている例です。The following example query is from the Search Index operation (Azure Search API) article. この記事のクエリ例の多くには、Fiddler では許可されないスペースが含まれています。Many of the example queries in this article include spaces, which are not allowed in Fiddler. Fiddler でクエリを実行する場合は、次のように、スペースを + 文字に置き換えてからクエリ文字列に貼り付けてください。Replace each space with a + character before pasting in the query string before attempting the query in Fiddler.

(lastRenovationDate desc の) スペースを置き換える前:Before spaces are replaced (in lastRenovationDate desc):

    GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2017-11-11

(lastRenovationDate+desc の) + でスペースを置き換えた後:After spaces are replaced with + (in lastRenovationDate+desc):

    GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate+desc&api-version=2017-11-11

クエリ インデックスのプロパティQuery index properties

システム情報のクエリを実行して、ドキュメント数とストレージ消費を取得することもできます。https://my-app.search.windows.net/indexes/hotels/stats?api-version=2017-11-11You can also query system information to get document counts and storage consumption: https://my-app.search.windows.net/indexes/hotels/stats?api-version=2017-11-11

Postman の場合、要求は次のようになります。また、応答にはドキュメント数とバイト単位の使用領域が含まれます。In Postman, your request should look similar to the following, and the response includes a document count and space used in bytes.

Postman のシステム クエリ

API バージョンの構文が異なる点に注目してください。Notice that the api-version syntax differs. この要求では、? を使用して API バージョンを付加しています。For this request, use ? to append the api-version. ?The ? は URL パスとクエリ文字列を区切っています。& はクエリ文字列内の各 "名前=値" ペアを区切っています。separates the URL path from the query string, while & separates each 'name=value' pair in the query string. このクエリのクエリ文字列では、API バージョンは最初で唯一の項目です。For this query, api-version is the first and only item in the query string.

この API の詳細については、インデックスの統計情報の取得 (REST) に関するページを参照してください。For more information about this API, see Get Index Statistics (REST).

Fiddler でインデックスの統計情報を表示するためのヒントTips for viewing index statistic in Fiddler

Fiddler で、[Inspectors](インスペクター) タブをクリックし、[Headers](ヘッダー) タブをクリックして、JSON 形式を選択します。In Fiddler, click the Inspectors tab, click the Headers tab, and then select the JSON format. ドキュメント数とストレージ サイズ (KB) が表示されます。You should see the document count and storage size (in KB).

次の手順Next steps

REST クライアントは即時の探索にとても有効です。この記事で REST API のしくみを理解したら、次はコードに進みましょう。REST clients are invaluable for impromptu exploration, but now that you know how the REST APIs work, you can move forward with code. 次のステップについては、以下のリンクを参照してください。For your next steps, see the following links: