Videók keresése a Bing Video Search API-val
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.