Início Rápido: Pesquisar vídeos usando a API de Pesquisa de Vídeo do Bing e C#

Aviso

As APIs de Pesquisa do Bing estão migrando dos Serviços Cognitivos para os Serviços de Pesquisa do Bing. A partir de 30 de outubro de 2020, todas as novas instâncias da Pesquisa do Bing precisam ser provisionadas seguindo o processo documentado aqui. As APIs de Pesquisa do Bing provisionadas por meio dos Serviços Cognitivos terão suporte nos próximos três anos ou até o final do seu Contrato Enterprise, o que ocorrer primeiro. Para obter instruções sobre a migração, confira Serviços de Pesquisa do Bing.

Use este início rápido para fazer sua primeira chamada à API da Pesquisa de Vídeo do Bing. Este aplicativo C# simples envia uma consulta de pesquisa de vídeo HTTP para a API e exibe a resposta JSON. Embora esse aplicativo seja escrito em C#, a API é um serviço Web RESTful compatível com a maioria das linguagens de programação.

O código-fonte para deste exemplo está disponível no GitHub com anotações de código, recursos e tratamentos de erro adicionais.

Pré-requisitos

Você precisará configurar seu computador para executar o .NET Core. Encontre as instruções de instalação na página Downloads do .NET Core. Execute esse aplicativo no Windows, no Linux, no macOS ou em um contêiner do Docker. Será necessário instalar o editor de código de sua preferência. As descrições a seguir usam o Visual Studio Code, que é uma software livre, no editor de plataforma. No entanto, você pode usar quaisquer ferramentas que esteja familiarizado.

Criar um recurso do Azure

Comece a usar a API de Pesquisa de Vídeo do Bing criando um dos seguintes recursos do Azure:

Recurso de Pesquisa do Bing v7

  • Disponível por meio do portal do Azure até que você exclua o recurso.
  • Use o tipo de preço gratuito para experimentar o serviço e atualize mais tarde para uma camada paga para produção.

Recurso de vários serviços

  • Disponível por meio do portal do Azure até que você exclua o recurso.
  • Use a mesma chave e ponto de extremidade para seus aplicativos em vários Serviços Cognitivos.

Criar e inicializar um projeto

A primeira etapa é criar um novo aplicativo. Abra um prompt de comando e crie um novo diretório para seu aplicativo. Torne ele o diretório atual. Insira o seguinte comando em uma janela do console:

dotnet new console --name VideoSearchClient

Você precisará adicionar a seguinte diretiva using à parte superior do método Main para que o compilador C# reconheça os tipos Tarefa e JSON:

using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Collections.Generic;
using System.Text.Json;
using System.Text.Json.Serialization;

Adicione variáveis para a chave de assinatura, um ponto de extremidade e um termo de pesquisa. Para o valor uriBase, use o ponto de extremidade global no código a seguir ou o ponto de extremidade do subdomínio personalizado exibido no portal do Azure para seu recurso.

// Replace the accessKey string value with your valid access key.
const string _accessKey = "enter your key here";

// Or use the custom subdomain endpoint displayed in the Azure portal for your resource.
const string _uriBase = "https://api.cognitive.microsoft.com/bing/v7.0/videos/search";

const string _searchTerm = "kittens";

Em seguida, atualize o método Main para que possamos usar métodos assíncronos. Adicione o modificador assíncrono e altere o tipo de retorno para Tarefa.

static async Task Main(string[] args)
{
    
}

Agora você tem um programa que não faz nada, mas faz isso de maneira assíncrona. Vamos melhorar isso.

Criar uma estrutura de dados para armazenar a resposta da API de Pesquisa de Vídeo do Bing

Defina uma classe SearchResult e Video para conter os resultados da pesquisa de vídeo. Você poderá adicionar mais propriedades posteriormente quando precisar de outros campos do resultado JSON.

class SearchResult
{
    [JsonPropertyName("totalEstimatedMatches")]
    public int TotalEstimatedMatches { get; set; }

    [JsonPropertyName("value")]
    public List<Video> Videos { get; set; }
}

class Video
{
    [JsonPropertyName("name")]
    public string Name { get; set; }

    [JsonPropertyName("description")]
    public string Description { get; set; }

    [JsonPropertyName("thumbnailUrl")]
    public string ThumbnailUrl { get; set; }

    [JsonPropertyName("contentUrl")]
    public string ContentUrl { get; set; }
}

Crie e manipule uma solicitação de pesquisa de vídeo

Usamos HttpClient para fazer a chamada à API. Primeiro, precisamos adicionar o cabeçalho Ocp-Apim-Subscription-Key e a sua chave de acesso.

using var client = new HttpClient();
client.BaseAddress = new Uri(_uriBase);
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", _accessKey);

Construa o URI para a solicitação de pesquisa. Formate o termo de pesquisa _searchTerm antes de acrescentá-lo à cadeia de caracteres.

var response = await client.GetAsync($"?q={Uri.EscapeDataString(_searchTerm)}");

Processe o resultado

Quando a resposta for bem-sucedida, poderemos processar os dados JSON. Desserializamos a cadeia de caracteres JSON no SearchResult que criamos anteriormente. Faça um loop para o resultado (se houver) e imprima o resultado no console.

