Bing Video Arama API'siyle video arama

Makale
06/24/2019

Uyarı

30 Ekim 2020'de Bing Arama API'leri Azure yapay zeka hizmetlerinden Bing Arama Hizmetlerine taşındı. Bu belgeler yalnızca başvuru için sağlanır. Güncelleştirilmiş belgeler için Bing arama API'sinin belgelerine bakın. Bing araması için yeni Azure kaynakları oluşturma yönergeleri için bkz. Azure Market aracılığıyla Bing Arama kaynağı oluşturma.

Bing Video Arama API'si, Bing'in bilişsel haber arama özelliklerini uygulamalarınızla tümleştirmeyi kolaylaştırır. API öncelikle web'den ilgili videoları bulup döndürürken, web'de akıllı ve odaklanmış video alma için çeşitli özellikler sağlar.

Videoları alma

Web'den kullanıcının arama terimiyle ilgili videoları almak için aşağıdaki GET isteğini gönderin:

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

Tüm isteklerin bir sunucudan yapılması gerekir.

Bing API'lerinden birini ilk kez çağırıyorsanız istemci kimliği üst bilgisini eklemeyin. İstemci kimliğini yalnızca önceden bir Bing API'sini çağırdıysanız ve Bing, kullanıcı ve cihaz birleşimi için bir istemci kimliği döndürdüyse dahil edin.

Belirli bir etki alanındaki videoları almak için site: dize işlecini kullanın.

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

Yanıt, Bing'in sorguyla ilişkili olduğunu düşündüğü videoları bir listesini içeren Videos yanıtı içerir. Listedeki her Video nesneyi videonun URL’sini, süresini, boyutlarını, kodlama biçimini ve diğer özniteliklerini içerir. Video nesnesi aynı zamanda video küçük resminin URL'sini ve küçük resmin boyutlarını içerir.

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

Video küçük resimleri

Bing Video Arama API'sinin döndürdiği video küçük resimlerinin tümünü veya bir alt kümesini görüntüleyebilirsiniz. Alt küme görüntülerseniz kullanıcıya kalan videoları görüntüleme seçeneği sunun. Bing API'sinin kullanım ve görüntüleme gereksinimlerinin bir parçası olarak, videoları yanıtta sağlanan sırayla görüntülemeniz gerekir. Küçük resmi yeniden boyutlandırma hakkında bilgi için bkz. Küçük Resimleri Yeniden Boyutlandırma ve Kırpma.

Kullanıcı küçük resmin üzerine geldiğinde videonun küçük resim bir sürümünü oynatmak için motionThumbnailUrl kullanabilirsiniz. Hareket küçük resmini görüntülediğinizde öznitelik belirlediğinizden emin olun.

Küçük resme tıklandığında, videoyu görüntülemek için üç seçenek vardır:

Videoyu konak web sitesinde (örneğin YouTube) görüntülemek için hostPageUrl kullanın
Videoyu Bing video tarayıcısında görüntülemek için webSearchUrl kullanın
Videoyu kendi deneyiminize eklemek için embdedHtml kullanın

Videoyu oynatırken yayımcı ve oluşturucu özniteliklerini kullandığınızdan emin olun.

Video hakkında öngörüler almak için videoId kullanma hakkında daha fazla bilgi için bkz. Video Öngörüleri.

Videoları filtreleme

Video Arama API'si varsayılan olarak sorguyla ilgili tüm videoları döndürür. Yalnızca ücretsiz videolar veya uzunluğu beş dakikayı aşmayan videolar istiyorsanız, aşağıdaki filtre sorgu parametrelerini kullanırsınız:

fiyatlandırma—Videoları fiyatlandırmaya göre filtreleyin (örneğin, ücretsiz olan veya ödemeniz gereken videolar)
çözünürlük—Videoları çözünürlüğe göre filtreleyin (örneğin, 720p veya daha yüksek çözünürlüğe sahip videolar)
videoLength—Videoları video uzunluğuna göre filtreleme (örneğin, beş dakikadan kısa videolar)
freshness—Videoları yaşa göre filtreleme (örneğin, Bing tarafından geçen hafta bulunan videolar)

