Guida introduttiva: Cercare video con l'API REST Ricerca video Bing e C#
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 di avvio rapido per effettuare la prima chiamata all'API Ricerca video Bing. Questa semplice applicazione C# invia una query di ricerca video HTTP all'API e visualizza la risposta JSON. 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 per questo esempio è disponibile in GitHub con altre annotazioni di codice, funzionalità e informazioni sulla gestione degli errori.
Prerequisiti
È necessario configurare il computer per l'esecuzione di .NET core. Per le istruzioni per l'installazione, vedere la pagina di download di .NET Core. È possibile eseguire questa applicazione in Windows, Linux, macOS o in un contenitore Docker. È necessario installare l'editor di codice preferito. Nelle descrizioni seguenti viene usato Visual Studio Code, un editor open source multipiattaforma, ma è possibile usare gli strumenti con cui si ha maggiore familiarità.
Creare una risorsa di Azure
Per iniziare a usare l'API Ricerca video Bing, creare una delle risorse di Azure seguenti:
- 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.
- 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
Il primo passaggio consiste nel creare una nuova applicazione. Aprire un prompt dei comandi e creare una nuova directory per l'applicazione, impostandola come directory corrente. Immettere il comando seguente in una finestra della console:
dotnet new console --name VideoSearchClient
È necessario aggiungere la direttiva using seguente all'inizio del metodo Main, in modo che il compilatore C# riconosca i tipi Task e JSON:
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Collections.Generic;
using System.Text.Json;
using System.Text.Json.Serialization;
Aggiungere variabili per la chiave di sottoscrizione, l'endpoint e un termine di ricerca. Per il valore di uriBase, è possibile usare l'endpoint globale nel codice seguente o l'endpoint del sottodominio personalizzato visualizzato nel portale di Azure per la risorsa.
// Replace the accessKey string value with your valid access key.
const string _accessKey = "enter your key here";
// Or use the custom subdomain endpoint displayed in the Azure portal for your resource.
const string _uriBase = "https://api.cognitive.microsoft.com/bing/v7.0/videos/search";
const string _searchTerm = "kittens";
Successivamente, aggiornare il metodo Main per poter usare i metodi asincroni. Aggiungere il modificatore async e cambiare il tipo restituito in Task.
static async Task Main(string[] args)
{
}
A questo punto è disponibile un programma che non esegue alcuna operazione, ma è impostato per l'esecuzione asincrona. È ora possibile migliorarlo.
Creare una struttura dati in cui contenere la risposta dell'API Ricerca video Bing
Definire le classi SearchResult e Video in cui inserire i risultati della ricerca video. È possibile aggiungere altre proprietà in un secondo momento, se sono necessari altri campi del risultato JSON.
class SearchResult
{
[JsonPropertyName("totalEstimatedMatches")]
public int TotalEstimatedMatches { get; set; }
[JsonPropertyName("value")]
public List<Video> Videos { get; set; }
}
class Video
{
[JsonPropertyName("name")]
public string Name { get; set; }
[JsonPropertyName("description")]
public string Description { get; set; }
[JsonPropertyName("thumbnailUrl")]
public string ThumbnailUrl { get; set; }
[JsonPropertyName("contentUrl")]
public string ContentUrl { get; set; }
}
Creare e gestire una nuova richiesta di ricerca video
Usare HttpClient per eseguire la chiamata all'API. Prima di tutto, è necessario aggiungere l'intestazione Ocp-Apim-Subscription-Key e la chiave di accesso.
using var client = new HttpClient();
client.BaseAddress = new Uri(_uriBase);
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", _accessKey);
Costruire l'URI per la richiesta di ricerca. Formattare il termine di ricerca _searchTerm prima di aggiungerlo alla richiesta.
var response = await client.GetAsync($"?q={Uri.EscapeDataString(_searchTerm)}");
Elaborare il risultato
Se la risposta è stata positiva, è possibile elaborare i dati JSON. Deserializzare la stringa JSON nella classe SearchResult creata in precedenza. Scorrere fino al risultato (se presente) e stamparlo nella console.
if (response.IsSuccessStatusCode)
{
var json = await response.Content.ReadAsStringAsync();
var result = JsonSerializer.Deserialize<SearchResult>(json);
foreach (var video in result.Videos)
{
Console.WriteLine($"Name: {video.Name}");
Console.WriteLine($"ContentUrl: {video.ContentUrl}");
Console.WriteLine();
}
}
Risposta JSON di esempio
Viene restituita una risposta con esito positivo in formato JSON, come illustrato nell'esempio seguente:
{
"_type": "Videos",
"instrumentation": {},
"readLink": "https://api.cognitive.microsoft.com/api/v7/videos/search?q=kittens",
"webSearchUrl": "https://www.bing.com/videos/search?q=kittens",
"totalEstimatedMatches": 1000,
"value": [
{
"webSearchUrl": "https://www.bing.com/videos/search?q=kittens&view=...",
"name": "Top 10 cute kitten videos compilation",
"description": "HELP HOMELESS ANIMALS AND WIN A PRIZE BY CHOOSING...",
"thumbnailUrl": "https://tse4.mm.bing.net/th?id=OVP.n1aE_Oikl4MtzBb...",
"datePublished": "2014-11-12T22:47:36.0000000",
"publisher": [
{
"name": "Fabrikam"
}
],
"creator": {
"name": "Marcus Appel"
},
"isAccessibleForFree": true,
"contentUrl": "https://www.fabrikam.com/watch?v=8HVWitAW-Qg",
"hostPageUrl": "https://www.fabrikam.com/watch?v=8HVWitAW-Qg",
"encodingFormat": "h264",
"hostPageDisplayUrl": "https://www.fabrikam.com/watch?v=8HVWitAW-Qg",
"width": 480,
"height": 360,
"duration": "PT3M52S",
"motionThumbnailUrl": "https://tse4.mm.bing.net/th?id=OM.j4QyJAENJphdZQ_1501386166&pid=Api",
"embedHtml": "<iframe width=\"1280\" height=\"720\" src=\"https://www.fabrikam.com/embed/8HVWitAW-Qg?autoplay=1\" frameborder=\"0\" allowfullscreen></iframe>",
"allowHttpsEmbed": true,
"viewCount": 7513633,
"thumbnail": {
"width": 300,
"height": 168
},
"videoId": "655D98260D012432848F6558260D012432848F",
"allowMobileEmbed": true,
"isSuperfresh": false
},
. . .
],
"nextOffset": 36,
"queryExpansions": [
{
"text": "Kittens Meowing",
"displayText": "Meowing",
"webSearchUrl": "https://www.bing.com/videos/search?q=Kittens+Meowing...",
"searchLink": "https://api.cognitive.microsoft.com/api/v7/videos/search...",
"thumbnail": {
"thumbnailUrl": "https://tse3.mm.bing.net/th?q=Kittens+Meowing&pid..."
}
},
{
"text": "Funny Kittens",
"displayText": "Funny",
"webSearchUrl": "https://www.bing.com/videos/search?q=Funny+Kittens...",
"searchLink": "https://api.cognitive.microsoft.com/api/v7/videos/search...",
"thumbnail": {
"thumbnailUrl": "https://tse3.mm.bing.net/th?q=Funny+Kittens&..."
}
},
. . .
],
"pivotSuggestions": [
{
"pivot": "kittens",
"suggestions": [
{
"text": "Cat",
"displayText": "Cat",
"webSearchUrl": "https://www.bing.com/videos/search?q=Cat...",
"searchLink": "https://api.cognitive.microsoft.com/api/v7/videos/search?...",
"thumbnail": {
"thumbnailUrl": "https://tse3.mm.bing.net/th?q=Cat&pid=Api..."
}
},
{
"text": "Feral Cat",
"displayText": "Feral Cat",
"webSearchUrl": "https://www.bing.com/videos/search?q=Feral+Cat...",
"searchLink": "https://api.cognitive.microsoft.com/api/v7/videos/search...",
"thumbnail": {
"thumbnailUrl": "https://tse3.mm.bing.net/th?q=Feral+Cat&pid=Api&..."
}
}
]
}
],
"relatedSearches": [
{
"text": "Kittens Being Born",
"displayText": "Kittens Being Born",
"webSearchUrl": "https://www.bing.com/videos/search?q=Kittens+Being+Born...",
"searchLink": "https://api.cognitive.microsoft.com/api/v7/videos/search?...",
"thumbnail": {
"thumbnailUrl": "https://tse1.mm.bing.net/th?q=Kittens+Being+Born&pid=..."
}
},
. . .
]
}