Esplorare le API REST di Ricerca di Azure con Fiddler o PostmanExplore Azure Search REST APIs using Fiddler or Postman

Uno dei modi più semplici per esplorare l'API REST di Ricerca di Azure consiste nell'usare Fiddler o Postman per formulare le richieste HTTP e analizzare le risposte.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. In questo articolo si sperimentano i payload di richiesta e di risposta senza dover scrivere codice.In this article, experiment with request and response payloads without having to write any code.

  • Scaricare uno strumento di test delle API WebDownload a web api test tool
  • Ottenere la chiave API e l'endpoint per il servizio di ricercaGet the api-key and endpoint for your search service
  • Configurare le intestazioni delle richiesteConfigure request headers
  • Creare un indiceCreate an index
  • Caricare un indiceLoad an index
  • Eseguire la ricerca in un indiceSearch an index

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare e quindi eseguire la registrazione a Ricerca di Azure.If you don't have an Azure subscription, create a free account before you begin and then sign up for Azure Search.

Scaricare e installare gli strumentiDownload and install tools

Gli strumenti seguenti sono spesso usati per lo sviluppo Web, ma se si ha familiarità con un altro strumento, le istruzioni riportate in questo articolo dovrebbero essere comunque valide.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.

Ottenere la chiave API e l'endpointGet the api-key and endpoint

Le chiamate REST richiedono l'URL del servizio e una chiave di accesso per ogni richiesta.REST calls require the service URL and an access key on every request. Con entrambi gli elementi viene creato un servizio di ricerca, quindi se si è aggiunto Ricerca di Azure alla sottoscrizione, seguire questi passaggi per ottenere le informazioni necessarie: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. Nel portale di Azure aprire la pagina del servizio di ricerca dal dashboard o trovare il servizio nell'elenco di servizi.In the Azure portal, open the search service page from the dashboard or find your service in the service list.
  2. Ottenere l'endpoint in Panoramica > Informazioni di base > URL.Get the endpoint at Overview > Essentials > Url. Un endpoint di esempio potrebbe essere simile a https://my-service-name.search.windows.net.An example endpoint might look like https://my-service-name.search.windows.net.
  3. Ottenere la chiave API in Impostazioni > Chiavi.Get the api-key in Settings > Keys. Ci sono due chiavi amministratore per offrire ridondanza nel caso in cui si voglia eseguire il rollback delle chiavi.There are two admin keys for redundancy in case you want to roll over keys. Le chiavi amministratore concedono le autorizzazioni di scrittura per il servizio, necessarie per creare e caricare gli indici.Admin keys grant the write permissions on your service, necessary for creating and loading indexes. Per le operazioni di scrittura è possibile usare la chiave primaria o secondaria.You can use either the primary or secondary key for write operations.

Configurare le intestazioni delle richiesteConfigure request headers

Ogni strumento conserva le informazioni dell'intestazione della richiesta per la sessione, quindi è necessario immettere l'endpoint dell'URL, la versione API, la chiave API e il tipo di contenuto una sola volta.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.

L'URL completo dovrebbe essere simile all'esempio seguente, con un valore valido per il segnaposto my-app: https://my-app.search.windows.net/indexes/hotels?api-version=2016-09-01The 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=2016-09-01

La composizione dell'URL del servizio include gli elementi seguenti:Service URL composition includes the following elements:

  • Prefisso HTTPS.HTTPS prefix.
  • URL del servizio, ottenuto dal portale.Service URL, obtained from the portal.
  • Risorsa, un'operazione che crea un oggetto nel servizio.Resource, an operation that creates an object on your service. In questo passaggio si tratta di un indice denominato hotels.In this step, it is an index named hotels.
  • Versione API, una stringa obbligatoria in caratteri minuscoli specificata come "?api-version=2016-09-01" per la versione corrente.api-version, a required lowercase string specified as "?api-version=2016-09-01" for the current version. Le versioni API vengono aggiornate regolarmente.API versions are updated regularly. Includendo l'elemento api-version in ogni richiesta, è possibile avere controllo completo sulla versione API usata.Including the api-version on each request gives you full control over which one is used.

