Procurar vídeos com a API de Pesquisa de Vídeos do Bing

  • Artigo

Aviso

A 30 de outubro de 2020, as APIs de Pesquisa do Bing passaram dos serviços de IA do Azure para os Serviços Pesquisa do Bing. Esta documentação é fornecida apenas para referência. Para obter documentação atualizada, veja a documentação da API de pesquisa do Bing. Para obter instruções sobre como criar novos recursos do Azure para a pesquisa do Bing, veja Criar um recurso de Pesquisa do Bing através do Azure Marketplace.

A API de Pesquisa de Vídeos do Bing facilita a integração das capacidades de pesquisa de notícias cognitivas do Bing nas suas aplicações. Embora a API encontre e devolva principalmente vídeos relevantes da Web, fornece várias funcionalidades para obtenção de vídeo inteligente e focada na Web.

Obter vídeos

Para obter vídeos relacionados com o termo de pesquisa do utilizador a partir da Web, envie o seguinte pedido 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

Todos os pedidos têm de ser feitos a partir de um servidor.

Se for a primeira vez que está a chamar qualquer uma das APIs do Bing, não inclua o cabeçalho de ID de cliente. Inclua apenas o ID de cliente se tiver chamado anteriormente uma API do Bing e o Bing tiver devolvido um ID de cliente para o utilizador e a combinação de dispositivo.

Para obter vídeos de um domínio específico, utilize o operador de consulta site:.

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

A resposta contém uma resposta Vídeos que contém uma lista de vídeos que o Bing considerou relevantes para a consulta. Cada objeto de Vídeo na lista inclui o URL, a duração, as dimensões e o formato de codificação do vídeo, entre outros atributos. O objeto de vídeo também inclui o URL de uma miniatura do vídeo e as dimensões da miniatura.

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

Miniaturas de vídeo

Pode apresentar todas ou um subconjunto das miniaturas de vídeo devolvidas pela API de Pesquisa de Vídeos do Bing. Se for apresentado um subconjunto, dê ao utilizador uma opção para ver os vídeos restantes. como parte dos requisitos de utilização e apresentação da API do Bing, tem de apresentar os vídeos pela ordem indicada na resposta. Para obter informações sobre o redimensionamento da miniatura, veja Redimensionar e Recortar Miniaturas.

À medida que o utilizador coloca o cursor sobre a miniatura, pode utilizar motionThumbnailUrl para reproduzir uma versão em miniatura do vídeo. Certifique-se de que adiciona um atributo à miniatura de movimento quando a apresentar.

Quando uma miniatura é clicada, existem três opções para ver o vídeo:

  • Utilize hostPageUrl para ver o vídeo no site anfitrião (por exemplo, o YouTube)
  • Utilize webSearchUrl para ver o vídeo no browser de vídeos do Bing
  • Utilize embdedHtml para incorporar o vídeo na sua própria experiência

Certifique-se de que utiliza o editor e criador para adicionar um atributo ao vídeo quando o reproduzir.

Para obter detalhes sobre como utilizar o videoId para obter informações sobre o vídeo, veja Informações de Vídeo.

Filtrar vídeos

Por predefinição, a API de Pesquisa de Vídeos devolve todos os vídeos que são relevantes para a consulta. Se quiser apenas vídeos gratuitos ou com menos de cinco minutos de duração, utilize os seguintes parâmetros de consulta de filtro:

  • preços — Filtre vídeos por preços (por exemplo, vídeos gratuitos ou que tem de pagar)
  • resolução — filtrar vídeos por resolução (por exemplo, vídeos com uma resolução de 720p ou superior)
  • videoLength — filtrar vídeos por comprimento de vídeo (por exemplo, vídeos com menos de cinco minutos de comprimento)
  • freshness — Filtrar vídeos por idade (por exemplo, vídeos detetados pelo Bing na semana passada)

Para obter vídeos de um domínio específico, inclua o operador de consulta site: na cadeia de consulta.

Nota

Consoante a consulta, se utilizar o operador site:, existe a possibilidade de a resposta incluir conteúdo para adultos, independentemente da definição safeSearch. Deve utilizar site: apenas se tiver conhecimento do conteúdo do site e se o seu cenário suportar a possibilidade de conteúdo para adultos.

O exemplo seguinte mostra como obter vídeos gratuitos de ContosoSailing.com que tenham uma resolução de 720p ou superior e que o Bing tenha descoberto no mês anterior.

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

Expandir a consulta

Se o Bing conseguir expandir a consulta para restringir a pesquisa original, o objeto Vídeos irá conter o campo queryExpansions. Por exemplo, se a consulta tiver sido Limpeza de Algeroz, as consultas expandidas poderão ser: Ferramentas de Limpeza de Algerozes, Limpeza de Algerozes a Partir do Chão, Máquina de Limpeza de Algerozes e Fácil Limpeza de Algerozes.

O exemplo seguinte mostra as consultas expandidas para Limpeza de Algerozes.

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

O campo queryExpansions contém uma lista de objetos de Consulta. O campo text contém a consulta expandida e o campo displayText contém o termo de expansão. Pode utilizar os campos text (texto) e thumbnail (miniatura) para apresentar as cadeias de consulta expandidas ao utilizador no caso de a cadeia de consulta expandida ser realmente aquilo que procura. Torne a miniatura e o texto clicáveis com o URL webSearchUrl ou o URL searchLink. Utilize webSearchUrl para encaminhar o utilizador para os resultados de pesquisa do Bing ou searchLink se fornecer a sua própria página de resultados.

Dinamizar a consulta

Se o Bing puder segmentar a consulta de pesquisa original, o objeto Vídeos contém o campo pivotSuggestions. Por exemplo, se a consulta original era Limpeza de Algerozes, o Bing poderá segmentar a consulta em Limpeza e Algerozes.

O exemplo seguinte mostra as sugestões de dinamização para Limpeza de Algerozes.

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

Para cada pivô, a resposta contém uma lista de objetos de Consulta que contêm as consultas sugeridas. O campo text contém a consulta sugerida e o campo displayText contém o termo que substitui o pivô na consulta original. Por exemplo, Limpeza de Janelas.

Pode utilizar os campos text e thumbnail para apresentar as cadeias de consulta expandidas ao utilizador no caso de a cadeia de consulta expandida ser realmente aquilo que procura. Torne a miniatura e o texto clicáveis com o URL webSearchUrl ou o URL searchLink. Utilize webSearchUrl para encaminhar o utilizador para os resultados de pesquisa do Bing ou searchLink se fornecer a sua própria página de resultados.

Limitar pedidos

O serviço e o seu tipo de subscrição determinam o número de consultas por segundo (QPS) que pode fazer. Certifique-se de que a sua aplicação inclui a lógica necessária para se manter na sua quota. Se o limite de QPS for atingido ou excedido, o pedido falha e é devolvido um código de estado HTTP 429. A resposta inclui o cabeçalho Retry-After, que indica o tempo que tem de esperar antes de poder enviar outro pedido.

Denial of service versus Limitação

O serviço diferencia entre um ataque denial of service (DoS) e uma violação de QPS. Se o serviço suspeitar de um ataque DoS, o pedido é realizado com êxito (o código de estado HTTP é 200 OK). No entanto, o corpo da resposta está vazio.