Avvio rapido: Usare la libreria client di Ricerca entità Bing

Articolo
03/06/2020

Avviso

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

Usare questa guida introduttiva per iniziare a cercare entità con la libreria client di Ricerca entità Bing per C#. Anche se Ricerca entità Bing ha un'API REST compatibile con la maggior parte dei linguaggi di programmazione, la libreria client offre un modo semplice per integrare il servizio nelle applicazioni. Il codice sorgente per questo esempio è disponibile su GitHub.

Prerequisiti

Qualsiasi edizione di Visual Studio 2017 o versioni successive.
Il framework Json.NET, disponibile come pacchetto NuGet.
Se si usa Linux/MacOS, questa applicazione può essere eseguita tramite Mono.
Pacchetto NuGet SDK di Ricerca notizie Bing. Installando questo pacchetto vengono anche installati gli elementi seguenti:
- Microsoft.Rest.ClientRuntime
- Microsoft.Rest.ClientRuntime.Azure
- Newtonsoft.Json

Per aggiungere la libreria client di Ricerca entità Bing al progetto di Visual Studio, usare l'opzione Gestisci pacchetti NuGet da Esplora soluzioni e aggiungere il Microsoft.Azure.CognitiveServices.Search.EntitySearch pacchetto.

Creare una risorsa di Azure

Per iniziare a usare l'API Ricerca entità Bing, creare una delle risorse di Azure seguenti.

Risorsa Ricerca entità 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.
Ricerca entità Bing è disponibile anche nei livelli a pagamento della risorsa Ricerca Bing v7.

Risorsa multiservizio

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

Creare e inizializzare un'applicazione

creare una nuova soluzione di console C# in Visual Studio. Aggiungere quindi quanto segue nel file di codice principale.

using System;
using System.Linq;
using System.Text;
using Microsoft.Azure.CognitiveServices.Search.EntitySearch;
using Microsoft.Azure.CognitiveServices.Search.EntitySearch.Models;
using Newtonsoft.Json;

Creare un client e inviare una richiesta di ricerca

Creare un nuovo client di ricerca. Aggiungere la chiave di sottoscrizione creando un nuovo oggetto ApiKeyServiceClientCredentials.
```
var client = new EntitySearchClient(new ApiKeyServiceClientCredentials("YOUR-ACCESS-KEY"));
```
Usare la funzione Entities.Search() del client per la ricerca della query:
```
var entityData = client.Entities.Search(query: "Satya Nadella");
```

Recuperare e stampare la descrizione di un'entità

Se l'API ha restituito risultati della ricerca, recuperare l'entità principale da entityData.

var mainEntity = entityData.Entities.Value.Where(thing => thing.EntityPresentationInfo.EntityScenario == EntityScenario.DominantEntity).FirstOrDefault();

Stampare la descrizione dell'entità principale.
```
Console.WriteLine(mainEntity.Description);
```

Passaggi successivi

Creare app Web a pagina singola

Informazioni sull'API Ricerca entità Bing

Usare questa guida introduttiva per iniziare a cercare entità con la libreria client Ricerca entità Bing per Java. Anche se Ricerca entità Bing ha un'API REST compatibile con la maggior parte dei linguaggi di programmazione, la libreria client offre un modo semplice per integrare il servizio nelle applicazioni. Il codice sorgente per questo esempio è disponibile su GitHub.

Prerequisiti

Java Development Kit (JDK)
Libreria client di Ricerca entità Bing per Java

Installare le dipendenze della libreria client di Ricerca entità Bing usando Maven, Gradle o un altro sistema di gestione delle dipendenze. Il file POM di Maven richiede la dichiarazione:

<dependency>
  <groupId>com.microsoft.azure.cognitiveservices</groupId>
  <artifactId>azure-cognitiveservices-entitysearch</artifactId>
  <version>1.0.2</version>
</dependency>

Creare una risorsa di Azure

Per iniziare a usare l'API Ricerca entità Bing, creare una delle risorse di Azure seguenti.

Risorsa Ricerca entità 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.
Ricerca entità Bing è disponibile anche nei livelli a pagamento della risorsa Ricerca Bing v7.

Risorsa multiservizio

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

Creare e inizializzare un progetto

Creare un nuovo progetto Java nell'ambiente di sviluppo integrato o nell'editor preferito e importare le librerie seguenti.

import com.microsoft.azure.cognitiveservices.entitysearch.*;
import com.microsoft.azure.cognitiveservices.entitysearch.implementation.EntitySearchAPIImpl;
import com.microsoft.azure.cognitiveservices.entitysearch.implementation.SearchResponseInner;
import com.microsoft.rest.credentials.ServiceClientCredentials;
import okhttp3.Interceptor;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