Belirli bir etki alanındaki videoları almak için sorgu dizesine site: dize işlecini ekleyin.

Not

Sorguya bağlı olarak site: sorgu işlecini kullanmanız halinde safeSearch ayarından bağımsız olarak yanıtta yetişkinlere yönelik içerik bulunabilir. site: işlecini yalnızca sitenin içeriği hakkında bilgi sahibiyseniz ve senaryonuz, yetişkinlere yönelik içeriğin mevcut olma ihtimalini destekliyorsa kullanın.

Aşağıdaki örnekte ContosoSailing.com adresinden 720p veya daha iyi çözünürlüğe sahip ve Bing’in geçen ay içinde bulduğu ücretsiz videoların nasıl alındığı gösterilmektedir.

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

Sorguyu genişletme

Bing özgün aramayı daraltmak için sorguyu genişletebiliyorsa Videos nesnesi queryExpansions alanını içerir. Örneğin, sorgu Boşluk Temizleme ise, genişletilmiş sorgular şunlar olabilir: Boşluk Temizleme Araçları, Sıfırdan Boşluk Temizleme, Boşluk Temizleme Makinesi ve Kolay Boşluk Temizleme.

Aşağıdaki örnekte Boşluk Temizleme için genişletilmiş sorgular gösterilmektedir.

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

queryExpansions alanı Query nesnelerinin listesini içerir. text alanı genişletilmiş sorguyu, displayText alanı ise genişletme terimini içerir. Metin ve küçük resim alanlarını kullanarak genişletilmiş sorgu dizelerini kullanıcıya gösterebilir ve kullanıcının bu genişletilmiş sorgu dizelerinden seçim yapmasını sağlayabilirsiniz. webSearchUrl URL veya searchLink URL kullanarak küçük resmi ve metni tıklanabilir hale getirebilirsiniz. webSearchUrl kullanarak kullanıcıyı Bing arama sonuçlarına gönderebilir veya searchLink ile kendi sonuç sayfanızı sunabilirsiniz.

Sorguyu özetleme

Bing özgün arama sorgusunu parçalara ayırabiliyorsa Videos nesnesi pivotSuggestions alanını içerir. Örneğin, özgün sorgu Boşluk Temizleme ise Bing bunu Boşluk ve Temizleme olmak üzere ikiye bölebilir.

Aşağıdaki örnekte Boşluk Temizleme için öneri özetleri gösterilmektedir.

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

Her bir özet terim için gelen yanıtta önerilen sorguları içeren Query nesnelerinin listesi yer alır. text alanı önerilen sorguyu, displayText alanı ise özgün sorguda özetin yerine kullanılan terimi içerir. Örneğin, Pencere Temizleme.

text ve thumbnail alanlarını kullanarak genişletilmiş sorgu dizelerini kullanıcıya gösterebilir ve kullanıcının bu genişletilmiş sorgu dizelerinden seçim yapmasını sağlayabilirsiniz. webSearchUrl URL veya searchLink URL kullanarak küçük resmi ve metni tıklanabilir hale getirebilirsiniz. webSearchUrl kullanarak kullanıcıyı Bing arama sonuçlarına gönderebilir veya searchLink ile kendi sonuç sayfanızı sunabilirsiniz.

İstekleri azaltma

Saniye başına yapabileceğiniz sorgu sayısı (QPS), hizmete ve aboneliğinizin türüne göre belirlenir. Uygulamanızın, kotanızın sınırları içinde kalmak için gereken mantığı içerdiğinden emin olun. QPS sınırına ulaşılırsa veya bu sınır aşılırsa istek başarısız olur ve HTTP 429 durum kodu döndürülür. Yanıt, başka bir istek göndermeden önce beklemeniz gereken süreyi gösteren Retry-After üst bilgisini içerir.

Hizmet reddi ile azaltma karşılaştırması

Hizmette, hizmet reddi (DoS) saldırısıyla QPS ihlali arasında bir ayrım yapılır. Hizmet bir DoS saldırısı olduğundan şüphelenirse istek başarılıyla sonuçlanır (HTTP durum kodu 200 TAMAM). Ancak, yanıt gövdesi boş olur.

Aracılığıyla paylaş