Referenční informace k rozhraní API Bingu pro místní obchodní vyhledávání v7
Upozornění
30. října 2020 se rozhraní API Vyhledávání Bingu přesunula ze služeb Azure AI na Vyhledávání Bingu Services. Tato dokumentace je k dispozici pouze pro referenci. Aktualizovanou dokumentaci najdete v dokumentaci k rozhraní API bingu pro vyhledávání. Pokyny k vytváření nových prostředků Azure pro vyhledávání Bingem najdete v tématu Vytvoření prostředku Vyhledávání Bingu prostřednictvím Azure Marketplace.
Rozhraní API pro místní podnikové vyhledávání odesílá vyhledávací dotaz do Bingu, aby získalo výsledky, které zahrnují restaurace, hotely nebo jiné místní firmy. U míst může dotaz zadat název místní firmy nebo kategorii (například restaurace v mém okolí). Mezi výsledky entit patří osoby, místa nebo věci. Místo v tomto kontextu jsou obchodní entity, státy, země/oblasti atd.
Tato část obsahuje technické podrobnosti o objektech odpovědi a parametrech a hlavičce dotazu, které ovlivňují výsledky hledání. Příklady, které ukazují, jak vytvářet požadavky, najdete v tématu Rychlý start pro místní obchodní vyhledávání v jazyce C# nebo Místní obchodní vyhledávání v Javě Rychlý start.
Informace o hlavičkách, které by měly požadavky obsahovat, najdete v tématu Hlavičky.
Informace o parametrech dotazu, které by požadavky měly obsahovat, najdete v tématu Parametry dotazu.
Informace o objektech JSON, které odpověď obsahuje, najdete v tématu Objekty odpovědi.
Informace o povoleném použití a zobrazení výsledků najdete v tématu Požadavky na použití a zobrazení.
Koncový bod
Pokud chcete požádat o místní obchodní výsledky, odešlete požadavek GET na adresu:
https://api.cognitive.microsoft.com/bing/v7.0/localbusinesses/search
Tento požadavek musí používat protokol HTTPS.
Poznámka
Maximální délka adresy URL je 2 048 znaků. Aby délka adresy URL nepřekračovala limit, měla by být maximální délka parametrů dotazu menší než 1 500 znaků. Pokud adresa URL přesahuje 2 048 znaků, server vrátí hodnotu 404 Nenalezena.
Hlavičky
Níže jsou uvedené hlavičky, které může požadavek a odpověď obsahovat.
| Hlavička | Description |
|---|---|
| Přijmout | Nepovinná hlavička požadavku. Výchozí typ média je application/json. Pokud chcete určit, že odpověď bude používat JSON-LD, nastavte hlavičku Accept na application/ld+json. |
| Accept-Language | Nepovinná hlavička požadavku. Čárkami oddělený seznam jazyků pro řetězce uživatelského rozhraní. Seznam je v sestupném pořadí podle priority. Další informace včetně očekávaného formátu najdete v RFC2616. Tato hlavička a parametr dotazu setLang se vzájemně vylučují – nezadávejte obojí. Pokud tuto hlavičku nastavíte, musíte zadat také parametr dotazu cc. K určení trhu, pro který se mají vracet výsledky, Bing použije první podporovaný jazyk, který najde v seznamu, a zkombinuje ho s hodnotou parametru cc. Pokud seznam jazyků podporovaný jazyk neobsahuje, Bing najde nejbližší jazyk a trh, který požadavek podporuje, nebo pro výsledky použije agregovaný nebo výchozí trh. Pokud chcete zjistit, který trh Bing použil, podívejte se do hlavičky BingAPIs-Market.Tuto hlavičku a parametr dotazu cc použijte jenom v případě, že zadáte více jazyků. Jinak použijte parametry dotazu mkt a setLang.Řetězec uživatelského rozhraní je řetězec, který se používá jako popisek v uživatelském rozhraní. V objektech odpovědí JSON je několik řetězců uživatelského rozhraní. Zadaný jazyk použijí všechny odkazy na vlastnosti Bing.com v objektech odpovědi. |
| BingAPIs-Market | Hlavička odpovědi. Trh používaný požadavkem. Formulář je <languageCode-countryCode<>>. Například cs-CZ. |
| BingAPIs-TraceId | Hlavička odpovědi. ID položky protokolu obsahující podrobnosti požadavku. Pokud dojde k chybě, toto ID zachyťte. Pokud problém nedokážete určit a vyřešit, uveďte toto ID spolu s dalšími informacemi, které poskytnete týmu podpory. |
| Ocp-Apim-Subscription-Key | Povinná hlavička požadavku. Klíč předplatného, který jste obdrželi při registraci k této službě ve službách Azure AI. |
| Pragma | Nepovinná hlavička požadavku Ve výchozím nastavení Bing vrátí obsah uložený v mezipaměti, pokud je k dispozici. Abyste Bingu zabránili ve vrácení obsahu uloženého v mezipaměti, hlavičku Pragma nastavte na hodnotu no-cache (například Pragma: no-cache). |
| User-Agent | Nepovinná hlavička požadavku. Uživatelský agent, ze kterého požadavek pochází. Bing používá uživatelského agenta k poskytnutí optimalizovaného prostředí pro mobilní uživatele. I když je tato hlavička nepovinná, doporučujeme ji vždy zadat. Uživatelský agent by měl být stejný řetězec, který odesílá kterýkoli běžně používaný prohlížeč. Informace o uživatelských agentech najdete v RFC 2616. Následují příklady řetězců uživatelského agenta.
|
| X-MSEdge-ClientID | Nepovinná hlavička požadavku a odpovědi Bing tuto hlavičku používá k tomu, aby uživatelům poskytoval konzistentní chování napříč voláními rozhraní API Bingu. Bing často testuje nové funkce a vylepšení a ID klienta používá jako klíč pro přiřazení provozu v různých testovacích verzích. Pokud nepoužíváte stejné ID klienta pro uživatele napříč více požadavky, pak může Bing uživatele přiřadit k více konfliktním testovacím verzím. Přiřazení k více konfliktním testovacím verzím může vést k nekonzistentnímu prostředí pro uživatele. Pokud třeba druhý požadavek má jiné přiřazení k testovací verzi než prví, může být prostředí neočekávané. Bing také může ID klienta použít pro přizpůsobení webových výsledků historii hledání daného ID klienta. Uživatel tak získá bohatší prostředí. Bing také tuto hlavičku používá ke zlepšování hodnocení výsledků díky analýze aktivity generované tímto ID klienta. Zlepšení relevance pomáhá zlepšit kvalitu výsledků poskytovaných rozhraním API Bingu a stejně tak umožňuje vyšší míru prokliků uživatele rozhraní API. DŮLEŽITÉ: I když je tato hlavička nepovinná, měli byste ji považovat za povinnou. Zachování ID klienta mezi více požadavky pro stejnou kombinaci koncového uživatele a zařízení umožňuje 1) aby uživatel rozhraní API získával konzistentní uživatelské prostředí a 2) vyšší míry prokliků díky kvalitnějším výsledkům z rozhraní API Bingu. Následují základní pravidla používání, která se na tuto hlavičku vztahují.
POZNÁMKA: Odpovědi Bingu tuto hlavičku mohou nebo nemusí obsahovat. Pokud odpověď tuto hlavičku obsahuje, ID klienta zachyťte a použijte pro všechny následné požadavky Bingu pro uživatele na tomto zařízení. POZNÁMKA: Pokud zahrnete X-MSEdge-ClientID, nesmíte do požadavku zahrnout soubory cookie. |
| X-MSEdge-ClientIP | Nepovinná hlavička požadavku. Adresa IPv4 nebo IPv6 klientského zařízení. IP adresa se používá ke zjištění polohy uživatele. Bing informace o poloze používá k určení chování bezpečného hledání. POZNÁMKA: I když je tato hlavička nepovinná, doporučujeme ji vždy zadat, stejně jako hlavičku X-Search-Location. Neprovádějte obfuskaci adresy (například změnou posledního oktetu na 0). Obfuskace adresy vede k tomu, že poloha nebude blízko skutečné polohy zařízení. Bing pak může dodávat chybné výsledky. |
| X-Search-Location | Nepovinná hlavička požadavku. Středníky oddělený seznam párů klíč/hodnota, které popisují zeměpisnou polohu klienta. Bing informace o poloze používá k určení chování bezpečného hledání a vracení relevantního místního obsahu. Pár klíč/hodnota zadejte jako <klíč>:<hodnota>. Následují klíče, které se používají k určení polohy uživatele.
POZNÁMKA: Doporučujeme vždy zadat zeměpisnou polohu uživatele. Poskytnutí polohy je zvlášť důležité, pokud IP adresa klienta přesně neodráží fyzickou polohu uživatele (třeba pokud klient používá síť VPN). Pro dosažení optimálních výsledků byste měli zahrnout tuto hlavičku i hlavičku X-MSEdge ClientIP, minimálně ale aspoň tuto hlavičku. |
Poznámka
Nezapomínejte, že podmínky použití vyžadují dodržování příslušných zákonů, včetně těch týkajících se použití těchto hlaviček. Například v určitých jurisdikcích, třeba v Evropě, se před umístěním určitých sledovacích zařízení do zařízení uživatelů požaduje získání souhlasu uživatele.
Parametry dotazů
Požadavek může obsahovat následující parametry dotazu. Požadované parametry najdete ve sloupci Povinné. Parametry dotazu musíte zakódovat pomocí adresy URL.
| Name | Hodnota | Typ | Vyžadováno |
|---|---|---|---|
| Počet | Počet výsledků, které se mají vrátit, počínaje indexem určeným parametrem offset . |
Řetězec | No |
| místníkategorie | Seznam možností, které definují vyhledávání podle obchodních kategorií Zobrazit hledání v kategoriích místních firem | Řetězec | No |
| mkt | Trh, odkud pochází výsledky. Seznam možných hodnot trhu najdete v tématu Kódy trhu. POZNÁMKA: Rozhraní API pro místní obchodní vyhledávání v současné době podporuje pouze trh a jazyk en-us. |
Řetězec | Yes |
| Posun | Index pro spuštění výsledků určený parametrem count . |
Integer | No |
| Q | Hledaný termín uživatele. | Řetězec | No |
| formát odpovědi | Typ média, který se má použít pro odpověď. Níže jsou uvedené možné hodnoty, které nerozlišují malá a velká písmena.
Výchozí hodnota je JSON. Informace o objektech JSON, které odpověď obsahuje, najdete v tématu Objekty odpovědi. Pokud zadáte JsonLd, text odpovědi bude obsahovat objekty JSON-LD, které obsahují výsledky hledání. Informace o JSON-LD najdete v tématu JSON-LD. |
Řetězec | No |
| safeSearch | Filtr, který slouží k filtrování obsahu pro dospělé. Následují možné hodnoty filtru s rozlišováním velkých a malých písmen.
Výchozí hodnota je Moderate. POZNÁMKA: Pokud žádost pochází z trhu, který zásady Bingu pro dospělé vyžadují, aby safeSearch byla nastavená na Striktní, Bing tuto hodnotu ignoruje safeSearch a použije strict.POZNÁMKA: Pokud použijete operátor dotazu site:, je možné, že odpověď bude zahrnovat obsah pro dospělé bez ohledu na nastavení parametru dotazu safeSearch.
site: použijte jenom v případě, že znáte obsah příslušného webu a váš scénář podporuje možnost zobrazení obsahu pro dospělé. |
Řetězec | No |
| setLang | Jazyk, který se má použít pro řetězce uživatelského rozhraní. Jazyk zadejte pomocí dvoupísmenného kódu jazyka ISO 639-1. Například kód jazyka pro češtinu je CS. Výchozí hodnota je EN (angličtina). I když je jazyk volitelný, měli byste ho vždy zadat. Obvykle se setLang nastavuje na stejný jazyk, jaký určuje parametr mkt, pokud uživatel nechce řetězce uživatelského rozhraní zobrazené v jiném jazyce.Tento parametr a hlavička Accept-Language se vzájemně vylučují – nezadávejte obojí. Řetězec uživatelského rozhraní je řetězec, který se používá jako popisek v uživatelském rozhraní. V objektech odpovědí JSON je několik řetězců uživatelského rozhraní. Zadaný jazyk použijí také všechny odkazy na vlastnosti Bing.com v objektech odpovědi. |
Řetězec | No |
Objekty odpovědi
Níže jsou uvedené objekty odpovědi JSON, které může odpověď obsahovat. Pokud je požadavek úspěšný, je objektem nejvyšší úrovně v odpovědi objekt SearchResponse . Pokud požadavek selže, objektem nejvyšší úrovně je objekt ErrorResponse .
| Objekt | Description |
|---|---|
| Místo | Definuje informace o místní firmě, jako je restaurace nebo hotel. |
Chyba
Definuje chybu, ke které došlo.
| Element | Popis | Typ |
|---|---|---|
| Kód | Kód chyby, který identifikuje kategorii chyby. Seznam možných kódů najdete v tématu Kódy chyb. | Řetězec |
| Zprávu | Popis chyby. | Řetězec |
| dalšípodrobné informace | Popis, který poskytuje další informace o chybě. | Řetězec |
| Parametr | Parametr dotazu v požadavku, který způsobil chybu. | Řetězec |
| podkód | Kód chyby, který chybu identifikuje. Například pokud code je InvalidRequest, subCode může být ParameterInvalid nebo ParameterInvalidValue. |
Řetězec |
| Hodnotu | Neplatná hodnota parametru dotazu. | Řetězec |
ChybaResponse
Objekt nejvyšší úrovně, který odpověď zahrnuje, když požadavek selže.
| Name | Hodnota | Typ |
|---|---|---|
| _Typ | Napište nápovědu. | Řetězec |
| Chyby | Seznam chyb, které popisují důvody, proč požadavek selhal. | Chyba[] |
Licence
Definuje licenci, pod kterou může být text nebo fotka použita.
| Name | Hodnota | Typ |
|---|---|---|
| name | Název licence. | Řetězec |
| url | Adresa URL webu, kde uživatel může získat další informace o licenci. K vytvoření hypertextového odkazu použijte název a adresu URL. |
Řetězec |
Odkaz
Definuje komponenty hypertextového odkazu.
| Name | Hodnota | Typ |
|---|---|---|
| _Typ | Napište nápovědu. | Řetězec |
| text | Zobrazovaný text | Řetězec |
| url | Adresa URL. K vytvoření hypertextového odkazu použijte adresu URL a zobrazovaný text. | Řetězec |
Organizace
Definuje vydavatele.
Všimněte si, že vydavatel může zadat svůj název, web nebo obojí.
| Name | Hodnota | Typ |
|---|---|---|
| name | Jméno vydavatele. | Řetězec |
| url | Adresa URL webu vydavatele. Upozorňujeme, že vydavatel nemusí poskytnout web. |
Řetězec |
Místo
Definuje informace o místní firmě, jako je restaurace nebo hotel.
| Name | Hodnota | Typ |
|---|---|---|
| _Typ | Zadejte nápovědu, která může být nastavená na jednu z následujících možností:
|
Řetězec |
| adresa | Poštovní adresa, kde se entita nachází. | PostalAddress |
| entityPresentationInfo | Další informace o entitě, například nápovědy, které můžete použít k určení typu entity. Například jestli se jedná o restauraci nebo hotel. Pole entityScenario je nastavené na ListItem. |
EntityPresentationInfo |
| name | Název entity. | Řetězec |
| Telefonní | Telefonní číslo entity. | Řetězec |
| url | Adresa URL webu entity. Tuto adresu URL použijte spolu s názvem entity k vytvoření hypertextového odkazu, který po kliknutí uživatele přenese na web entity. |
Řetězec |
| adresa URL webového hledání | Adresa URL výsledku hledání Bingu pro toto místo. | Řetězec |
Text dotazu
Definuje kontext dotazu, který Bing použil pro požadavek.
| Element | Popis | Typ |
|---|---|---|
| adultIntent | Logická hodnota, která označuje, jestli má zadaný dotaz záměr pro dospělé. Hodnota je true , pokud má dotaz záměr dospělého; jinak false. | Logická hodnota |
| změnaOverrideQuery | Řetězec dotazu, který se má použít k vynucení, aby Bing použil původní řetězec. Pokud je například řetězec dotazu saling downwind, řetězec dotazu přepsání bude +saling downwind. Nezapomeňte zakódovat řetězec dotazu, jehož výsledkem bude %2Bsaling+downwind. Toto pole je zahrnuto pouze v případě, že původní řetězec dotazu obsahuje pravopisnou chybu. |
Řetězec |
| alteredQuery | Řetězec dotazu, který Bing používá k provedení dotazu. Bing použije změněný řetězec dotazu, pokud původní řetězec dotazu obsahoval pravopisné chyby. Pokud je saling downwindnapříklad řetězec dotazu , změněný řetězec dotazu bude sailing downwind.Toto pole je zahrnuto pouze v případě, že původní řetězec dotazu obsahuje pravopisnou chybu. |
Řetězec |
| askUserForLocation | Logická hodnota, která určuje, jestli Bing vyžaduje polohu uživatele, aby poskytoval přesné výsledky. Pokud jste zadali umístění uživatele pomocí hlaviček X-MSEdge-ClientIP a X-Search-Location , můžete toto pole ignorovat. Pro dotazy s informacemi o poloze, například "dnešní počasí" nebo "restaurace v mém okolí", které k poskytnutí přesných výsledků potřebují polohu uživatele, je toto pole nastaveno na hodnotu true. U dotazů, které tuto polohu obsahují (například "Počasí v Seattlu"), je toto pole nastaveno na hodnotu false. Toto pole je také nastaveno na hodnotu false pro dotazy, které nevědí o umístění, například "best sellers". |
Logická hodnota |
| původní dotaz | Řetězec dotazu zadaný v požadavku. | Řetězec |
Identifikovatelné
| Name | Hodnota | Typ |
|---|---|---|
| id | Identifikátor prostředku | Řetězec |
RankingGroup
Definuje skupinu výsledků hledání, například hlavní řádek.
| Name | Hodnota | Typ |
|---|---|---|
| položky | Seznam výsledků hledání, které se zobrazí ve skupině. | RankingItem |
RankingItem
Definuje položku výsledků hledání, která se má zobrazit.
| Name | Hodnota | Typ |
|---|---|---|
| index výsledku | Index položky v odpovědi, která se má zobrazit od nuly. Pokud položka toto pole neobsahuje, zobrazte všechny položky v odpovědi. Můžete například zobrazit všechny zpravodajské články v odpovědi Příspěvky. | Integer |
| answerType | Odpověď obsahující položku, která se má zobrazit. Například Příspěvky. Pomocí typu vyhledejte odpověď v objektu SearchResponse. Typ je název pole SearchResponse. Typ odpovědi však použijte pouze v případě, že tento objekt obsahuje pole hodnoty; jinak ho ignorujte. |
Řetězec |
| index textual | Index odpovědi v textalAnswers k zobrazení. | Celé číslo bez znaménka |
| hodnota | ID, které identifikuje buď zobrazenou odpověď, nebo položku odpovědi, která se má zobrazit. Pokud ID identifikuje odpověď, zobrazte všechny položky odpovědi. | Identifikovatelné |
RankingResponse
Definuje, kam se má na stránce výsledků hledání umístit obsah a v jakém pořadí.
SearchResponse
Definuje objekt nejvyšší úrovně, který odpověď zahrnuje, když je požadavek úspěšný.
Všimněte si, že pokud má služba podezření na útok dos, požadavek bude úspěšný (stavový kód HTTP je 200 OK). text odpovědi však bude prázdný.
| Name | Hodnota | Typ |
|---|---|---|
| _Typ | Zadejte nápovědu, která je nastavená na SearchResponse. | Řetězec |
| zadá | Seznam entit, které jsou relevantní pro vyhledávací dotaz. | Objekt JSON |
| queryContext | Objekt obsahující řetězec dotazu, který Bing použil pro požadavek. Tento objekt obsahuje řetězec dotazu zadaný uživatelem. Může také obsahovat změněný řetězec dotazu, který bing použil pro dotaz, pokud řetězec dotazu obsahoval pravopisnou chybu. |
Text dotazu |
Kódy chyb
Níže jsou uvedené možné stavové kódy HTTP, které požadavek vrací.
| Stavový kód | Description |
|---|---|
| 200 | Úspěch. |
| 400 | Jeden z parametrů dotazu chybí nebo je neplatný. |
| 401 | Klíč předplatného chybí nebo není platný. |
| 403 | Uživatel je ověřený (například použil platný klíč předplatného), ale nemá oprávnění k požadovanému prostředku. Bing může tento stav vrátit také v případě, že volající překročí svoji měsíční kvótu dotazů. |
| 410 | Požadavek použil místo protokolu HTTPS protokol HTTP. HTTPS je jediný podporovaný protokol. |
| 429 | Volající překročil kvótu dotazů za sekundu. |
| 500 | Neočekávaná chyba serveru. |
Pokud požadavek selže, odpověď obsahuje objekt ErrorResponse , který obsahuje seznam objektů Error , které popisují příčinu chyby. Pokud chyba souvisí s parametrem, parameter identifikuje pole parametr, u kterého dochází k problému. A pokud chyba souvisí s hodnotou parametru value , pole identifikuje neplatnou hodnotu.
{
"_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."
}
]
}
Níže jsou uvedené možné hodnoty kódu chyby a kódu dílčích chyb.
| Kód | Dílčí kód | Description |
|---|---|---|
| Chyba serveru | Neočekávaná chyba Chyba prostředku NotImplemented |
Stavový kód HTTP je 500. |
| Neplatná žádost | ParametrMissing ParametrInvalidValue HttpNotAllowed Blokované |
Bing vrátí InvalidRequest vždy, když některá část požadavku není platná. Například chybí požadovaný parametr nebo hodnota parametru není platná. Pokud je chyba ParameterMissing nebo ParameterInvalidValue, stavový kód HTTP je 400. Pokud místo HTTPS použijete protokol HTTP, vrátí Bing hodnotu HttpNotAllowed a stavový kód HTTP je 410. |
| RateLimitExceeded | Žádné dílčí kódy | Bing vrátí rateLimitExceeded vždy, když překročíte kvótu dotazů za sekundu (QPS) nebo dotazů za měsíc (QPM). Pokud překročíte QPS, vrátí Bing stavový kód HTTP 429, a pokud překročíte QPM, vrátí Bing 403. |
| Neplatná autorizace | AutorizaceMissing AuthorizationRedundancy |
Bing vrátí InvalidAuthorization, když Bing nemůže ověřit volajícího. Například chybí hlavička Ocp-Apim-Subscription-Key nebo klíč předplatného není platný.Redundance nastane, pokud zadáte více než jednu metodu ověřování. Pokud je chyba InvalidAuthorization, stavový kód HTTP je 401. |
| Nedostatečná autorizace | AuthorizationDisabled AuthorizationExpired |
Bing vrátí InsufficientAuthorization, pokud volající nemá oprávnění pro přístup k prostředku. K tomu může dojít v případě, že je klíč předplatného zakázaný nebo vypršela jeho platnost. Pokud je chyba InsufficientAuthorization, stavový kód HTTP je 403. |