Bing Entidade Pesquisa referência API v7

Aviso

As APIs de Pesquisa de Bing estão a mover-se dos Serviços Cognitivos para os Serviços de Pesquisa Bing. A partir de 30 de outubro de 2020, quaisquer novos casos de Bing Search devem ser adquir-se na sequência do processo aquidocumentado. Bing Search APIs aforados usando Serviços Cognitivos será suportado durante os próximos três anos ou até o final do seu Contrato de Empresa, o que acontecer primeiro. Para obter instruções de migração, consulte os Serviços de Busca Bing.

A API de Pesquisa de Entidade permite-lhe enviar uma consulta de pesquisa para Bing e obter de volta resultados de pesquisa que incluem entidades e lugares. Os resultados de locais incluem restaurantes, hotéis ou outras empresas locais. Nos locais, a consulta pode especificar o nome da empresa local ou pedir uma lista (por exemplo, restaurantes perto de mim). Os resultados de entidades incluem pessoas, locais ou coisas. Os locais neste contexto são atrações turísticas, estados, países, etc.

Nota

As respostas de Entidades suportam vários mercados, mas a resposta de Locais suporta apenas as localizações de Empresas nos E.U.A.

Esta secção fornece detalhes técnicos sobre os objetos de resposta e os parâmetros de consulta e cabeçalhos que afetam os resultados da pesquisa. Para exemplos que mostram como fazer pedidos, consulte pesquisar na web entidades e locais.

Para obter informações sobre cabeçalhos que os pedidos devem incluir, consulte Headers.

Para obter informações sobre os parâmetros de consulta que os pedidos devem incluir, consulte parâmetros de consulta.

Para obter informações sobre os objetos JSON que a resposta inclui, consulte os objetos de resposta.

Para obter informações sobre a utilização permitida e exibição de resultados, consulte os requisitos de utilização e exibição.

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á. Não deve assumir dependências do formato URL ou parâmetros, exceto quando for anotado.

Ponto final

Para solicitar os resultados da pesquisa da entidade, envie um pedido GET para:

https://api.cognitive.microsoft.com/bing/v7.0/entities

Para subscrições multi-serviços, deve incluir a região no URL. Por exemplo: westus.api.cognitive.microsoft.com. Ver Regiões Apoiadas.

O pedido tem de utilizar o protocolo HTTPS.

Nota

O comprimento máximo de URL é de 2.048 caracteres. Para garantir que o comprimento do URL não exceda o limite, o comprimento máximo dos seus parâmetros de consulta deve ser inferior a 1.500 caracteres. Se o URL exceder 2.048 caracteres, o servidor retorna 404 Não encontrado.

Cabeçalhos

Seguem-se os cabeçalhos que um pedido e resposta podem incluir.

Cabeçalho Description
Aceitar Cabeçalho de pedido opcional.

O tipo de mídia predefinido é aplicação/json. Para especificar que a utilização da resposta JSON-LD,desa estale o cabeçalho Aceitar para aplicação/ld+json.
Accept-Language Cabeçalho de pedido opcional.

Uma lista separada por vírgulas dos idiomas que vão ser utilizados nas cadeias da interface de utilizador. A lista está em ordem decrescente de preferência. Para obter mais informações, incluindo o formato esperado, veja RFC2616.

Este cabeçalho e o parâmetro de consulta setLang são mutuamente exclusivos — não os especifique a ambos.

Se definir este cabeçalho, também tem de especificar o parâmetro de consulta cc. Para determinar o mercado do qual devolver resultados, o Bing utiliza o primeiro idioma suportado que encontra na lista e combina-o com o valor do parâmetro cc. Se a lista não incluir um idioma suportado, o Bing encontra o idioma e o mercado mais parecidos que suportem o pedido ou utiliza um mercado agregado ou predefinido para devolver os resultados. Para determinar o mercado que o Bing utiliza, veja o cabeçalho BingAPIs-Market.

Utilize este cabeçalho o parâmetro de consulta cc apenas se especificar vários idiomas. Caso contrário, utilize os parâmetros de consulta mkt e setLang.

As cadeias da interface de utilizador são cadeias utilizadas como etiquetas na interface de utilizador. Os objetos de resposta JSON têm poucas cadeias de interface de utilizador. Todas as ligações para propriedades de Bing.com nos objetos de resposta aplicam o idioma especificado.
BingAPIs-Market O cabeçalho da resposta.

O mercado que o pedido utiliza. O formulário <languageCode> - <countryCode> é. Por exemplo: en-US.
BingAPIs-TraceId O cabeçalho da resposta.

O ID da entrada de registo que contém os detalhes do pedido. Quando ocorrer um erro, capture este ID. Se não conseguir determinar nem resolver o problema, inclua o ID juntamente com as outras informações que enviar à equipa de suporte.
Ocp-Apim-Subscription-Key Cabeçalho de pedido obrigatório.

A chave de subscrição que recebeu quando se inscreveu neste serviço nos Serviços Cognitivos.
Pragma Cabeçalho de pedido opcional