La composizione dell'intestazione della richiesta include due elementi, il tipo di contenuto e la chiave API, come descritto nella sezione precedente: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

Formulare una richiesta simile allo screenshot seguente.Formulate a request that looks like the following screen shot. Scegliere PUT come verbo.Choose PUT as the verb. Fiddler aggiunge User-Agent=Fiddler.Fiddler adds User-Agent=Fiddler. È possibile incollare due intestazioni delle richieste aggiuntive nelle nuove righe al di sotto dell'elemento.You can paste the two additional request headers on new lines below it. Includere il tipo di contenuto e la chiave API per il servizio, usando la chiave di accesso di amministratore per il servizio.Include the content type and api-key for your service, using the admin access key for your service.

Intestazione della richiesta Fiddler

Suggerimento

È possibile disattivare il traffico Web per nascondere l'attività HTTP estranea non correlata alle attività che si stanno eseguendo.You can turn off web traffic to hide extraneous HTTP activity unrelated to the tasks you are performing. In Fiddler passare al menu File e disattivare l'opzione Capture Traffic (Acquisisci traffico).In Fiddler, go to the File menu and turn off Capture Traffic.

PostmanPostman

Formulare una richiesta simile allo screenshot seguente.Formulate a request that looks like the following screen shot. Scegliere PUT come verbo.Choose PUT as the verb.

Intestazione della richiesta Postman

Creare l'indiceCreate the index

Il corpo della richiesta contiene la definizione di indice.The body of the request contains the index definition. Aggiungendo il corpo della richiesta, si completa la richiesta che produce l'indice.Adding the request body completes the request that produces your index.

Oltre al nome dell'indice, il componente più importante nella richiesta è la raccolta fields.Besides the index name, the most important component in the request is the fields collection. La raccolta fields definisce lo schema dell'indice.The fields collection defines the index schema. In ogni campo, specificare il relativo tipo.On each field, specify its type. I campi stringa vengono usati nella ricerca full-text, quindi è consigliabile eseguire il cast dei dati numerici come stringhe se è necessario consentire l'esecuzione di ricerche nel contenuto.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.

Gli attributi nel campo determinano l'azione consentita.Attributes on the field determine allowed action. Le API REST consentono numerose azioni per impostazione predefinita.The REST APIs allow many actions by default. Tutte le stringhe, ad esempio, per impostazione predefinita consentono le ricerche, possono essere recuperate e filtrate e prevedono facet.For example, all strings are searchable, retrievable, filterable, and facetable by default. Spesso è necessario impostare gli attributi solo per disattivare un comportamento.Often, you only have to set attributes when you need to turn a behavior off. Per altre informazioni sugli attributi, vedere l'articolo relativo all'operazione Create Index (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"}
      ]
     }

Quando si invia questa richiesta, si dovrebbe ottenere una risposta HTTP 201, che indica che l'indice è stato creato correttamente.When you submit this request, you should get an HTTP 201 response, indicating the index was created successfully. È possibile verificare questa azione nel portale, ma si noti che, in base agli intervalli di aggiornamento della pagina del portale, potrebbero essere necessari uno o due minuti.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.

Se viene restituita una risposta HTTP 504, verificare se nell'URL è specificato HTTPS.If you get HTTP 504, verify the URL specifies HTTPS. Se viene visualizzata la risposta HTTP 400 o 404, esaminare il corpo della richiesta per verificare che le operazioni di copia e incolla sono state eseguite correttamente.If you see HTTP 400 or 404, check the request body to verify there were no copy-paste errors. Una risposta HTTP 403 indica in genere che si è verificato un problema con la chiave API (chiave non valida o problema di sintassi nella specifica della chiave 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

