Cercare video con l'API Ricerca video Bing

Articolo
06/24/2019

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.

L'API Ricerca video Bing facilita l'integrazione delle funzionalità di ricerca notizie cognitive di Bing nelle applicazioni. Oltre a trovare e restituire principalmente i video pertinenti dal Web, l'API offre diverse funzionalità per il recupero intelligente e mirato dei video sul Web.

Come ottenere video

Per ottenere dal Web video relativi al termine di ricerca dell'utente, inviare la seguente richiesta GET:

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

Tutte le richieste devono essere eseguite da un server.

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.

Per ottenere video da un dominio specifico, usare il sito: operatore query.

GET https://api.cognitive.microsoft.com/bing/v7.0/videos/search?q=sailing+dinghies+site:contososailing.com&mkt=en-us HTTP/1.1

Il risultato contiene una risposta Video che riporta un elenco di video che Bing ha ritenuto pertinenti alla query. Ogni oggetto video nell'elenco include l'URL, la durata, le dimensioni e il formato di codifica del video, tra gli altri attributi. L'oggetto video include anche l'URL di un'anteprima del video e le dimensioni dell'anteprima.

{
    "_type" : "Videos",
    "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=81EF7545...",
    "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=81EF7...",
            "thumbnailUrl" : "https:\/\/tse4.mm.bing.net\/th?id=OVP.DYW...",
            "datePublished" : "2014-03-04T11:51:53",
            "publisher" : [
                {
                    "name" : "Fabrikam"
                }
            ],
            "creator" : 
            {
                "name" : "Marcus Appel"
            },
            "contentUrl" : "https:\/\/www.fabrikam.com\/watch?v=vzmPjZ--g",
            "hostPageUrl" : "https:\/\/www.bing.com\/cr?IG=81EF7545D569...",
            "encodingFormat" : "h264",
            "hostPageDisplayUrl" : "https:\/\/www.fabrikam.com\/watch?v=vzmPjZ--g",
            "width" : 1280,
            "height" : 720,
            "duration" : "PT2M47S",
            "motionThumbnailUrl" : "https:\/\/tse3.mm.bing.net\/th?id=OM.Y62...",
            "embedHtml" : "<iframe width=\"1280\" height=\"720\" src=\"https:...><\/iframe>",
            "allowHttpsEmbed" : true,
            "viewCount" : 8743,
            "thumbnail" : 
            {
                "width" : 300,
                "height" : 168
            },
            "videoId" : "6DB795E11A6E3CBAAD636DB795E113CBAAD63",
            "allowMobileEmbed" : true,
            "isSuperfresh" : false
        },
        ...
    ],
    "queryExpansions" : [...],
    "nextOffsetAddCount" : 0,
    "pivotSuggestions" : [...]
}

Anteprime video

È possibile visualizzare tutte le anteprime video restituite dall'API Ricerca video Bing oppure solo un sottoinsieme. Se l'utente visualizza un subset, avrà la possibilità di vedere i video rimanenti. Come parte dei requisiti per l'uso e la visualizzazione delle API Bing, è necessario visualizzare i video nell'ordine indicato nella risposta. Per informazioni sul ridimensionamento dell'anteprima, vedere Resizing and Cropping Thumbnails (Ridimensionamento e ritaglio di anteprime).

L'utente, passando con il mouse sull'anteprima, potrà usare motionThumbnailUrl per riprodurre una versione di anteprima del video. Assicurarsi di assegnare un attributo all'anteprima animata quando la si visualizza.

Quando si fa clic su un'anteprima, sono disponibili tre opzioni per la visualizzazione del video:

Usare hostPageUrl per visualizzare il video sul sito Web host (ad esempio YouTube)
Usare webSearchUrl per visualizzare il video nel browser video di Bing
Usare embdedHtml per incorporare il video nell'esperienza dell'utente

Assicurarsi di usare l'editore e l'autore per attribuire il video durante la riproduzione.

Per informazioni dettagliate sull'uso di videoId, consultare la sezione Informazioni dettagliate sui video.

Come filtrare i video

Per impostazione predefinita, l'API Ricerca video riporta tutti i video pertinenti alla query. Se si ricercano solo video gratuiti o video di lunghezza inferiore a cinque minuti, è possibile utilizzare i seguenti parametri di filtro per la query:

prezzi: Filtrare i video in base ai prezzi (ad esempio, video gratuiti o che è necessario pagare)
risoluzione: Filtrare i video in base alla risoluzione (ad esempio, i video con una risoluzione di 720p o superiore)
videoLength: Filtrare i video in base alla lunghezza del video (ad esempio, i video che sono inferiori a cinque minuti di lunghezza)
freschezza: Filtrare i video in base all'età (ad esempio i video individuati da Bing nella settimana precedente)

Per ottenere risultati di ricerca da un dominio specifico, includere il sito: dell'operatore query, nella stringa di query.

Nota

A seconda della query, se si usa site:l'operatore query è possibile che i risultati contengano contenuti per adulti, indipendentemente dall'impostazione Ricerca sicura. È consigliabile usare site: solo se si conosce il contenuto del sito e lo scenario prevede la possibilità di contenuto per adulti.