Creare una variabile per la chiave di sottoscrizione
```
String subscriptionKey = "your-key-here"
```

Creare un client di ricerca

Implementare il client dominantEntityLookup, che richiede l'endpoint API, e un'istanza della classe ServiceClientCredentials. È possibile usare l'endpoint globale seguente o l'endpoint sottodominio personalizzato visualizzato nel portale di Azure per la risorsa.

public static EntitySearchAPIImpl getClient(final String subscriptionKey) {
    return new EntitySearchAPIImpl("https://api.cognitive.microsoft.com/bing/v7.0/",
            new ServiceClientCredentials() {
            //...
            }
)};

Per implementare ServiceClientCredentials, seguire questa procedura:

Eseguire l'override della funzione applyCredentialsFilter(), con un oggetto OkHttpClient.Builder come parametro.

//...
new ServiceClientCredentials() {
        @Override
        public void applyCredentialsFilter(OkHttpClient.Builder builder) {
        //...
        }
//...

All'interno di applyCredentialsFilter(), chiamare builder.addNetworkInterceptor(). Creare un nuovo oggetto Interceptor ed eseguire l'override del relativo metodo intercept() per acquisire un oggetto intercettore Chain.
```
//...
builder.addNetworkInterceptor(
    new Interceptor() {
        @Override
        public Response intercept(Chain chain) throws IOException {
        //...    
        }
    });
///...
```

All'interno della funzione intercept creare le variabili per la richiesta. Usare Request.Builder() per creare la richiesta. Aggiungere la chiave della sottoscrizione all'intestazione Ocp-Apim-Subscription-Key e restituire chain.proceed() per l'oggetto della richiesta.

//...
public Response intercept(Chain chain) throws IOException {
    Request request = null;
    Request original = chain.request();
    Request.Builder requestBuilder = original.newBuilder()
            .addHeader("Ocp-Apim-Subscription-Key", subscriptionKey);
    request = requestBuilder.build();
    return chain.proceed(request);
}
//...

Inviare una richiesta e ricevere una risposta

Creare una nuova istanza del client di ricerca all'interno della chiave della sottoscrizione. Usare client.entities().search() per inviare una richiesta di ricerca per la query di ricerca satya nadella e ottenere una risposta.

EntitySearchAPIImpl client = getClient(subscriptionKey);
SearchResponseInner entityData = client.entities().search(
        "satya nadella", null, null, null, null, null, null, "en-us", null, null, SafeSearch.STRICT, null);

Se vengono restituite entità, convertirle in un elenco. Scorrere le entità e stampare quella dominante.

if (entityData.entities().value().size() > 0){
    // Find the entity that represents the dominant entity
    List<Thing> entries = entityData.entities().value();
    Thing dominateEntry = null;
    for(Thing thing : entries) {
        if(thing.entityPresentationInfo().entityScenario() == EntityScenario.DOMINANT_ENTITY) {
            System.out.println("\r\nSearched for \"Satya Nadella\" and found a dominant entity with this description:");
            System.out.println(thing.description());
            break;
        }
    }
}

Passaggi successivi

Creare un'app Web a pagina singola

Informazioni sull'API Ricerca entità Bing

Seguire questo argomento di avvio rapido per iniziare a cercare entità con la libreria client di Ricerca entità Bing per JavaScript. Anche se Ricerca entità Bing ha un'API REST compatibile con la maggior parte dei linguaggi di programmazione, la libreria client offre un modo semplice per integrare il servizio nelle applicazioni. Il codice sorgente per questo esempio è disponibile su GitHub.

Prerequisiti

La versione più recente di Node.js.
L'SDK di Ricerca entità Bing per JavaScript
- Per installarlo, eseguire npm install @azure/cognitiveservices-entitysearch
La classe CognitiveServicesCredentials del pacchetto @azure/ms-rest-azure-js per autenticare il client.
- Per installarlo, eseguire npm install @azure/ms-rest-azure-js

Creare una risorsa di Azure

Per iniziare a usare l'API Ricerca entità Bing, creare una delle risorse di Azure seguenti.

Risorsa Ricerca entità 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.
Ricerca entità Bing è disponibile anche nei livelli a pagamento della risorsa Ricerca Bing v7.

Risorsa multiservizio

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

Creare e inizializzare l'applicazione

Creare un nuovo file JavaScript nell'ambiente di sviluppo integrato o nell'editor preferito e aggiungere i requisiti seguenti.

const CognitiveServicesCredentials = require('@azure/ms-rest-azure-js').CognitiveServicesCredentials;
const EntitySearchAPIClient = require('@azure/cognitiveservices-entitysearch');

Creare un'istanza di CognitiveServicesCredentials usando la chiave della sottoscrizione. Quindi usarla per creare un'istanza del client di ricerca.
```
let credentials = new CognitiveServicesCredentials('YOUR-ACCESS-KEY');
let entitySearchApiClient = new EntitySearchAPIClient(credentials);
```

Inviare una richiesta e ricevere una risposta

Inviare una richiesta di ricerca entità con entitiesOperations.search(). Dopo aver ricevuto una risposta, stampare queryContext, il numero di risultati restituiti e la descrizione del primo risultato.

entitySearchApiClient.entitiesOperations.search('seahawks').then((result) => {
    console.log(result.queryContext);
    console.log(result.entities.value);
    console.log(result.entities.value[0].description);
}).catch((err) => {
    throw err;
});

Passaggi successivi

Creare app Web a pagina singola

Informazioni sull'API Ricerca entità Bing

Usare questa guida introduttiva per iniziare a cercare entità con la libreria client Ricerca entità Bing per Python. Anche se Ricerca entità Bing ha un'API REST compatibile con la maggior parte dei linguaggi di programmazione, la libreria client offre un modo semplice per integrare il servizio nelle applicazioni. Il codice sorgente per questo esempio è disponibile su GitHub.

Prerequisiti

Python 2.x o 3.x
SDK di Ricerca entità Bing per Python

È consigliabile usare un ambiente virtuale Python. È possibile installare e inizializzare un ambiente virtuale con il modulo venv. È possibile installare virtualenv con:

python -m venv mytestenv

Installare la libreria client di Ricerca entità Bing con:

cd mytestenv
python -m pip install azure-cognitiveservices-search-entitysearch

Creare una risorsa di Azure

Per iniziare a usare l'API Ricerca entità Bing, creare una delle risorse di Azure seguenti.

Risorsa Ricerca entità 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.
Ricerca entità Bing è disponibile anche nei livelli a pagamento della risorsa Ricerca Bing v7.

Risorsa multiservizio

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

Creare e inizializzare l'applicazione

Creare un nuovo file Python nell'IDE o nell'editor preferito e aggiungere le istruzioni di importazione seguenti.

from azure.cognitiveservices.search.entitysearch import EntitySearchClient
from azure.cognitiveservices.search.entitysearch.models import Place, ErrorResponseException
from msrest.authentication import CognitiveServicesCredentials

Creare una variabile per l'endpoint e la chiave della sottoscrizione. Creare un'istanza del client creando un nuovo oggetto CognitiveServicesCredentials con la chiave.

subscription_key = "YOUR-SUBSCRIPTION-KEY"
endpoint = "YOUR-ENDPOINT"
client = EntitySearchclient(endpoint=endpoint, credentials=CognitiveServicesCredentials(subscription_key))

Inviare una richiesta di ricerca e ricevere una risposta

Inviare una richiesta di ricerca a Ricerca entità Bing con client.entities.search() e una query di ricerca.
```
entity_data = client.entities.search(query="Gibralter")
```

Se vengono restituite entità, convertire entity_data.entities.value in un elenco e stampare il primo risultato.

if entity_data.entities.value:

    main_entities = [entity for entity in entity_data.entities.value
                     if entity.entity_presentation_info.entity_scenario == "DominantEntity"]

    if main_entities:
        print(main_entities[0].description)

Passaggi successivi

Creare app Web a pagina singola

Informazioni sull'API Ricerca entità Bing

Avvio rapido: Usare la libreria client di Ricerca entità Bing

Prerequisiti

Creare una risorsa di Azure

Creare e inizializzare un'applicazione

Creare un client e inviare una richiesta di ricerca

Recuperare e stampare la descrizione di un'entità

Passaggi successivi

Prerequisiti

Creare una risorsa di Azure

Creare e inizializzare un progetto

Creare un client di ricerca

Inviare una richiesta e ricevere una risposta

Passaggi successivi

Prerequisiti

Creare una risorsa di Azure

Creare e inizializzare l'applicazione

Inviare una richiesta e ricevere una risposta

Passaggi successivi

Prerequisiti

Creare una risorsa di Azure

Creare e inizializzare l'applicazione

Inviare una richiesta di ricerca e ricevere una risposta

Passaggi successivi

Risorse aggiuntive