Videók keresése a Bing Video Search API-val

Cikk
06/24/2019

Figyelmeztetés

2020. október 30-án a Bing Search API-k átkerültek az Azure AI-szolgáltatásokból a Bing Search Servicesbe. Ez a dokumentáció csak referenciaként szolgál. A frissített dokumentációt a Bing search API dokumentációjában találja. Az új Azure-erőforrások Bing-kereséshez való létrehozásával kapcsolatos útmutatásért lásd: Bing Search-erőforrás létrehozása a Azure Marketplace keresztül.

A Bing Video Search API megkönnyíti a Bing kognitív hírkeresési funkcióinak integrálását az alkalmazásokba. Bár az API elsősorban a webről keres és ad vissza releváns videókat, számos funkciót biztosít az intelligens és célzott videólekéréshez a weben.

Videók lekérése

A felhasználó keresőkifejezéséhez kapcsolódó, az interneten megtalálható videók lekéréséhez küldje el a következő GET kérést:

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

Minden kérést egy kiszolgálóról kell elküldeni.

Ha első alkalommal hívja meg bármelyik Bing API-t, ne használja az ügyfél-azonosító fejlécét. Csak akkor használja az ügyfél-azonosítót, ha korábban már meghívott egy Bing API-t, és visszakapott egy ügyfél-azonosítót a felhasználó és az eszköz kombinációjához.

Ha egy konkrét tartományban található videókat szeretne lekérni, használja a site: lekérdezési operátort.

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

A válasz tartalmaz egy Videos választ, amely azoknak a videóknak a listáját tartalmazza, amelyeket a Bing a lekérdezéshez kapcsolódónak ítélt. A listában minden egyes Video objektum tartalmazza többek között a videó URL-címét, hosszát, méreteit és kódolási formátumát. A videóobjektum a videó miniatűrjének URL-címét, illetve a miniatűr méreteit is tartalmazza.

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

Videó miniatűrjei

A Bing Video Search API által visszaadott videóminiatűrök mindegyikét vagy egy részhalmazát megjelenítheti. Ha csak a miniatűrök egy részét jeleníti meg, biztosítson lehetőséget a felhasználónak a többi videó megtekintésére. A Bing API használati és megjelenítési követelményeinek részeként a videókat a válaszban megadott sorrendben kell megjelenítenie. A miniatűrök átméretezésével kapcsolatos információkért lásd a miniatűrök átméretezésével és körülvágásával foglalkozó szakaszt.

A motionThumbnailUrl használatával beállíthatja, hogy ha a felhasználó a miniatűr fölé viszi a mutatót, akkor elinduljon a videó miniatűr verziójának lejátszása. Ügyeljen arra, hogy megjelenítse a mozgó miniatűr forrását.

Ha egy miniatűrre kattint, három lehetőség van a videó megtekintésére:

hostPageUrl használata esetén a videó az eredeti webhelyen (például a YouTube-on) tekinthető meg;
webSearchUrl használata esetén a videó a Bing videóböngészőjében tekinthető meg;
embdedHtml használata esetén a videót saját felületére ágyazza be.

Ügyeljen arra, hogy lejátszáskor a videóban megjelenítse annak közzétevőjét és létrehozóját.

A videoId a videóhoz kapcsolódó információk beszerzésére vonatkozó használatáról bővebben a videóelemzésekkel foglalkozó részben olvashat.

Videók szűrése

Alapértelmezés szerint a Video Search API a lekérdezéshez kapcsolódó összes videót visszaadja. Ha csak ingyenes vagy öt percnél rövidebb videókat szeretne visszakapni, a következő szűrőlekérdezési paramétereket használhatja:

díjszabás – Videók szűrése díjszabás szerint (például ingyenes vagy fizetős videók)
felbontás – Videók szűrése felbontás szerint (például 720p vagy nagyobb felbontású videók)
videoLength – Videók szűrése videóhossz szerint (például öt percnél rövidebb videók)
frissesség – Videók szűrése kor szerint (például a Bing által az elmúlt héten felfedezett videók)

Ha egy konkrét tartományban található videókat szeretne lekérni, foglalja bele a site: lekérdezési operátort a lekérdezési sztringbe.