Por predefinição, o Bing devolve conteúdo em cache, se disponível. Para impedir que o Bing devolva conteúdo em cache, defina o cabeçalho Pragma como no-cache (por exemplo, Pragma: no-cache).
User-Agent Cabeçalho de pedido opcional.

O agente de utilizador que origina o pedido. O Bing utiliza o agente de utilizador para proporcionar uma experiência otimizada aos utilizadores de dispositivos móveis. Embora seja opcional, recomenda-se que especifique sempre este cabeçalho.

O agente de utilizador deve ser a mesma cadeia que qualquer browser geralmente utilizado envia. Para obter informações sobre os agentes de utilizador, veja RFC 2616.

Pode ver exemplos de cadeias de agente de utilizador abaixo:
  • Windows Phone—Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)

  • Android—Mozilla/5.0 (Linux; U; Android 2.3.5; en-us; SCH-I500 Build/GINGERBREAD) AppleWebKit/533.1 (KHTML; like Gecko) Version/4.0 Mobile Safari/533.1

  • iPhone—Mozilla/5.0 (iPhone; CPU iPhone OS 6_1 like Mac OS X) AppleWebKit/536.26 (KHTML; like Gecko) Mobile/10B142 iPhone4;1 BingWeb/3.03.1428.20120423

  • PC—Mozilla/5.0 (Windows NT 6.3; WOW64; Trident/7.0; Touch; rv:11.0) like Gecko

  • iPad—Mozilla/5.0 (iPad; CPU OS 7_0 like Mac OS X) AppleWebKit/537.51.1 (KHTML, like Gecko) Version/7.0 Mobile/11A465 Safari/9537.53
X-MSEdge-ClientID Cabeçalho de pedido e resposta opcional.

O Bing utiliza este cabeçalho para proporcionar um comportamento consistente nas chamada à API do Bing aos utilizadores. O Bing lança, muitas vezes, funcionalidades e melhorias novas e utiliza o ID de cliente como uma chave para atribuir tráfego aos diferentes lançamentos. Se não utilizar o mesmo ID de cliente para um utilizador em vários pedidos, o Bing poderá atribuir esse utilizador a vários lançamentos sobrepostos. A atribuição a vários lançamentos sobrepostos pode provocar uma experiência de utilizador inconsistente. Por exemplo, se a atribuição de lançamento do segundo pedido for diferente da do primeiro, a experiência poderá ser inesperada. Além disso, o Bing pode usar o ID do cliente para adaptar os resultados web ao histórico de pesquisa desse cliente, proporcionando uma experiência mais rica para o utilizador.

O Bing também utiliza este cabeçalho para ajudar a melhorar as classificações dos resultados ao analisar a atividade gerada por um ID de cliente. As melhorias à relevância ajudam a que as APIs do Bing devolvam resultados com melhor qualidade, o que, por sua vez, origina taxas de cliques mais altas para o consumidor da API.

IMPORTANTE: embora seja opcional, deve ver este cabeçalho como obrigatório. Persistir o ID de cliente em vários pedidos para a mesma combinação de utilizador final e dispositivo permite 1) que o consumidor da API receba uma experiência de utilizador consistente e 2) taxas de cliques mais altas, através de resultados com melhor qualidade das APIs do Bing.

As regras abaixo são as regras de utilização básicas aplicáveis a este cabeçalho.
  • Cada utilizador que utilize a sua aplicação no dispositivo tem de ter um ID de cliente exclusivo e gerado pelo Bing.

    Se não incluir este cabeçalho no pedido, o Bing gera um ID e devolve-o no cabeçalho da resposta X-MSEdge-ClientID. O único momento em que NÃO deve incluir este cabeçalho num pedido é na primeira vez que o utilizador utiliza a sua aplicação nesse dispositivo.

  • Utilize o ID de cliente para cada pedido da API do Bing que a sua aplicação fizer para este utilizador no dispositivo.

  • ATENÇÃO: Tem de garantir que este ID do Cliente não está ligado a nenhuma informação autenticada da conta de utilizador.

  • Persista o ID de cliente. Para persistir o ID numa aplicação de browser, utilize um cookie HTTP persistente para garantir que esse ID é utilizado em todas as sessões. Não utilize um cookie de sessão. Relativamente a outras aplicações, como aplicações móveis, utilize o armazenamento persistente do dispositivo para persistir o ID.

    Da próxima vez que o utilizador utilizar a aplicação nesse dispositivo, recebe o ID de cliente que foi persistido.

NOTA: as respostas do Bing podem incluir ou não este cabeçalho. Se a resposta incluir este cabeçalho, capture o ID de cliente e utilize-o em todos os pedidos do Bing subsequentes do utilizador nesse dispositivo.

NOTA: se incluir X-MSEdge-ClientID, não pode incluir cookies no pedido.
X-MSEdge-ClientIP Cabeçalho de pedido opcional.

O endereço IPv4 ou IPv6 do dispositivo cliente. O endereço IP é utilizado para detetar a localização do utilizador. O Bing utiliza as informações de localização para determinar o comportamento do safesearch.

NOTA: embora seja opcional, recomenda-se que especifique sempre este cabeçalho e o cabeçalho X-Search-Location.

Não ofusque a morada (por exemplo, ao alterar o último octeto para 0). Ofuscar a morada faz com que a localização não esteja perto da localização efetiva do dispositivo, o que pode fazer com que o Bing sirva resultados errados.
X-Search-Location Cabeçalho de pedido opcional.

Uma lista separada por ponto e vírgula de pares de chaves/valores que descreve a localização geográfica do cliente. O Bing utiliza as informações de localização para determinar o comportamento do safesearch e para devolver conteúdos locais relevantes. Especifique o par chave/valor como <key> : <value> . As chaves seguintes são as chaves utilizadas para especificar a localização do utilizador.

  • lat — A latitude da localização do cliente, em graus. Tem de ser igual ou superior a -90,0 e inferior ou igual a +90,0. Os valores negativos indicam latitudes no hemisfério sul e os positivos latitudes no hemisfério norte.

  • —longa a longitude da localização do cliente, em graus. Tem de ser igual ou superior a -180.0 e inferior ou igual a +180.0. Os valores negativos indicam longitudes a ocidente e os positivos a oriente.

  • re — O raio, em metros, que especifica a precisão horizontal das coordenadas. Transmita o valor que o serviço de localização do dispositivo devolve. Os valores mais comuns podem ser 22 m para GPS/Wi-Fi, 380 m para triangulação de antenas e 18 000 m para pesquisa de IP inversa.

  • ts — O calendário UTC UNIX de quando o cliente estava no local. (o carimbo de data/hora é o número de segundos desde 1 de janeiro de 1970.)

  • head—Optional. O cabeçalho relativo do cliente ou a direção de deslocamento. Especifique a direção de deslocamento em graus, de 0 a 360, a contar no sentido dos ponteiros do relógio em relação ao norte verdadeiro. Especifique esta chave apenas se a chave sp não for zero.

  • sp — A velocidade horizontal (velocidade), em metros por segundo, que o dispositivo cliente está a viajar.

  • alt — A altitude do dispositivo cliente, em metros.

  • are—Optional. O raio, em metros, que especifica a exatidão vertical das coordenadas. Raio de raio está a 50 km. Especifique esta chave apenas se especificar a chave alt.

  • disp — Opcional. A localização geográfica do utilizador no formulário, disp:<City, State>. Por exemplo, disp: Seattle, Washington. Esta é a versão de texto de exibição da localização do utilizador que especificou utilizando as teclas lat/long. Se este valor entrar em conflito com as coordenadas lat/long, bing utiliza o valor de disp como localização do utilizador.

NOTA: Bing ignora este cabeçalho se a consulta incluir uma localização. Por exemplo, se este cabeçalho refletir a localização do utilizador como São Francisco, mas a consulta são restaurantes seattle , Bing devolve restaurantes localizados em Seattle, Washington.

NOTA: Embora estas chaves sejam opcionais, quanto mais informação fornecer, mais precisas são os resultados da localização.

NOTA: É-lhe encorajado a especificar sempre a localização geográfica do utilizador. Especificar a localização é particularmente importante se o endereço IP do cliente não refletir, com precisão, a localização física do utilizador (por exemplo, se este utilizar VPN). Para obter os melhores resultados, deve incluir este cabeçalho e o cabeçalho X-MSEdge-ClientIP, mas deve incluir este cabeçalho, no mínimo.

Nota

Não se esqueça de que os Termos de Utilização requerem conformidade com toda a legislação aplicável, incluindo a relativa à utilização destes cabeçalhos. Por exemplo, em determinadas jurisdições, como a Europa, há requisitos para obter o consentimento do utilizador antes de colocar certos tipos de dispositivos de monitorização nos dispositivos dos utilizadores.

Parâmetros de consulta

O pedido pode incluir os seguintes parâmetros de consulta. Consulte a coluna requerida para obter os parâmetros necessários. Tem de codificar os parâmetros de consulta.

Name Valor Tipo Necessário
mkt O mercado de onde os resultados provêm.

Para obter uma lista de possíveis valores de mercado, consulte códigos de mercado.

NOTA: O código de mercado é necessário. Desta forma, ajuda o Bing a encaminhar o pedido e a devolver a resposta adequada e ideal.

String Yes
q O termo de pesquisa do utilizador. String Yes
filtro de resposta Uma lista de respostas delimitadas por vírgulas para incluir na resposta. Se não especificar este parâmetro, a resposta inclui todas as respostas de pesquisa para as quais existem dados relevantes.

Seguem-se os valores possíveis do filtro.

  • Entidades
  • Realiza
String No
respostaFormat O tipo de mídia a usar para a resposta. Seguem-se os possíveis valores caso-insensíveis.
  • JSON
  • JSONLD

O padrão é JSON. Para obter informações sobre os objetos JSON que a resposta contém, consulte Objetos de Resposta.

Se especificar JsonLd, o corpo de resposta inclui objetos JSON-LD que contêm os resultados da pesquisa. Para obter informações sobre o JSON-LD, consulte JSON-LD.
String No
safeSearch É um filtro utilizado para filtrar conteúdo para adultos. Os valores seguintes são os possíveis valores do filtro, não sensíveis a maiúsculas e minúsculas.
  • Off — Devolver páginas web com texto adulto, imagens ou vídeos.

  • Páginas de retorno moderado — com texto adulto, mas não imagens ou vídeos adultos.

  • Estrita — Não devolva páginas web com texto adulto, imagens ou vídeos.

A predefinição é Moderado.

NOTA: Se o pedido vier de um mercado que a política de adultos de Bing requer que safeSearch seja definido como Strict, Bing ignora o safeSearch valor e usa Strict.

NOTA: se utilizar o operador de consulta site:, existe a possibilidade de a resposta poder conter conteúdos para adultos, independentemente da definição do parâmetro de consulta safeSearch. Utilize site: apenas se tiver conhecimento do conteúdo do site e se o seu cenário suportar a possibilidade de conteúdos para adultos.
String No
setLang O idioma a utilizar nas cadeias da interface de utilizador. Pode especificar o idioma usando um código de 2 letras ou 4 letras. É preferível a utilização de códigos de 4 letras.

Para obter uma lista de códigos linguísticos suportados, consulte as línguas apoiadas por Bing.

Bing carrega as cordas localizadas se setlang contiver um código de cultura neutro de 2 letras válido (fr) ou um código de cultura específico válido de 4 letras (fr-ca). Por exemplo, para fr-ca, Bing carrega as cordas de código de cultura neutra fr.

Se setlang não for válido (por exemplo, zh) ou Bing não suporta a língua (por exemplo, af, af-na), Bing defaults to en (inglês).

Para especificar o código de 2 letras, desa um parâmetro para um código linguístico ISO 639-1.

Para especificar o código de 4 letras, utilize o formulário -<> país/região onde se encontra um código linguístico ISO 639-1 (cultura neutra) e <> país/região iso 3166 (cultura específica). Por exemplo, use en-US para inglês dos Estados Unidos.

Embora seja opcional, deve indicar sempre o idioma. Normalmente, setLang é definido como o mesmo idioma especificado por mkt, a não ser que o utilizador queira que as cadeias da interface de utilizador sejam apresentadas noutro idioma.

Este parâmetro e o cabeçalho Accept-Language são mutuamente exclusivos — não especifique ambos.

As cadeias da interface de utilizador são cadeias utilizadas como etiquetas na interface de utilizador. Os objetos de resposta JSON têm poucas cadeias de interface de utilizador. Além disso, todas as ligações para propriedades de Bing.com nos objetos de resposta aplicam o idioma especificado.
String No

Objetos de resposta

Seguem-se os objetos de resposta JSON que a resposta pode incluir. Se o pedido for bem sucedido, o objeto de nível superior na resposta é o objeto SearchResponse. Se o pedido falhar, o objeto de nível superior é o objeto ErrorResponse.

Objeto Description
Entidade Define uma entidade como uma pessoa, lugar ou coisa.
EntityPresentationInfo Define informações adicionais sobre uma entidade como sugestões de tipo.
Erro Define um erro que ocorreu.
Resposta de erros O objeto de nível superior que a resposta inclui quando o pedido falha.
Imagem Define uma imagem.
Licença Define a licença segundo a qual o texto ou a foto podem ser utilizados.
Atribuição de Licenças Define uma regra contratual para a atribuição de licença.
Ligação Define os componentes de uma hiperligação.
LinkAttribution Define uma regra contratual para a atribuição de ligações.
MediaAttribution Define uma regra contratual para a atribuição de meios de comunicação.
Organização Define uma editora.
Lugar Define informações sobre uma entidade local, como um restaurante ou hotel.
PostalAddress Define um endereço postal.
QueryContexto Define o contexto de consulta que Bing usou para o pedido.
Identificável Um identificador de recursos
RankingGroup Define um grupo de resultados de pesquisa, como mainline.
RankingItem Define um item de resultado de pesquisa para visualizar.
RankingResponse Define onde no conteúdo da página de resultados de pesquisa deve ser colocado e em que ordem.
PesquisaResponse O objeto de nível superior que a resposta inclui quando o pedido é bem sucedido.
Distribuição de texto Define uma regra contratual para a atribuição de texto simples.

Entidade

Define uma entidade como uma pessoa, lugar ou coisa.

Name Valor Tipo
bingId Um ID que identifica exclusivamente esta entidade. String
contratuaisRulas Uma lista de regras a que deve aderir se mostrar a entidade. Por exemplo, as regras podem reger-se atribuindo a descrição da entidade.

Podem aplicar-se as seguintes regras contratuais.


Nem todas as entidades incluem regras. Se a entidade fornecer regras contratuais, deve cumpri-las. Para obter mais informações sobre a utilização de regras contratuais, consulte Atribuindo Dados.
Objeto[]
descrição Uma breve descrição da entidade. String
entidadePresentaçãoInfo Informações adicionais sobre a entidade, tais como indícios que pode usar para determinar o tipo da entidade. Para determinar o tipo da entidade, utilize os entityScenario campos e entityTypeHint campos. Por exemplo, os campos ajudam-no a determinar se a entidade é uma entidade dominante ou desambiguação e se é uma pessoa ou filme. A entidade é uma entidade dominante se bing acredita que apenas uma entidade satisfaz o pedido. Se várias entidades puderem satisfazer o pedido, a entidade é uma entidade de desambiguação e o utilizador precisa de selecionar a entidade em que está interessado. EntityPresentationInfo
image Uma imagem da entidade. Imagem
name O nome da entidade. String
webSearchUrl O URL que leva o utilizador à página de resultados de pesquisa de Bing para esta entidade. String

EntityPresentationInfo

Define informações adicionais sobre uma entidade como sugestões de tipo.

Name Valor Tipo
entidadesScenario O cenário apoiado. String
entidadeTypeDisplayHint Uma versão de exibição da sugestão da entidade. Por exemplo, se entityTypeHints for Artista, este campo pode ser definido para American Singer . String
entidadeTypeHint Uma lista de pistas que indicam o tipo da entidade. A lista pode conter uma única dica, como Movie ou uma lista de dicas como Place, LocalBusiness, Restaurant. Cada sugestão sucessiva na matriz restringe o tipo da entidade.

Para obter uma lista de tipos possíveis, consulte Os Tipos de Entidade. Se o objeto não incluir este campo, o Genérico é assumido.
Corda[]

Erro

Define o erro que ocorreu.

Elemento Descrição Tipo
código O código de erro que identifica a categoria de erro. Para obter uma lista de códigos possíveis, consulte Códigos de Erro. String
Mensagem Descrição do erro. String
moreDetails Uma descrição que fornece informações adicionais sobre o erro. String
parâmetro O parâmetro de consulta no pedido que causou o erro. String
subCódigo O código de erro que identifica o erro. Por exemplo, se code for InválidaRequest, subCode pode ser ParâmetroInvalid ou ParameterInvalidValue. String
valor O valor do parâmetro de consulta que não era válido. String

Resposta de erros

O objeto de nível superior que a resposta inclui quando o pedido falha.

Name Valor Tipo
_type Tipo dica. String
erros Uma lista de erros que descrevem as razões pelas quais o pedido falhou. Erro[]

Imagem

Define uma imagem.

Nota

Como o formato URL e os parâmetros estão sujeitos a alterações sem aviso prévio, todos os URLs de imagem devem ser utilizados como-é; não deve assumir dependências do formato URL ou parâmetros. A exceção são os parâmetros e valores discutidos por Resize e imagens de miniaturas de cultura.

Name Valor Tipo
altura A altura da imagem de origem, em pixels. Curto sem assinatura
hostPageUrl O URL da página web que inclui a imagem.

Esta URL e contentUrl pode ser a mesma URL.
String
name Uma cadeia de texto opcional que contém informações aleatórias sobre a imagem. String
provedor A fonte da imagem. A matriz conterá um único item.

Deve atribuir a imagem ao fornecedor. Por exemplo, pode apresentar o nome do fornecedor à medida que o cursor paira sobre a imagem ou fazer da imagem um link de clique para o site do fornecedor onde a imagem é encontrada.
Organização[]
miniaturaUrl O URL para uma miniatura da imagem. Para obter informações sobre o redimensionamento da imagem, consulte redimensionar e plantar imagens de miniaturas. String
largura A largura da imagem de origem, em pixels. Curto sem assinatura

Licença

Define a licença segundo a qual o texto ou a foto podem ser utilizados.

Name Valor Tipo
name O nome da licença. String
url O URL para um site onde o utilizador pode obter mais informações sobre a licença.

Use o nome e o URL para criar uma hiperligação.
String

Atribuição de Licenças

Define uma regra contratual para a atribuição de licença.

Name Valor Tipo
_type Uma dica tipo, que está definida para LicenseAttribution. String
license A licença segundo a qual o conteúdo pode ser utilizado. Licença
licençaNotício A licença para visualizar ao lado do campo alvo. Por exemplo, "Texto sob licença CC-BY-SA".

Use o nome e URL da licença no license campo para criar uma hiperligação para o site que descreve os detalhes da licença. Em seguida, substitua o nome da licença na licenseNotice cadeia (por exemplo, CC-BY-SA) pela hiperligação que acabou de criar.
String
mustBeCloseToContent Um valor booleano que determina se o conteúdo da regra deve ser colocado nas proximidades do campo a que a regra se aplica. Se for verdade, o conteúdo deve ser colocado nas proximidades. Se for falso, ou se este campo não existir, o conteúdo pode ser colocado à discrição do autor da chamada. Booleano
targetPropertyName O nome do campo a que a regra se aplica. String

Define os componentes de uma hiperligação.

Name Valor Tipo
_type Tipo dica. String
texto O texto do visor. String
url UMA URL. Utilize o URL e o texto de exibição para criar uma hiperligação. String

LinkAttribution

Define uma regra contratual para a atribuição de ligações.

Name Valor Tipo
_type Uma sugestão tipo, que está definida para LinkAttribution. String
mustBeCloseToContent Um valor booleano que determina se o conteúdo da regra deve ser colocado nas proximidades do campo a que a regra se aplica. Se for verdade, o conteúdo deve ser colocado nas proximidades. Se for falso, ou se este campo não existir, o conteúdo pode ser colocado à discrição do autor da chamada. Booleano
targetPropertyName O nome do campo a que a regra se aplica.

