Envio de pedidos de pesquisa para a API de Pesquisa de Vídeo BingSending search requests to the Bing Video Search API

Este artigo descreve os parâmetros e atributos dos pedidos enviados para a API de Pesquisa de Vídeo Bing, bem como o objeto de resposta JSON que devolve.This article describes the parameters and attributes of requests sent to the Bing Video Search API, as well as the JSON response object it returns.

Criar um recurso AzureCreate an Azure resource

Comece a utilizar a API de Pesquisa de Vídeo Bing criando um dos seguintes recursos Azure:Start using the Bing Video Search API by creating one of the following Azure resources:

Bing Search v7 recursoBing Search v7 resource

  • Disponível através do portal Azure até eliminar o recurso.Available through the Azure portal until you delete the resource.
  • Use o nível de preços gratuitos para experimentar o serviço e atualize mais tarde para um nível pago para produção.Use the free pricing tier to try the service, and upgrade later to a paid tier for production.

Recurso multi-serviçoMulti-service resource

  • Disponível através do portal Azure até eliminar o recurso.Available through the Azure portal until you delete the resource.
  • Use a mesma chave e ponto final para as suas aplicações, através de vários Serviços Cognitivos.Use the same key and endpoint for your applications, across multiple Cognitive Services.

Sugerir termos de pesquisa com a API Bing AutosuggestSuggest search terms with the Bing Autosuggest API

Se disponibilizar uma caixa de pesquisa na qual o utilizador introduz o seu termo de pesquisa, utilize a API de Sugestão Automática do Bing para melhorar a experiência.If you provide a search box where the user enters their search term, use the Bing Autosuggest API to improve the experience. A API devolve cadeias de consulta sugerida com base em termos de pesquisa parcial à medida que o utilizador escreve.The API returns suggested query strings based on partial search terms as the user types.

Depois de o utilizador introduzir o seu termo de pesquisa, o URL codifica-o antes de definir o parâmetro de consulta q.After the user enters their search term, URL-encode it before setting the q query parameter. Por exemplo, se o utilizador introduzir sailing dinghies, defina q como sailing+dinghies ou sailing%20dinghies.For example, if the user enters sailing dinghies, set q to sailing+dinghies or sailing%20dinghies.

Envio de um pedidoSending a request

Para obter os resultados da pesquisa de vídeo, enviaria um pedido GET ao seguinte ponto final:To get Video search results, you'd send a GET request to the following endpoint:

https://api.cognitive.microsoft.com/bing/v7.0/videos/search

O pedido tem de utilizar o protocolo HTTPS.The request must use the HTTPS protocol.

Recomendamos que todos os pedidos tenham origem num servidor.We recommend that all requests originate from a server. Distribuir a chave como parte de uma aplicação cliente abre mais oportunidades de acesso à mesma a terceiros mal-intencionados.Distributing the key as part of a client application provides more opportunity for a malicious third party to access it. Fazer chamadas a partir de um servidor também fornece um único ponto de atualização para futuras versões da API.Making calls from a server also provides a single upgrade point for future versions of the API.

O pedido tem de especificar o parâmetro de consulta q, que contém o termo de pesquisa do utilizador.The request must specify the q query parameter, which contains the user's search term. Embora seja opcional, o pedido deve também especificar o parâmetro de consulta mkt, que identifica o mercado de onde pretende que os resultados provenham.Although it's optional, the request should also specify the mkt query parameter, which identifies the market where you want the results to come from. Para obter uma lista opcional de parâmetros de consulta, como pricing, veja Parâmetros de Consulta.For a list of optional query parameters such as pricing, see Query Parameters. Todos os valores de parâmetro de consulta têm de estar codificados com URL.All query parameter values must be URL encoded.

O pedido tem de especificar o cabeçalho Ocp-Apim-Subscription-Key.The request must specify the Ocp-Apim-Subscription-Key header. Embora seja opcional, recomenda-se que especifique também os seguintes cabeçalhos:Although optional, you are encouraged to also specify the following headers:

Os cabeçalhos de IP e localização do cliente são importantes para devolver o conteúdo com reconhecimento de local.The client IP and location headers are important for returning location aware content.