if (response.IsSuccessStatusCode)
{
    var json = await response.Content.ReadAsStringAsync();
    var result = JsonSerializer.Deserialize<SearchResult>(json);

    foreach (var video in result.Videos)
    {
        Console.WriteLine($"Name: {video.Name}");
        Console.WriteLine($"ContentUrl: {video.ContentUrl}");
        Console.WriteLine();
    }
}

Resposta JSON de exemplo

Uma resposta com êxito é retornada em JSON, conforme mostrado no seguinte exemplo:

{
    "_type": "Videos",
    "instrumentation": {},
    "readLink": "https://api.cognitive.microsoft.com/api/v7/videos/search?q=kittens",
    "webSearchUrl": "https://www.bing.com/videos/search?q=kittens",
    "totalEstimatedMatches": 1000,
    "value": [
        {
            "webSearchUrl": "https://www.bing.com/videos/search?q=kittens&view=...",
            "name": "Top 10 cute kitten videos compilation",
            "description": "HELP HOMELESS ANIMALS AND WIN A PRIZE BY CHOOSING...",
            "thumbnailUrl": "https://tse4.mm.bing.net/th?id=OVP.n1aE_Oikl4MtzBb...",
            "datePublished": "2014-11-12T22:47:36.0000000",
            "publisher": [
                {
                    "name": "Fabrikam"
                }
            ],
            "creator": {
                "name": "Marcus Appel"
            },
            "isAccessibleForFree": true,
            "contentUrl": "https://www.fabrikam.com/watch?v=8HVWitAW-Qg",
            "hostPageUrl": "https://www.fabrikam.com/watch?v=8HVWitAW-Qg",
            "encodingFormat": "h264",
            "hostPageDisplayUrl": "https://www.fabrikam.com/watch?v=8HVWitAW-Qg",
            "width": 480,
            "height": 360,
            "duration": "PT3M52S",
            "motionThumbnailUrl": "https://tse4.mm.bing.net/th?id=OM.j4QyJAENJphdZQ_1501386166&pid=Api",
            "embedHtml": "<iframe width=\"1280\" height=\"720\" src=\"https://www.fabrikam.com/embed/8HVWitAW-Qg?autoplay=1\" frameborder=\"0\" allowfullscreen></iframe>",
            "allowHttpsEmbed": true,
            "viewCount": 7513633,
            "thumbnail": {
                "width": 300,
                "height": 168
            },
            "videoId": "655D98260D012432848F6558260D012432848F",
            "allowMobileEmbed": true,
            "isSuperfresh": false
        },
        . . .
    ],
    "nextOffset": 36,
    "queryExpansions": [
        {
            "text": "Kittens Meowing",
            "displayText": "Meowing",
            "webSearchUrl": "https://www.bing.com/videos/search?q=Kittens+Meowing...",
            "searchLink": "https://api.cognitive.microsoft.com/api/v7/videos/search...",
            "thumbnail": {
                "thumbnailUrl": "https://tse3.mm.bing.net/th?q=Kittens+Meowing&pid..."
            }
        },
        {
            "text": "Funny Kittens",
            "displayText": "Funny",
            "webSearchUrl": "https://www.bing.com/videos/search?q=Funny+Kittens...",
            "searchLink": "https://api.cognitive.microsoft.com/api/v7/videos/search...",
            "thumbnail": {
                "thumbnailUrl": "https://tse3.mm.bing.net/th?q=Funny+Kittens&..."
            }
        },
        . . .
    ],
    "pivotSuggestions": [
        {
            "pivot": "kittens",
            "suggestions": [
                {
                    "text": "Cat",
                    "displayText": "Cat",
                    "webSearchUrl": "https://www.bing.com/videos/search?q=Cat...",
                    "searchLink": "https://api.cognitive.microsoft.com/api/v7/videos/search?...",
                    "thumbnail": {
                        "thumbnailUrl": "https://tse3.mm.bing.net/th?q=Cat&pid=Api..."
                    }
                },
                {
                    "text": "Feral Cat",
                    "displayText": "Feral Cat",
                    "webSearchUrl": "https://www.bing.com/videos/search?q=Feral+Cat...",
                    "searchLink": "https://api.cognitive.microsoft.com/api/v7/videos/search...",
                    "thumbnail": {
                        "thumbnailUrl": "https://tse3.mm.bing.net/th?q=Feral+Cat&pid=Api&..."
                    }
                }
            ]
        }
    ],
    "relatedSearches": [
        {
            "text": "Kittens Being Born",
            "displayText": "Kittens Being Born",
            "webSearchUrl": "https://www.bing.com/videos/search?q=Kittens+Being+Born...",
            "searchLink": "https://api.cognitive.microsoft.com/api/v7/videos/search?...",
            "thumbnail": {
                "thumbnailUrl": "https://tse1.mm.bing.net/th?q=Kittens+Being+Born&pid=..."
            }
        },
        . . .
    ]
}

Próximas etapas

Confira também

O que é a API da Pesquisa de Vídeo do Bing?