Copiare la definizione di indice nel corpo della richiesta, in modo analogo allo screenshot seguente, e quindi fare clic su Execute (Esegui) in alto a destra per inviare la richiesta completata.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.

Corpo della richiesta Fiddler

PostmanPostman

Copiare la definizione di indice nel corpo della richiesta, in modo analogo allo screenshot seguente, e quindi fare clic su Send (Invia) in alto a destra per inviare la richiesta completata.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.

Corpo della richiesta Postman

Caricare i documentiLoad documents

La creazione e il popolamento dell'indice sono passaggi distinti.Creating the index and populating the index are separate steps. In Ricerca di Azure l'indice contiene tutti i dati che consentono le ricerche, che è possibile fornire come documenti JSON.In Azure Search, the index contains all searchable data, which you can provide as JSON documents. Per esaminare l'API per questa operazione, vedere Add, update, or delete documents (REST) (Aggiungere, aggiornare o eliminare documenti - REST).To review the API for this operation, see Add, update, or delete documents (REST).

  • Modificare il verbo in POST per questo passaggio.Change the verb to POST for this step.
  • Modificare l'endpoint per includere /docs/index.Change the endpoint to include /docs/index. L'URL completo dovrebbe essere simile a https://my-app.search.windows.net/indexes/hotels/docs/index?api-version=2016-09-01The full URL should look like https://my-app.search.windows.net/indexes/hotels/docs/index?api-version=2016-09-01
  • Mantenere le intestazioni delle richieste così come sono.Keep the request headers as-is.

Il corpo della richiesta contiene quattro documenti da aggiungere all'indice degli hotel.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] }
       }
      ]
     }

Entro pochi secondi si dovrebbe visualizzare una risposta HTTP 200 nella sessione.In a few seconds, you should see an HTTP 200 response in the session list. Questo indica che i documenti sono stati creati correttamente.This indicates the documents were created successfully.

Se viene restituito un codice 207, significa che il caricamento di almeno uno dei documenti non è riuscito.If you get a 207, at least one document failed to upload. Se viene restituito un codice 404, significa che è presente un errore di sintassi nell'intestazione o nel corpo della richiesta. Verificare di aver modificato l'endpoint per includere /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.

Suggerimento

