Esempio: Creare una competenza personalizzata usando l'API Ricerca entità Bing
Questo esempio illustra come creare una competenza personalizzata dell'API Web. Questa competenza accetterà posizioni, figure pubbliche e organizzazioni, e restituirà loro delle descrizioni. L'esempio usa una funzione di Azure per eseguire il wrapping dell'API Ricerca Entità Bing in modo da implementare l'interfaccia della competenza personalizzata.
Prerequisiti
Leggere l'articolo sull'interfaccia per le competenze personalizzate se non si ha familiarità con l'interfaccia di input/output che una competenza personalizzata deve implementare.
Creare una risorsa di Ricerca Bing tramite il portale di Azure. Un livello gratuito è disponibile e sufficiente per questo esempio.
Installare Visual Studio o versione successiva.
Crea una Funzione di Azure
Questo esempio usa una funzione di Azure per ospitare un'API Web, tuttavia non si tratta di un requisito obbligatorio. Purché si rispettino i requisiti di interfaccia per una competenza cognitiva, l'approccio adottato è irrilevante. Funzioni di Azure, tuttavia, rende la creazione di una competenza personalizzata estremamente semplice.
Creare un progetto
In Visual Studio selezionare Nuovo>Progetto dal menu File.
Scegliere Funzioni di Azure come modello e selezionare Avanti. Digitare un nome per il progetto e selezionare Crea. Il nome dell'app per le funzioni deve essere valido come spazio dei nomi C#, quindi non usare caratteri di sottolineatura, trattini o altri caratteri non alfanumerici.
Selezionare un framework con supporto a lungo termine.
Scegliere Trigger HTTP per il tipo di funzione da aggiungere al progetto.
Scegliere Funzione per il livello di autorizzazione.
Selezionare Crea per creare il progetto per le funzioni e la funzione attivata da HTTP.
Aggiungere codice per chiamare l'API entità Bing
Visual Studio crea un progetto con codice boilerplate per il tipo di funzione scelto. L'attributo FunctionName nel metodo imposta il nome della funzione. L'attributo HttpTrigger specifica che la funzione è attivata da una richiesta HTTP.
Sostituire il contenuto di Function1.cs con il codice seguente:
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
namespace SampleSkills
{
/// <summary>
/// Sample custom skill that wraps the Bing entity search API to connect it with a
/// AI enrichment pipeline.
/// </summary>
public static class BingEntitySearch
{
#region Credentials
// IMPORTANT: Make sure to enter your credential and to verify the API endpoint matches yours.
static readonly string bingApiEndpoint = "https://api.bing.microsoft.com/v7.0/entities";
static readonly string key = "<enter your api key here>";
#endregion
#region Class used to deserialize the request
private class InputRecord
{
public class InputRecordData
{
public string Name { get; set; }
}
public string RecordId { get; set; }
public InputRecordData Data { get; set; }
}
private class WebApiRequest
{
public List<InputRecord> Values { get; set; }
}
#endregion
#region Classes used to serialize the response
private class OutputRecord
{
public class OutputRecordData
{
public string Name { get; set; } = "";
public string Description { get; set; } = "";
public string Source { get; set; } = "";
public string SourceUrl { get; set; } = "";
public string LicenseAttribution { get; set; } = "";
public string LicenseUrl { get; set; } = "";
}
public class OutputRecordMessage
{
public string Message { get; set; }
}
public string RecordId { get; set; }
public OutputRecordData Data { get; set; }
public List<OutputRecordMessage> Errors { get; set; }
public List<OutputRecordMessage> Warnings { get; set; }
}
private class WebApiResponse
{
public List<OutputRecord> Values { get; set; }
}
#endregion
#region Classes used to interact with the Bing API
private class BingResponse
{
public BingEntities Entities { get; set; }
}
private class BingEntities
{
public BingEntity[] Value { get; set; }
}
private class BingEntity
{
public class EntityPresentationinfo
{
public string[] EntityTypeHints { get; set; }
}
public class License
{
public string Url { get; set; }
}
public class ContractualRule
{
public string _type { get; set; }
public License License { get; set; }
public string LicenseNotice { get; set; }
public string Text { get; set; }
public string Url { get; set; }
}
public ContractualRule[] ContractualRules { get; set; }
public string Description { get; set; }
public string Name { get; set; }
public EntityPresentationinfo EntityPresentationInfo { get; set; }
}
#endregion
#region The Azure Function definition
[FunctionName("EntitySearch")]
public static async Task<IActionResult> Run(
[HttpTrigger(AuthorizationLevel.Function, "post", Route = null)] HttpRequest req,
ILogger log)
{
log.LogInformation("Entity Search function: C# HTTP trigger function processed a request.");
var response = new WebApiResponse
{
Values = new List<OutputRecord>()
};
string requestBody = new StreamReader(req.Body).ReadToEnd();
var data = JsonConvert.DeserializeObject<WebApiRequest>(requestBody);
// Do some schema validation
if (data == null)
{
return new BadRequestObjectResult("The request schema does not match expected schema.");
}
if (data.Values == null)
{
return new BadRequestObjectResult("The request schema does not match expected schema. Could not find values array.");
}
// Calculate the response for each value.
foreach (var record in data.Values)
{
if (record == null || record.RecordId == null) continue;
OutputRecord responseRecord = new OutputRecord
{
RecordId = record.RecordId
};
try
{
responseRecord.Data = GetEntityMetadata(record.Data.Name).Result;
}
catch (Exception e)
{
// Something bad happened, log the issue.
var error = new OutputRecord.OutputRecordMessage
{
Message = e.Message
};
responseRecord.Errors = new List<OutputRecord.OutputRecordMessage>
{
error
};
}
finally
{
response.Values.Add(responseRecord);
}
}
return (ActionResult)new OkObjectResult(response);
}
#endregion
#region Methods to call the Bing API
/// <summary>
/// Gets metadata for a particular entity based on its name using Bing Entity Search
/// </summary>
/// <param name="entityName">The name of the entity to extract data for.</param>
/// <returns>Asynchronous task that returns entity data. </returns>
private async static Task<OutputRecord.OutputRecordData> GetEntityMetadata(string entityName)
{
var uri = bingApiEndpoint + "?q=" + entityName + "&mkt=en-us&count=10&offset=0&safesearch=Moderate";
var result = new OutputRecord.OutputRecordData();
using (var client = new HttpClient())
using (var request = new HttpRequestMessage {
Method = HttpMethod.Get,
RequestUri = new Uri(uri)
})
{
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string responseBody = await response?.Content?.ReadAsStringAsync();
BingResponse bingResult = JsonConvert.DeserializeObject<BingResponse>(responseBody);
if (bingResult != null)
{
// In addition to the list of entities that could match the name, for simplicity let's return information
// for the top match as additional metadata at the root object.
return AddTopEntityMetadata(bingResult.Entities?.Value);
}
}
return result;
}
private static OutputRecord.OutputRecordData AddTopEntityMetadata(BingEntity[] entities)
{
if (entities != null)
{
foreach (BingEntity entity in entities.Where(
entity => entity?.EntityPresentationInfo?.EntityTypeHints != null
&& (entity.EntityPresentationInfo.EntityTypeHints[0] == "Person"
|| entity.EntityPresentationInfo.EntityTypeHints[0] == "Organization"
|| entity.EntityPresentationInfo.EntityTypeHints[0] == "Location")
&& !String.IsNullOrEmpty(entity.Description)))
{
var rootObject = new OutputRecord.OutputRecordData
{
Description = entity.Description,
Name = entity.Name
};
if (entity.ContractualRules != null)
{
foreach (var rule in entity.ContractualRules)
{
switch (rule._type)
{
case "ContractualRules/LicenseAttribution":
rootObject.LicenseAttribution = rule.LicenseNotice;
rootObject.LicenseUrl = rule.License.Url;
break;
case "ContractualRules/LinkAttribution":
rootObject.Source = rule.Text;
rootObject.SourceUrl = rule.Url;
break;
}
}
}
return rootObject;
}
}
return new OutputRecord.OutputRecordData();
}
#endregion
}
}
Assicurarsi di immettere il proprio valore di chiave nella costante key in base alla chiave ottenuta durante l'iscrizione all'API di ricerca di entità Bing.
Testare la funzione da Visual Studio
Premere F5 per eseguire il programma e testare i comportamenti della funzione. In questo caso, si userà la funzione seguente per cercare due entità. Usare un client REST per eseguire una chiamata come quella illustrata di seguito:
POST https://localhost:7071/api/EntitySearch
Testo della richiesta
{
"values": [
{
"recordId": "e1",
"data":
{
"name": "Pablo Picasso"
}
},
{
"recordId": "e2",
"data":
{
"name": "Microsoft"
}
}
]
}
Risposta
La risposta dovrebbe essere simile all'esempio seguente:
{
"values": [
{
"recordId": "e1",
"data": {
"name": "Pablo Picasso",
"description": "Pablo Ruiz Picasso was a Spanish painter [...]",
"source": "Wikipedia",
"sourceUrl": "http://en.wikipedia.org/wiki/Pablo_Picasso",
"licenseAttribution": "Text under CC-BY-SA license",
"licenseUrl": "http://creativecommons.org/licenses/by-sa/3.0/"
},
"errors": null,
"warnings": null
},
"..."
]
}
Pubblicare la funzione in Azure
Quando si è soddisfatti del comportamento della funzione, è possibile pubblicarla.
In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto e scegliere Pubblica. Scegliere Crea nuovo>Pubblica.
Se non si è ancora connesso Visual Studio al proprio account di Azure, selezionare Aggiungi un account.
Seguire le istruzioni visualizzate sullo schermo. Viene chiesto di specificare un nome univoco per il servizio app, la sottoscrizione di Azure, il gruppo di risorse, il piano di hosting e l'account di archiviazione da usare. Se non sono già disponibili, è possibile creare un nuovo gruppo di risorse, un nuovo piano di hosting e un account di archiviazione. Al termine selezionare Crea
Al termine della distribuzione, notare l'URL del sito. Questo è l'indirizzo dell'app per le funzioni in Azure.
Nel portale di Azure, passare al gruppo di risorse e cercare la funzione di
EntitySearchpubblicata. Nella sezione Gestisci dovrebbe essere presente un elenco Chiavi host. Selezionare l'icona Copia icona per la chiave host predefinita.
Testare la funzione in Azure
Ora che si dispone della chiave host predefinita, testare la funzione come segue:
POST https://[your-entity-search-app-name].azurewebsites.net/api/EntitySearch?code=[enter default host key here]
Corpo della richiesta
{
"values": [
{
"recordId": "e1",
"data":
{
"name": "Pablo Picasso"
}
},
{
"recordId": "e2",
"data":
{
"name": "Microsoft"
}
}
]
}
Questo esempio dovrebbe produrre lo stesso risultato visualizzato in precedenza durante l'esecuzione della funzione nell'ambiente locale.
Connettersi alla pipeline
A questo punto è possibile aggiungere la competenza personalizzata al proprio set di competenze. L'esempio seguente illustra come chiamare la competenza per aggiungere descrizioni alle organizzazioni nel documento (questo potrebbe essere esteso anche per lavorare su posizioni e persone). Sostituire [your-entity-search-app-name] con il nome dell'app.
{
"skills": [
"[... your existing skills remain here]",
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "Our new Bing entity search custom skill",
"uri": "https://[your-entity-search-app-name].azurewebsites.net/api/EntitySearch?code=[enter default host key here]",
"context": "/document/merged_content/organizations/*",
"inputs": [
{
"name": "name",
"source": "/document/merged_content/organizations/*"
}
],
"outputs": [
{
"name": "description",
"targetName": "description"
}
]
}
]
}
In questo caso, si conta sul fatto che l'abilità di riconoscimento delle entità predefinita sia presente nel set di competenze e che abbia arricchito il documento con l'elenco delle organizzazioni. Per riferimento, ecco una configurazione della competenza di estrazione di entità sufficiente per generare i dati necessari:
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"name": "#1",
"description": "Organization name extraction",
"context": "/document/merged_content",
"categories": [ "Organization" ],
"defaultLanguageCode": "en",
"inputs": [
{
"name": "text",
"source": "/document/merged_content"
},
{
"name": "languageCode",
"source": "/document/language"
}
],
"outputs": [
{
"name": "organizations",
"targetName": "organizations"
}
]
},
Passaggi successivi
Complimenti. È stata creata la prima competenza personalizzata. Ora è possibile seguire lo stesso schema per aggiungere funzionalità personalizzate. Fare clic sui collegamenti seguenti per altre informazioni.