Para obter uma lista de todos os cabeçalhos de pedido e resposta, veja Cabeçalhos.For a list of all request and response headers, see Headers.

Exemplo de pedido de pesquisaExample search request

A seguir, é-lhe mostrado um pedido de pesquisa que inclui todos os parâmetros de consulta e cabeçalhos sugeridos.The following shows a search request that includes all the suggested query parameters and headers. 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.If it's your first time calling any of the Bing APIs, don't include the client ID header. 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.Only include the client ID if you've previously called a Bing API and Bing returned a client ID for the user and device combination.

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  

Exemplo JSON respostaExample JSON response

O código a seguir mostra a resposta ao pedido anterior.The following shows the response to the previous request. O exemplo também mostra os cabeçalhos de resposta específicos do Bing.The example also shows the Bing-specific response headers.

Nota

Como os formatos e parâmetros de URL estão sujeitos a alterações sem aviso prévio, utilize todos os URLs como está.Because URL formats and parameters are subject to change without notice, use all URLs as-is. Não deve assumir dependências do formato URL ou parâmetros, exceto quando for anotado.You should not take dependencies on the URL format or parameters except where noted.

BingAPIs-TraceId: 76DD2C2549B94F9FB55B4BD6FEB6AC
X-MSEdge-ClientID: 1C3352B306E669780D58D607B96869
BingAPIs-Market: en-US

{
    "_type" : "Videos",
    "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=81EF7545D5694...",
    "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=81EF7545D56...",
            "thumbnailUrl" : "https:\/\/tse4.mm.bing.net\/th?id=OVP.DYWCvh...",
            "datePublished" : "2014-03-04T11:51:53",
            "publisher" : [
                {
                    "name" : "Fabrikam"
                }
            ],
            "creator" : {
                "name" : "Marcus Appel"
            },
            "contentUrl" : "https:\/\/www.fabrikam.com\/watch?v=vzmPjHZ--g",
            "hostPageUrl" : "https:\/\/www.bing.com\/cr?IG=81EF7545D56944...",
            "encodingFormat" : "h264",
            "hostPageDisplayUrl" : "https:\/\/www.fabrikam.com\/watch?v=vzmPjBZ--g",
            "width" : 1280,
            "height" : 720,
            "duration" : "PT2M47S",
            "motionThumbnailUrl" : "https:\/\/tse3.mm.bing.net\/th?id=OM.Y6...",
            "embedHtml" : "<iframe width=\"1280\" height=\"720\" src=\"https:...><\/iframe>",
            "allowHttpsEmbed" : true,
            "viewCount" : 8743,
            "thumbnail" : {
                "width" : 300,
                "height" : 168
            },
            "videoId" : "6DB795E11A6E3CBAAD636DB795E11E3CBAAD63",
            "allowMobileEmbed" : true,
            "isSuperfresh" : false
        },
        . . .
    ],
    "nextOffset" : 0,
    "pivotSuggestions" : [
        {
            "pivot" : "sailing",
            "suggestions" : []
        },
        {
            "pivot" : "dinghies",
            "suggestions" : [
                {
                    "text" : "Sailing Cruising",
                    "displayText" : "Cruising",
                    "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=81EF754...",
                    "searchLink" : "https:\/\/api.cognitive.microsoft.com...",
                    "thumbnail" : {
                        "thumbnailUrl" : "https:\/\/tse4.mm.bing.net\/th?q=Sailing..."
                    }
                },
                . . .
            ]
        }
    ]
}

Passos seguintesNext steps

Experimente a API.Try out the API. Aceda a Consola de Testes da API da Pesquisa de Vídeos.Go to Video Search API Testing Console.

Para obter detalhes sobre os objetos de resposta, veja Pesquisar Vídeos na Web.For details about consuming the response objects, see Searching the Web for Videos.

Para obter detalhes de como obter informações sobre um vídeo, como pesquisas relacionadas, veja Informações de Vídeo.For details about getting insights about a video such as related searches, see Video Insights.

Para obter detalhes sobre os vídeos que são mais populares nas redes sociais, veja Vídeos Populares.For details about videos that are trending on social media, see Trending Videos.