Per le origini dati selezionate, è possibile scegliere l'approccio alternativo tramite indicizzatore, che semplifica e riduce la quantità di codice necessario per l'indicizzazione.For selected data sources, you can choose the alternative indexer approach which simplifies and reduces the amount of code required for indexing. Per altre informazioni, vedere Indexer operations (Operazioni dell'indicizzatore).For more information, see Indexer operations.

FiddlerFiddler

Modificare il verbo in POST.Change the verb to POST. Modificare l'URL per includere /docs/index.Change the URL to include /docs/index. Copiare i documenti nel corpo della richiesta, in modo analogo allo screenshot seguente, e quindi eseguire la richiesta.Copy the documents into the request body, similar to the following screen shot, and then execute the request.

Payload della richiesta Fiddler

PostmanPostman

Modificare il verbo in POST.Change the verb to POST. Modificare l'URL per includere /docs/index.Change the URL to include /docs/index. Copiare i documenti nel corpo della richiesta, in modo analogo allo screenshot seguente, e quindi eseguire la richiesta.Copy the documents into the request body, similar to the following screen shot, and then execute the request.

Payload della richiesta Postman

Eseguire una query sull'indiceQuery the index

Ora che l'indice e i documenti sono stati caricati, è possibile eseguire query su di essi.Now that an index and documents are loaded, you can issue queries against them. Per altre informazioni su quest'API, vedere l'articolo relativo all'operazione Search Documents (REST)For more information about this API, see Search Documents (REST)

  • Modificare il verbo in GET per questo passaggio.Change the verb to GET for this step.
  • Modificare l'endpoint per includere i parametri di query, comprese le stringhe di ricerca.Change the endpoint to include query parameters, including search strings. Un URL di query potrebbe essere simile a https://my-app.search.windows.net/indexes/hotels/docs?search=motel&$count=true&api-version=2016-09-01A query URL might look like https://my-app.search.windows.net/indexes/hotels/docs?search=motel&$count=true&api-version=2016-09-01
  • Mantenere le intestazioni delle richieste così come sonoKeep the request headers as-is

Questa query cerca il termine "motel" e restituisce il numero di documenti nei risultati della ricerca.This query searches on the term "motel" and returns a count of the documents in the search results. La richiesta e la risposta dovrebbero essere simili allo screenshot seguente per Postman dopo avere fatto clic su Send (Invia).The request and response should look similar to the following screen shot for Postman after you click Send. Il codice di stato dovrebbe essere 200.The status code should be 200.

Risposta alla query Postman

Suggerimenti per l'esecuzione delle query di esempio in FiddlerTips for running our sample queries in Fiddler

La query di esempio seguente è tratta dall'argomento relativo all'operazione di ricerca nell'indice (API di Ricerca di Azure).The following example query is from the Search Index operation (Azure Search API) article. Molte delle query di esempio in questo articolo includono spazi, che non sono consentiti in Fiddler.Many of the example queries in this article include spaces, which are not allowed in Fiddler. Sostituire tutti gli spazi con un carattere + prima di incollare la stringa di query ed eseguirla in Fiddler.Replace each space with a + character before pasting in the query string before attempting the query in Fiddler.

Prima della sostituzione degli spazi (in lastRenovationDate desc):Before spaces are replaced (in lastRenovationDate desc):

    GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2016-09-01

Dopo la sostituzione degli spazi con + (in lastRenovationDate+desc):After spaces are replaced with + (in lastRenovationDate+desc):

    GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate+desc&api-version=2016-09-01

Eseguire una query per le proprietà dell'indiceQuery index properties

È anche possibile eseguire una query relativa alle informazioni di sistema per ottenere il numero di documenti e informazioni sull'utilizzo dello spazio di archiviazione: https://my-app.search.windows.net/indexes/hotels/stats?api-version=2016-09-01You can also query system information to get document counts and storage consumption: https://my-app.search.windows.net/indexes/hotels/stats?api-version=2016-09-01

In Postman la richiesta dovrebbe essere simile alla seguente e la risposta include il numero di documenti e lo spazio usato in byte.In Postman, your request should look similar to the following, and the response includes a document count and space used in bytes.

Query di sistema Postman

Si noti che la sintassi relativa alla versione API è diversa.Notice that the api-version syntax differs. Per questa richiesta, usare ? per aggiungere l'elemento api-version.For this request, use ? to append the api-version. Il carattere ?The ? separa il percorso dell'URL dalla stringa di query, mentre & separa ogni coppia "nome=valore" nella stringa di query.separates the URL path from the query string, while & separates each 'name=value' pair in the query string. Per questa query, api-version è il primo e unico elemento nella stringa di query.For this query, api-version is the first and only item in the query string.

Per altre informazioni su quest'API, vedere l'articolo relativo all'operazione Get Index Statistics (REST).For more information about this API, see Get Index Statistics (REST).

Suggerimenti per la visualizzazione delle statistiche di indice in FiddlerTips for viewing index statistic in Fiddler

In Fiddler fare clic sulla scheda Inspectors (Controlli), quindi sulla scheda Headers (Intestazioni) e selezionare il formato JSON.In Fiddler, click the Inspectors tab, click the Headers tab, and then select the JSON format. Verrà visualizzato il numero di documenti e la dimensione dello spazio di archiviazione (in KB).You should see the document count and storage size (in KB).

Passaggi successiviNext steps

I client REST sono molto utili per l'esplorazione improvvisata, ma ora che si conosce il funzionamento delle API REST, è possibile precedere con il codice.REST clients are invaluable for impromptu exploration, but now that you know how the REST APIs work, you can move forward with code. Per i passaggi successivi, vedere i collegamenti seguenti:For your next steps, see the following links: