Hledání videí pomocí rozhraní API Bingu pro vyhledávání videí

Článek
06/24/2019

Upozornění

30. října 2020 se rozhraní API Vyhledávání Bingu přesunula ze služeb Azure AI na Vyhledávání Bingu Services. Tato dokumentace je k dispozici pouze pro referenci. Aktualizovanou dokumentaci najdete v dokumentaci k rozhraní API Bingu pro vyhledávání. Pokyny k vytváření nových prostředků Azure pro vyhledávání Bingu najdete v tématu Vytvoření prostředku Vyhledávání Bingu prostřednictvím Azure Marketplace.

Rozhraní API Bingu pro vyhledávání videí usnadňuje integraci funkcí kognitivního vyhledávání zpráv Bingu do vašich aplikací. I když rozhraní API primárně vyhledává a vrací relevantní videa z webu, poskytuje několik funkcí pro inteligentní a cílené načítání videí na webu.

Získávání videí

Pokud chcete z webu získat videa související s hledaným termínem uživatele, odešlete následující požadavek 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

Všechny požadavky se musí provádět ze serveru.

Pokud voláte některé z rozhraní API Bingu poprvé, nezahrnujte do volání hlavičku ID klienta. ID klienta zahrňte pouze v případě, že jste již dříve volali rozhraní API Bingu a Bing vrátil ID klienta pro příslušnou kombinaci uživatele a zařízení.

Pokud chcete získat videa z konkrétní domény, použijte operátor dotazu site:.

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

Odpověď obsahuje objekt Videos se seznamem videí, které Bing vyhodnotil jako relevantní pro daný dotaz. Každý objekt Video v seznamu obsahuje mimo další atributy i adresu URL videa, dobu jeho trvání, rozměry a formát kódování. Objekt videa obsahuje také adresu URL miniatury videa a její rozměry.

{
    "_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" : [...]
}

Miniatury videí

Můžete zobrazit všechny miniatury videa vrácené rozhraním API Bingu pro vyhledávání videí nebo jejich podmnožinu. Pokud zobrazíte podmnožinu, poskytněte uživateli možnost zobrazit zbývající videa. v rámci požadavků na použití a zobrazení rozhraní API Bingu musíte videa zobrazit v pořadí uvedeném v odpovědi. Informace o změně velikosti miniatury najdete v tématu Změna velikosti a oříznutí miniatur.

Pokud uživatel najede myší na miniaturu, může pomocí motionThumbnailUrl spustit přehrávání miniatury videa. Ujistěte se, že je při zobrazení přiřazená filmová miniatura.

Když kliknete na miniaturu, můžete video zobrazit třemi způsoby:

Použitím adresy hostPageUrl zobrazíte video na webu hostitele (například YouTube)
Použitím adresy webSearchUrl zobrazíte video v prohlížeči videa Bingu
Použitím adresy embdedHtml můžete vložit video do vlastního prostředí

Ujistěte se, že při přehrávání k videu přiřadíte atributy creator a publisher.

Podrobné informace o použití videoId k získání přehledu o videu naleznete v tématu Přehledy z videí.

Filtrování videí

Ve výchozím nastavení vrací rozhraní API Bingu pro vyhledávání videí všechna videa, která jsou pro dotaz relevantní. Pokud chcete zobrazit pouze videa zdarma nebo videa kratší než pět minut, můžete použít následující parametry dotazu filtru:

ceny – filtrujte videa podle cen (například videa, která jsou zdarma nebo za která musíte platit).
resolution – filtruje videa podle rozlišení (například videa s rozlišením 720p nebo vyšším).
videoLength – filtruje videa podle délky videa (například videa, která jsou kratší než pět minut).
aktuálnost – filtruje videa podle věku (například videa zjištěná Bingem v minulém týdnu)

Pokud chcete získat videa z konkrétní domény, použijte v řetězci dotazu operátor site:.

Poznámka

Pokud použijete operátor site:, v závislosti na dotazu existuje jistá pravděpodobnost, že odpověď bude obsahovat obsah pro dospělé, a to bez ohledu na nastavení safeSearch. Operátor site: byste měli používat, pouze pokud znáte obsah příslušného webu a váš scénář podporuje možnost zobrazení obsahu pro dospělé.

Následující příklad ukazuje, jak získat bezplatná videa z webu ContosoSailing.com, která mají rozlišení obrazovky 720p nebo vyšší a Bing je našel během posledního měsíce.

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

Rozšíření dotazu

Pokud Bing dokáže rozšířením dotazu zúžit původní hledání, bude objekt Videos obsahovat pole queryExpansions. Například, pokud byl původní dotaz čištění okapů, rozšířené dotazy můžou být: nástroje na čištění okapů, čištění okapů ze země, Stroj na čištění okapů a snadné čištění okapů.

Následující příklad ukazuje rozšířené dotazy pro dotaz čištění okapů.

{
    "_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" : [...],
}

Pole queryExpansions obsahuje seznam objektů Query. Pole text obsahuje rozšířený dotaz a pole displayText obsahuje termín rozšíření. Pomocí polí text a miniatura můžete uživateli zobrazit rozšířené řetězce dotazů pro případ, že ve skutečnosti hledá právě rozšířený řetězec dotazu. Pomocí adresy URL webSearchUrl nebo searchLink můžete umožnit kliknutí na miniaturu a text. Pomocí hodnoty webSearchUrl můžete uživatele přesměrovat na výsledky hledání Bingu. Případně můžete použít hodnotu searchLink, pokud máte vlastní stránku výsledků.

Rozdělení dotazu na pivoty

Pokud Bing dokáže segmentovat původní vyhledávací dotaz, bude objekt Videos obsahovat pole pivotSuggestions. Pokud byl původní dotaz například čištění okapů, může ho Bing segmentovat na čištění a okapů.

Následující příklad ukazuje návrhy pivotů pro dotaz čištění okapů.

{
    "_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..."
                    }
                },
                ...
            ]
        }
    ]
}

Pro každý pivot obsahuje odpověď seznam objektů Query, které obsahují navrhované dotazy. Pole text obsahuje navrhovaný dotaz a pole displayText obsahuje termín, který nahradí pivot v původním dotazu. Například čištění oken.

Pomocí polí text a thumbnail můžete uživateli zobrazit rozšířené řetězce dotazů pro případ, že ve skutečnosti hledá právě rozšířený řetězec dotazu. Pomocí adresy URL webSearchUrl nebo searchLink můžete umožnit kliknutí na miniaturu a text. Pomocí hodnoty webSearchUrl můžete uživatele přesměrovat na výsledky hledání Bingu. Případně můžete použít hodnotu searchLink, pokud máte vlastní stránku výsledků.

Omezování požadavků

Služba a typ vašeho předplatného určuje počet dotazů, které můžete provést za sekundu (QPS). Ujistěte se, že vaše aplikace obsahuje logiku potřebnou k nepřekročení vaší kvóty. Při dosažení nebo překročení limitu QPS požadavek selže a vrátí se stavový kód HTTP 429. Odpověď zahrnuje hlavičku Retry-After, která označuje, jak dlouho je nutné počkat před odesláním dalšího požadavku.

Odepření služby a omezování

Služba rozlišuje mezi útokem s cílem odepření služby (DoS) a porušením QPS. Pokud služba má podezření na útok DoS, požadavek bude úspěšný (stavový kód HTTP je 200 OK). Text odpovědi však bude prázdný.

Sdílet prostřednictvím