Guida introduttiva: Controllare l'ortografia con l'API REST Controllo ortografico Bing e C#

Avviso

Il 30 ottobre 2020 le API Ricerca Bing sono state spostate dai servizi di intelligenza artificiale di Azure ai servizi di Ricerca Bing. Questa documentazione viene fornita solo per riferimento. Per la documentazione aggiornata, vedere la documentazione dell'API ricerca Bing. Per istruzioni sulla creazione di nuove risorse di Azure per la ricerca Bing, vedere Creare una risorsa Ricerca Bing tramite il Azure Marketplace.

Usare questa guida introduttiva per effettuare la prima chiamata all'API REST Controllo ortografico Bing. Questa semplice applicazione C# invia una richiesta all'API e restituisce un elenco di correzioni suggerite.

Anche se l'applicazione è scritta in C#, l'API è un servizio Web RESTful compatibile con la maggior parte dei linguaggi di programmazione. Il codice sorgente di questa applicazione è disponibile in GitHub.

Prerequisiti

• Qualsiasi edizione di Visual Studio 2017 o versioni successive.

• Pacchetto NuGet Newtonsoft.Json.

  Per installare questo pacchetto in Visual Studio:

  1. In Esplora soluzioni fare clic con il pulsante destro del mouse sul file della soluzione.
  2. Scegliere Gestisci pacchetti NuGet per la soluzione.
  3. Cercare Newtonsoft.Json e installare il pacchetto.

• Se si usa Linux/MacOS, è possibile eseguire questa applicazione con Mono.

Creare una risorsa di Azure

Per iniziare a usare l'API Controllo ortografico Bing, creare una delle seguenti risorse di Azure:

Risorsa Controllo ortografico Bing

• disponibile tramite il portale di Azure fino a quando la risorsa non viene eliminata.
• Usare il piano tariffario gratuito per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.
• L'API Controllo ortografico Bing è disponibile anche in alcuni livelli della risorsa Ricerca Bing v7.

Risorsa multi-servizio

• disponibile tramite il portale di Azure fino a quando la risorsa non viene eliminata.
• Usare la stessa chiave e lo stesso endpoint per le applicazioni in più servizi di intelligenza artificiale di Azure.

Creare e inizializzare un progetto

1. Creare una nuova soluzione console denominata SpellCheckSample in Visual Studio. Aggiungere quindi gli spazi dei nomi seguenti nel file di codice principale:

   using System;
   using System.Collections.Generic;
   using System.Linq;
   using System.Net.Http;
   using System.Net.Http.Headers;
   using System.Text;
   using Newtonsoft.Json;
   

2. Creare variabili per l'endpoint dell'API, la chiave di sottoscrizione e il testo da sottoporre a controllo ortografico. È possibile usare l'endpoint globale nel codice seguente o l'endpoint del sottodominio personalizzato visualizzato nel portale di Azure per la risorsa.

   namespace SpellCheckSample
   {
       class Program
       {
           static string host = "https://api.cognitive.microsoft.com";
           static string path = "/bing/v7.0/spellcheck?";
           static string key = "<ENTER-KEY-HERE>";
           //text to be spell-checked
           static string text = "Hollo, wrld!";
       }
   }
   

3. Creare una stringa per i parametri di ricerca:

   1. Assegnare il codice di mercato al parametro mkt con l'operatore =. Il codice di mercato è il codice del paese o dell'area geografica da cui si effettua la richiesta.

   2. Aggiungere il parametro mode con l'operatore & e quindi assegnare la modalità di controllo ortografico. La modalità può essere proof (individua la maggior parte degli errori di ortografia/grammatica) o spell (individua la maggior parte degli errori di ortografia, ma meno errori di grammatica).

   static string params_ = "mkt=en-US&mode=proof";
   

Creare e inviare una richiesta di controllo ortografico

1. Creare una funzione asincrona denominata SpellCheck() per inviare una richiesta all'API. Creare un oggetto HttpClient e aggiungere la chiave della sottoscrizione all'intestazione Ocp-Apim-Subscription-Key. All'interno della funzione eseguire i passaggi seguenti.

   async static void SpellCheck()
   {
       var client = new HttpClient();
       client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);
   
       HttpResponseMessage response = null;
       // add the rest of the code snippets here (except for main())...
   }
   

2. Creare l'URI per la richiesta aggiungendo l'host, il percorso e i parametri.

   string uri = host + path + params_;
   

3. Creare un elenco con un oggetto KeyValuePair contenente il testo e usarlo per creare un oggetto FormUrlEncodedContent. Impostare le informazioni dell'intestazione e usare PostAsync() per inviare la richiesta.

   var values = new Dictionary<string, string>();
   values.Add("text", text);
   var content = new FormUrlEncodedContent(values);
   content.Headers.ContentType = new MediaTypeHeaderValue("application/x-www-form-urlencoded");
   response = await client.PostAsync(uri, new FormUrlEncodedContent(values));
   

Ottenere e stampare la risposta dell'API

Ottenere l'intestazione dell'ID client

Se la risposta contiene un'intestazione X-MSEdge-ClientID, ottenere il valore e stamparlo.

string client_id;
if (response.Headers.TryGetValues("X-MSEdge-ClientID", out IEnumerable<string> header_values))
{
    client_id = header_values.First();
    Console.WriteLine("Client ID: " + client_id);
}

Ottenere la risposta

Ottenere la risposta dall'API. Deserializzare l'oggetto JSON e stamparlo nella console.

string contentString = await response.Content.ReadAsStringAsync();

dynamic jsonObj = JsonConvert.DeserializeObject(contentString);
Console.WriteLine(jsonObj);

Chiamare la funzione di controllo ortografico

Nella funzione Main() del progetto chiamare SpellCheck().

static void Main(string[] args)
{
    SpellCheck();
    Console.ReadLine();
}

Eseguire l'applicazione

Compilare ed eseguire il progetto. Se si usa Visual Studio, premere F5 per eseguire il debug del file.

Risposta JSON di esempio

Viene restituita una risposta con esito positivo in formato JSON, come illustrato nell'esempio seguente:

{
   "_type": "SpellCheck",
   "flaggedTokens": [
      {
         "offset": 0,
         "token": "Hollo",
         "type": "UnknownToken",
         "suggestions": [
            {
               "suggestion": "Hello",
               "score": 0.9115257530801
            },
            {
               "suggestion": "Hollow",
               "score": 0.858039839213461
            },
            {
               "suggestion": "Hallo",
               "score": 0.597385084464481
            }
         ]
      },
      {
         "offset": 7,
         "token": "wrld",
         "type": "UnknownToken",
         "suggestions": [
            {
               "suggestion": "world",
               "score": 0.9115257530801
            }
         ]
      }
   ]
}

Passaggi successivi

Creare app Web a pagina singola

• Informazioni sull'API Controllo ortografico Bing
• Informazioni di riferimento per l'API Controllo ortografico Bing v7