Megjegyzés

A lekérdezéstől függően, ha a site: lekérdezési operátort használja, előfordulhat, hogy a válasz a safeSearch beállítás ellenére is felnőtteknek szóló tartalmakat ad vissza. Csak akkor használja a site: operátort, ha ismeri a webhely tartalmát, és a felnőtteknek szóló tartalmak megjelenítése nem okoz problémát.

A következő példa azt mutatja be, hogyan kérhet le olyan ingyenes videókat a ContosoSailing.com webhelyről, amelyek 720p vagy nagyobb felbontással rendelkeznek, és amelyeket a Bing az elmúlt hónapban fedezett fel.

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

A lekérdezés bővítése

Ha a Bing ki tudja bővíteni a lekérdezést az eredeti keresés szűkítéséhez, a Videos objektumban szerepelni fog a queryExpansions mező. Ha például az eredeti lekérdezés a Cleaning Gutters volt, a bővített lekérdezések a következők lehetnek: Gutter Cleaning Tools, Cleaning Gutters From the Ground, Gutter Cleaning Machine és Easy Gutter Cleaning.

Az alábbi példában a Cleaning Gutters bővített lekérdezései láthatók.

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

A queryExpansions mező a Query objektumok listáját tartalmazza. A text mezőben a bővített lekérdezés, a displayText mezőben pedig a bővítési kifejezés található. A szöveg és a miniatűr mezőben megjelenítheti a bővített lekérdezési sztringeket arra az esetre, ha a felhasználó valójában az egyik bővített lekérdezési sztringet keresné. A miniatűrt és a szöveget a webSearchUrl URL vagy a searchLink URL használatával kattinthatóvá teheti. Akkor használja a webSearchUrl lehetőséget, ha a felhasználót a Bing keresési találatait szeretné küldeni, a searchLink lehetőséget pedig akkor, ha saját eredményoldalt használ.

A lekérdezés szegmentálása

Ha a Bing szegmensekre tudja bontani az eredeti keresési lekérdezést, a Videos objektumban szerepelni fog a pivotSuggestions mező. Ha például az eredeti lekérdezés a Cleaning Gutters volt, a Bing a kifejezést Cleaning és Gutters részekre bonthatja.

Az alábbi példában a Cleaning Gutters keresési kifejezés szegmentálási javaslatai láthatók.

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

A válasz minden szegmenshez kínál olyan Query objektumokat, amelyek a javasolt lekérdezéseket tartalmazzák. A text mező a javasolt lekérdezést, a displayText mező pedig az eredeti lekérdezésben a szegmenst lecserélő kifejezést tartalmazza. Például: Window Cleaning.

A text és a thumbnail mezőben megjelenítheti a bővített lekérdezési sztringeket arra az esetre, ha a felhasználó valójában az egyik bővített lekérdezési sztringet keresné. A miniatűrt és a szöveget a webSearchUrl URL vagy a searchLink URL használatával kattinthatóvá teheti. Akkor használja a webSearchUrl lehetőséget, ha a felhasználót a Bing keresési találatait szeretné küldeni, a searchLink lehetőséget pedig akkor, ha saját eredményoldalt használ.

Kérelmek szabályozása

A szolgáltatás és az előfizetés típusa határozza meg a másodpercenként futtatható lekérdezések számát (QPS). Mindenképpen gondoskodjon arról, hogy az alkalmazás tartalmazza a kvótán belül maradáshoz szükséges logikát. Ha eléri vagy túllépi a QPS határértékét, a kérés meghiúsul, és a rendszer HTTP 429-es állapotkódot ad vissza. A válasz a Retry-After fejlécet is tartalmazza, amely azt adja meg, hogy mennyi ideig kell várnia egy újabb kérés elküldése előtt.

Szolgáltatásmegtagadás kontra szabályozás

A szolgáltatás különbséget tesz a szolgáltatásmegtagadásos (DoS-) támadások és a QPS-eltérések között. Ha DoS-támadást feltételez, a kérés sikeres lesz (200 OK HTTP-állapotkóddal). A választörzs azonban üresen marad.

Megosztás a következőn keresztül: