Invio di richieste di ricerca all'API Ricerca video Bing
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.
Questo articolo descrive i parametri e gli attributi delle richieste inviate all'API Ricerca video Bing, nonché l'oggetto risposta JSON restituito.
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.
Suggerire termini di ricerca con l'API Suggerimenti automatici Bing
Se si fornisce una casella di ricerca in cui l'utente immette il termine di ricerca, usare l'API Suggerimenti automatici Bing per migliorare l'esperienza. Mentre l'utente digita, l'API restituisce le stringhe di query suggerite, in base ai termini di ricerca parziali.
Dopo che l'utente ha immesso il termine di ricerca, l'URL lo codifica prima di impostare il parametro di query q. Se ad esempio l'utente immette sailing dinghies, impostare q su sailing+dinghies o sailing%20dinghies.
Invio di una richiesta
Per ottenere video come risultati della ricerca, è consigliabile inviare una richiesta GET all'endpoint seguente:
https://api.cognitive.microsoft.com/bing/v7.0/videos/search
La richiesta deve usare il protocollo HTTPS.
È consigliabile che tutte le richieste abbiano origine da un server. La distribuzione della chiave come parte di un'applicazione client consente a terze parti dannose di accedervi più facilmente. L'esecuzione delle chiamate da un server fornisce anche un singolo punto di aggiornamento per le future versioni dell'API.
La richiesta deve specificare il parametro q query, che contiene il termine di ricerca dell'utente. Nonostante sia facoltativo, la richiesta dovrebbe anche specificare il parametro di query mkt, che identifica il mercato da cui devono provenire i risultati. Per un elenco di parametri di query facoltativi come pricing, vedere Query Parameters (Parametri di query). Tutti i valori dei parametri di query devono essere codificati in URL.
La richiesta deve specificare l'intestazione Ocp-Apim-Subscription-Key. Nonostante sia facoltativo, è consigliabile specificare anche le intestazioni seguenti:
Le intestazioni relative a IP client e posizione sono importanti per la restituzione di contenuto con riconoscimento della posizione.
Per un elenco di tutte le intestazioni di richiesta e risposta, vedere Headers (Intestazioni).
Richiesta di ricerca di esempio
Di seguito è illustrata una richiesta di ricerca che include tutte le intestazioni e i parametri di query suggeriti. Se è la prima volta che si chiama un'API Bing, non includere l'intestazione dell'ID client. Includere l'ID client solo se in precedenza è già stata chiamata un'API Bing e Bing ha restituito un ID client per la combinazione utente e dispositivo.
GET https://api.cognitive.microsoft.com/bing/v7.0/videos/search?q=sailing+dinghies&mkt=en-us HTTP/1.1
Ocp-Apim-Subscription-Key: 123456789ABCDE
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)
X-Search-ClientIP: 999.999.999.999
X-Search-Location: lat:47.60357;long:-122.3295;re:100
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>
Host: api.cognitive.microsoft.com
Risposta JSON di esempio
Di seguito è riportata la risposta alla richiesta precedente. L'esempio mostra anche le intestazioni di risposta specifiche di Bing.
Nota
Poiché i formati e i parametri degli URL sono soggetti a modifica senza preavviso, usare gli URL così come sono. Non acquisire dipendenze da formati o parametri degli URL se non diversamente specificato.
BingAPIs-TraceId: 76DD2C2549B94F9FB55B4BD6FEB6AC
X-MSEdge-ClientID: 1C3352B306E669780D58D607B96869
BingAPIs-Market: en-US
{
"_type" : "Videos",
"webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=81EF7545D5694...",
"totalEstimatedMatches" : 1000,
"value" : [
{
"name" : "How to sail - What to Wear for Dinghy Sailing",
"description" : "An informative video on what to wear when...",
"webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=81EF7545D56...",
"thumbnailUrl" : "https:\/\/tse4.mm.bing.net\/th?id=OVP.DYWCvh...",
"datePublished" : "2014-03-04T11:51:53",
"publisher" : [
{
"name" : "Fabrikam"
}
],
"creator" : {
"name" : "Marcus Appel"
},
"contentUrl" : "https:\/\/www.fabrikam.com\/watch?v=vzmPjHZ--g",
"hostPageUrl" : "https:\/\/www.bing.com\/cr?IG=81EF7545D56944...",
"encodingFormat" : "h264",
"hostPageDisplayUrl" : "https:\/\/www.fabrikam.com\/watch?v=vzmPjBZ--g",
"width" : 1280,
"height" : 720,
"duration" : "PT2M47S",
"motionThumbnailUrl" : "https:\/\/tse3.mm.bing.net\/th?id=OM.Y6...",
"embedHtml" : "<iframe width=\"1280\" height=\"720\" src=\"https:...><\/iframe>",
"allowHttpsEmbed" : true,
"viewCount" : 8743,
"thumbnail" : {
"width" : 300,
"height" : 168
},
"videoId" : "6DB795E11A6E3CBAAD636DB795E11E3CBAAD63",
"allowMobileEmbed" : true,
"isSuperfresh" : false
},
. . .
],
"nextOffset" : 0,
"pivotSuggestions" : [
{
"pivot" : "sailing",
"suggestions" : []
},
{
"pivot" : "dinghies",
"suggestions" : [
{
"text" : "Sailing Cruising",
"displayText" : "Cruising",
"webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=81EF754...",
"searchLink" : "https:\/\/api.cognitive.microsoft.com...",
"thumbnail" : {
"thumbnailUrl" : "https:\/\/tse4.mm.bing.net\/th?q=Sailing..."
}
},
. . .
]
}
]
}
Passaggi successivi
Provare l'API. Passare a Video Search API Testing Console (Console di test dell'API Ricerca video Bing).
Per informazioni dettagliate sull'utilizzo degli oggetti risposta, vedere Searching the Web for Videos (Ricerca di video sul Web).
Per informazioni su come ottenere dati dettagliati su un video, ad esempio ricerche correlate, vedere Ottenere informazioni dettagliate sui video.
Per informazioni dettagliate sui video di tendenza nei social network, vedere Get Trending Videos (Ottenere video di tendenza).