Se um alvo não for especificado, a atribuição aplica-se à entidade como um todo e deve ser exibida imediatamente após a apresentação da entidade. Se existirem várias regras de atribuição de textos e ligações que não especificam um alvo, deve concatená-las e exibi-las utilizando uma etiqueta "Dados de: ". Por exemplo, "Os dados do <nome do fornecedor1 > | <nome do > fornecedor2".
String
texto O texto de atribuição. String
url O URL para o site do fornecedor. Use text e URL para criar hiperligação. String

MediaAttribution

Define uma regra contratual para a atribuição de meios de comunicação.

Name Valor Tipo
_type Uma dica tipo, que é definida para MediaAttribution. String
mustBeCloseToContent Um valor booleano que determina se o conteúdo da regra deve ser colocado nas proximidades do campo a que a regra se aplica. Se for verdade, o conteúdo deve ser colocado nas proximidades. Se for falso, ou se este campo não existir, o conteúdo pode ser colocado à discrição do autor da chamada. Booleano
targetPropertyName O nome do campo a que a regra se aplica. String
url O URL que usa para criar hiperligação do conteúdo dos meios de comunicação. Por exemplo, se o alvo for uma imagem, usaria o URL para tornar a imagem clicável. String

Organização

Define uma editora.

Note que um editor pode fornecer o seu nome ou o seu website ou ambos.

Name Valor Tipo
name O nome da editora. String
url O URL para o site da editora.

Note que o editor não pode fornecer um site.
String

Lugar

Define informações sobre uma entidade local, como um restaurante ou hotel.

Nota

As respostas de Entidades suportam vários mercados, mas a resposta de Locais suporta apenas as localizações de Empresas nos E.U.A.