Nel seguente esempio viene illustrato come ottenere video gratuiti da ContosoSailing.com, con una risoluzione pari a 720p o superiore e che sono stati individuati da Bing nell'ultimo mese.

GET https://api.cognitive.microsoft.com/bing/v7.0/videos/search?q=sailing+dinghies+site:contososailing.com&pricing=free&freshness=month&resolution=720p&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-MSEdge-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

Espansione della query

Se Bing può espandere la query per circoscrivere la ricerca originale, significa che l'oggetto Video contiene il campo queryExpansions. Ad esempio, se la query fosse Pulizia dei margini, le query espanse potrebbero essere: Strumenti di pulizia dei margini, pulizia dei margini dal suolo, Computer di pulizia dei margini e pulizia dei margini facile.

Il seguente esempio mostra le query espanse per Pulizia dei margini.

{
    "_type" : "Videos",
    "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=B52FBC5...",
    "totalEstimatedMatches" : 1000,
    "value" : [...],
    "nextOffsetAddCount" : 4,
    "queryExpansions" : [
        {
            "text" : "Gutter Cleaning Tools",
            "displayText" : "Tools",
            "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=B52FB....",
            "searchLink" : "https:\/\/api.cognitive.microsoft.com\/api\/v5...",
            "thumbnail" : {
                "thumbnailUrl" : "https:\/\/tse4.mm.bing.net\/th?q=Gutter..."
            }
        },
        ...
    ]
    "pivotSuggestions" : [...],
}

Il campo queryExpansions contiene un elenco di oggetto Query. Il campo text contiene la query espansa e il campo displayText contiene il termine di espansione. È possibile usare i campi testo e anteprima per mostrare all'utente le stringhe di query espanse, qualora la stringa di query espansa sia effettivamente ciò che si sta cercando. Rendere selezionabile l'anteprima e il testo con l'URL webSearchUrl o con l'URL searchLink. Usare webSearchUrl per inviare l'utente ai risultati della ricerca di Bing o searchLink se si fornisce la propria pagina di risultati.

Trasformazione tramite Pivot della query

Se Bing può segmentare la query di ricerca originale, significa che l'oggetto Video contiene il campo pivotSuggestions. Se ad esempio la query originale fosse Pulizia dei margini, Bing potrebbe segmentare la query in Pulizia e Margini.

Il seguente esempio mostra i suggerimenti di pivot per Pulizia dei margini.

{
    "_type" : "Videos",
    "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=B52FBC...",
    "totalEstimatedMatches" : 1000,
    "value" : [...],
    "nextOffsetAddCount" : 0,
    "queryExpansions" : [...],
    "pivotSuggestions" : [
        {
            "pivot" : "cleaning",
            "suggestions" : [
                {
                    "text" : "Gutter Repair",
                    "displayText" : "Repair",
                    "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=B52...",
                    "searchLink" : "https:\/\/api.cognitive.microsoft.com\/api\/v5\/videos...",
                    "thumbnail" : {
                        "thumbnailUrl" : "https:\/\/tse3.mm.bing.net\/th?q=Gutter..."
                    }
                },
                ...
            ]
        },
        {
            "pivot" : "gutters",
            "suggestions" : [
                {
                    "text" : "Window Cleaning",
                    "displayText" : "Window",
                    "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=B52FBC59...",
                    "searchLink" : "https:\/\/api.cognitive.microsoft.com\/api\/v5...",
                    "thumbnail" : {
                        "thumbnailUrl" : "https:\/\/tse2.mm.bing.net\/th?q=Window..."
                    }
                },
                ...
            ]
        }
    ]
}

Per ogni pivot, la risposta contiene un elenco di oggetti Query contenenti le query suggerite. Il campo text contiene la query suggerita e il campo displayText contiene il termine che sostituisce il pivot nella query originale, Ad esempio, pulizia delle finestre.

È possibile usare i campi text e thumbnail per mostrare all'utente le stringhe di query espanse qualora la stringa di query espansa sia effettivamente ciò che sta cercando. Rendere selezionabile l'anteprima e il testo con l'URL webSearchUrl o con l'URL searchLink. Usare webSearchUrl per inviare l'utente ai risultati della ricerca di Bing o searchLink se si fornisce la propria pagina di risultati.

Limitazione delle richieste

Il tipo di servizio e di sottoscrizione determina il numero di query al secondo che è possibile effettuare. Assicurarsi che l'applicazione includa la logica necessaria per rimanere entro la quota. Se il limite di query al secondo viene raggiunto o superato, la richiesta avrà esito negativo e verrà restituito un codice di stato HTTP 429. La risposta include l'intestazione Retry-After, che indica il tempo di attesa necessario prima dell'invio di un'altra richiesta.

Confronto tra Denial of Service (DoS) e limitazione

Il servizio distingue tra un attacco Denial of Service e una violazione del limite di query al secondo. Se il servizio sospetta un attacco Denial of Service, la richiesta avrà esito positivo, con codice di stato HTTP 200 OK. Il corpo della risposta sarà tuttavia vuoto.

Condividi tramite