Name Valor Tipo
_type Dica de tipo, que pode ser definida para uma das seguintes:

  • Hotel
  • Negócios Locais
  • Restaurante
  • String
    address O endereço postal do local onde se encontra a entidade. PostalAddress
    entidadePresentaçãoInfo Informações adicionais sobre a entidade, tais como indícios que pode usar para determinar o tipo da entidade. Por exemplo, seja um restaurante ou hotel. O entityScenario campo está definido para ListItem. EntityPresentationInfo
    name O nome da entidade. String
    telefone O número de telefone da entidade. String
    url O URL para o site da entidade.

    Utilize este URL juntamente com o nome da entidade para criar uma hiperligação que quando clicada leva o utilizador ao website da entidade.
    String
    webSearchUrl O URL do resultado de pesquisa de Bing para este lugar. String

    PostalAddress

    Define um endereço postal.

    Name Valor Tipo
    endereço País O país/região onde se situa o endereço de rua. Este pode ser o código ISO de duas letras (por exemplo, EUA) ou o nome completo (por exemplo, Estados Unidos). String
    endereçoLocalidade A cidade onde se situa o endereço da rua. Por exemplo, Seattle. String
    endereçoRegion O código de estado ou província onde o endereço de rua está localizado. Este pode ser o código de duas letras (por exemplo, WA) ou o nome completo (por exemplo, Washington). String
    bairro O bairro onde está o endereço da rua. Por exemplo, Westlake. String
    código postal O código postal ou código postal onde se encontra o endereço de rua. Por exemplo, 98052. String

    QueryContexto

    Define o contexto de consulta que Bing usou para o pedido.

    Elemento Descrição Tipo
    adultoIntente Um valor Boolean que indica se a consulta especificada tem intenção adulta. O valor é verdadeiro se a consulta tiver intenção adulta; caso contrário, falso . Booleano
    alterationOverrideQuery A cadeia de consulta para usar para forçar Bing a usar a corda original. Por exemplo, se a cadeia de consulta estiver a salar para baixo, a cadeia de consulta de sobreposição será +saling downwind . Lembre-se de codificar a cadeia de consulta que resulta em %2Bsaling+downwind .

    Este campo só está incluído se a cadeia de consulta original contiver um erro ortográfico.
    String
    alteradoQuery A cadeia de consulta utilizada por Bing para realizar a consulta. Bing usa a cadeia de consulta alterada se a cadeia de consulta original contiver erros ortográficos. Por exemplo, se a cadeia de consulta saling downwind for, a cadeia de consulta alterada será sailing downwind .

    Este campo só está incluído se a cadeia de consulta original contiver um erro ortográfico.
    String
    askUserForLocation Um valor Boolean que indica se Bing requer a localização do utilizador para fornecer resultados precisos. Se especificar a localização do utilizador utilizando os cabeçalhos X-MSEdge-ClientIP e X-Search-Location, pode ignorar este campo.

    Para consultas conscientes da localização, como "o tempo de hoje" ou "restaurantes perto de mim" que precisam da localização do utilizador para fornecer resultados precisos, este campo está definido como verdadeiro.

    Para consultas de localização que incluam a localização (por exemplo, "Seattle weather"), este campo está definido como falso . Este campo também é definido como falso para consultas que não estão cientes da localização, como os "best sellers".
    Booleano
    OriginalQuery O string de consulta conforme especificado no pedido. String

    Identificável

    Name Valor Tipo
    ID Um identificador de recursos String

    RankingGroup

    Define um grupo de resultados de pesquisa, como mainline. |Name|Valor|Tipo|
    |-------------|-----------------|----------| |itens|Uma lista de resultados de pesquisa a apresentar no grupo.|RankingItem|

    RankingItem

    Define um item de resultado de pesquisa para visualizar. |Name|Valor|Tipo|
    |-------------|-----------------|----------| |resultadoIndex|Um índice baseado em zero do item na resposta a exibir. Se o artigo não incluir este campo, apresente todos os itens na resposta. Por exemplo, exiba todos os artigos noticiosos na resposta notícia.|Número inteiro| |answerType|A resposta que contém o item a exibir. Por exemplo, notícias.

    Utilize o tipo para encontrar a resposta no objeto SearchResponse. O tipo é o nome de um campo SearchResponse.

    No entanto, utilize o tipo de resposta apenas se este objeto incluir o campo de valor; caso contrário, ignorá-lo.|String| |textualIndex|O índice da resposta em textualAnswers para exibir.| Inteiro não assinado| |valor|O ID que identifica uma resposta a exibir ou um item de resposta a exibir. Se o ID identificar uma resposta, apresente todos os itens da resposta.|Identificável|

    RankingResponse

    Define onde no conteúdo da página de resultados de pesquisa deve ser colocado e em que ordem.

    Name Valor
    mainline Os resultados da pesquisa a exibir na linha principal.
    polo Os resultados da pesquisa que devem ser proporcionados ao tratamento mais visível (por exemplo, exibidos acima da linha principal e da barra lateral).
    barra lateral Os resultados da pesquisa a exibir na barra lateral.

    PesquisaResponse

    Define o objeto de nível superior que a resposta inclui quando o pedido é bem sucedido.

    Note que se o serviço suspeitar de um ataque de negação de serviço, o pedido será bem sucedido (código de estado HTTP é de 200 OK); no entanto, o corpo da resposta estará vazio.

    Name Valor Tipo
    _type Sugestão do tipo, que está definida para SearchResponse. String
    entidades Uma lista de entidades relevantes para a consulta de pesquisa. Entidade
    consultaContexto Um objeto que contém a cadeia de consulta que Bing usou para o pedido.

    Este objeto contém a cadeia de consulta tal como inserida pelo utilizador. Também pode conter uma cadeia de consulta alterada que Bing usou para a consulta se a cadeia de consulta contivesse um erro ortográfico.
    QueryContexto

    Distribuição de texto

    Define uma regra contratual para a atribuição de texto simples.

    Name Valor Tipo
    _type Uma sugestão tipo, que é definida para TextAttribution. String
    texto O texto de atribuição.

    A atribuição de texto aplica-se à entidade como um todo e deve ser exibida imediatamente após a apresentação da entidade. Se existirem várias regras de atribuição de texto ou ligação que não especifiquem um alvo, deve concatená-las e exibi-las utilizando uma etiqueta "Dados de: ".
    String

    Tipos de Entidades

    Esta secção contém as possíveis dicas de entidade. As dicas são agrupadas por categoria de entidades.

    Seguem-se os tipos de entidades base.

    • Genérica
    • Pessoa
    • Lugar
    • Meios de comunicação social
    • Organização

    Seguem-se as indicações da entidade que se enquadram no tipo base Place.

    • Atração
    • City
    • Continente
    • País
    • Hotel
    • Casa
    • Negócios Locais
    • Localização
    • Região Menor
    • Bairro
    • Outro
    • Pontos De interesse
    • PostalCode
    • RadioStation
    • Região
    • Restaurante
    • Estado
    • StreetAddress
    • Sub-Região
    • TuristaAttracção
    • Viagens

    Seguem-se as insinuações da entidade que se enquadram no tipo base Media.

    • Livro
    • Filme
    • Temporada de Televisão
    • Programa de Televisão
    • VideoGame

    Seguem-se as dicas da entidade relacionada com o evento.

    • Evento

    Seguem-se as dicas da entidade relacionada com a profissão.

    • Ator
    • Artista
    • Advogado

    Seguem-se as dicas da entidade relacionada com a educação.

    • CollegeOrUniversity
    • Escola
    • Especialidade

    Seguem-se dicas de entidades não relacionadas.

    • Animal
    • Carro
    • Droga
    • Comida
    • Produto
    • SportsTeam

    Códigos de erro

    Seguem-se os possíveis códigos de estado http que um pedido devolve.

    Código de Estado Descrição
    200 Êxito.
    400 Um dos parâmetros de consulta está em falta ou não é válido.
    401 Falta a chave de subscrição ou não é válida.
    403 O utilizador é autenticado (por exemplo, utilizou uma chave de subscrição válida) mas não tem permissão para o recurso solicitado.

    Bing também pode devolver este estatuto se o chamador exceder as suas consultas por mês.
    410 O pedido utilizou HTTP em vez do protocolo HTTPS. HTTPS é o único protocolo suportado.
    429 O chamador excedeu as suas consultas por segunda quota.
    500 Erro de servidor inesperado.

    Se o pedido falhar, a resposta contém um objeto ErrorResponse, que contém uma lista de objetos error que descrevem o que causou o erro. Se o erro estiver relacionado com parameter um parâmetro, o campo identifica o parâmetro que é o problema. E se o erro estiver relacionado com value um valor de parâmetro, o campo identifica o valor que não é válido.

    {
      "_type": "ErrorResponse", 
      "errors": [
        {
          "code": "InvalidRequest", 
          "subCode": "ParameterMissing", 
          "message": "Required parameter is missing.", 
          "parameter": "q" 
        }
      ]
    }
    
    {
      "_type": "ErrorResponse", 
      "errors": [
        {
          "code": "InvalidAuthorization", 
          "subCode": "AuthorizationMissing", 
          "message": "Authorization is required.", 
          "moreDetails": "Subscription key is not recognized."
        }
      ]
    }
    

    Seguem-se os possíveis códigos de erro e os valores do código de sub-erro.

    Código Subcódigo Descrição
    Error do servidor Erro Inesperado
    Erro de Recursos
    Não Implementado
    O código de estado HTTP é 500.
    Pedido inválido Parâmetros desaparecidos
    ParâmetroSInvalidValue
    Httpnotado
    Bloqueado
    Devoluções Bing InvalidRequest sempre que qualquer parte do pedido não for válida. Por exemplo, falta um parâmetro necessário ou não é válido um valor de parâmetro.

    Se o erro for ParameterMissing ou ParameterInvalidValue, o código de estado HTTP é de 400.

    Se utilizar o protocolo HTTP em vez de HTTPS, bing devolve httpNotAllowed, e o código de estado HTTP é 410.
    RateLimitExceeded Sem subcódigos Bing devolve RateLimitExceeded sempre que excede as suas consultas por segundo (QPS) ou consultas por mês (QPM) quota.

    Se exceder o QPS, bing devolve o código de estado HTTP 429, e se exceder o QPM, bing devolve 403.
    Autorização Inválida Autorização Faltando
    AutorizaçãoRedundy
    Bing devolve InvalidAuthorization quando Bing não pode autenticar o chamador. Por exemplo, Ocp-Apim-Subscription-Key falta o cabeçalho ou a chave de subscrição não é válida.

    O despedimento ocorre se especificar mais do que um método de autenticação.

    Se o erro for InvalidAuthorization, o código de estado HTTP é 401.
    Autorização Insuficiente AutorizaçãoDeficiente
    Autorizações Caducadas
    Bing devolve InsuficienteAutorização quando o chamador não tem permissões para aceder ao recurso. Isto pode ocorrer se a chave de subscrição tiver sido desativada ou tiver expirado.

    Se o erro for insuficiente, o código de estado HTTP é 403.

    Códigos de mercado

    A tabela que se segue lista os valores de código de mercado que pode utilizar para especificar o mkt parâmetro de consulta. Bing devolve conteúdo apenas para estes mercados. A lista está sujeita a alterações.

    Nota

    As respostas de Entidades suportam vários mercados, mas a resposta de Locais suporta apenas as localizações de Empresas nos E.U.A.

    País/Região Linguagem Código de mercado
    Austrália Inglês en-AU
    Canadá Inglês en-CA
    Canadá Francês fr-CA
    França Francês fr-FR
    Alemanha Alemão de-DE
    Índia Inglês en-IN
    Itália Italiano it-IT
    México Espanhol es-MX
    Reino Unido Inglês en-GB
    Estados Unidos da América Inglês en-PT
    Estados Unidos da América Espanhol es-EUA
    Espanha Espanhol es-ES
    Brasil Português pt-BR

    Bing línguas apoiadas

    Seguem-se as línguas apoiadas pelo setLang Bing que pode especificar no parâmetro de consulta. A lista está sujeita a alterações.

    Idiomas Suportados Código do Idioma
    Árabe ar
    Basco eu
    Bengalês bn
    Búlgaro bg
    Catalão ca
    Chinês (Simplificado) zh-hans
    Chinês (Tradicional) zh-hant
    Croata hr
    Checo cs
    Dinamarquês da
    Neerlandês nl
    Inglês en
    Inglês-Reino Unido en-gb
    Estónio et
    Finlandês fi
    Francês fr
    Galego gl
    Alemão de
    Guzerate gu
    Hebraico ele
    Hindi Olá
    Húngaro hu
    Islandês é
    Italiano lo
    Japonês jp
    Canarês kn
    Coreano ko
    Letão lv
    Lituano lt
    Malaio ms
    Malaiala  ml
    Marata mr
    Norueguês (Bokmål) nb
    Polaco pl
    Português (Brasil) pt-br
    Português (Portugal) pt-pt
    Punjabi pa
    Romeno ro
    Russo ru
    Sérvio (Cyrylic) sr.
    Eslovaco sk
    Esloveno sl
    Espanhol es
    Sueco sv
    Tâmil ta
    Telugu te
    Tailandês th
    Turco tr
    Ucraniano Reino Unido
    Vietnamita vi