Co je Vyhledávání entit Bingu?What is Bing Entity Search?

Rozhraní API Bingu pro vyhledávání entit odešle vyhledávací dotaz do Bingu a načte výsledky, které zahrnují entity a místa.The Bing Entity Search API sends a search query to Bing and gets results that include entities and places. Mezi místa patří například restaurace, hotely nebo jiné místní firmy.Place results include restaurants, hotel, or other local businesses. Bing vrátí místa, pokud dotaz určuje název místní firmy nebo vyzve k zadání typu podniku (například restaurace v okolí).Bing returns places if the query specifies the name of the local business or asks for a type of business (for example, restaurants near me). Bing vrátí entity, pokud dotaz specifikuje dobře známé osobnosti, místa (turistické zajímavosti, státy, země atd.) nebo věci.Bing returns entities if the query specifies well-known people, places (tourist attractions, states, countries, etc.), or things.

Navrhování a používání hledaných termínůSuggesting & using search terms

Pokud nabízíte vyhledávací pole, do kterého může uživatel zadat hledaný termín, můžete hledání vylepšit s využitím rozhraní API pro automatické návrhy Bingu.If you provide a search box where the user enters their search term, use the Bing Autosuggest API to improve the experience. Toto rozhraní API vrací navrhované řetězce dotazů na základě částečné shody hledaných termínů zadávaných uživatelem.The API returns suggested query strings based on partial search terms as the user types.

Jakmile uživatel zadá hledaný termín, před nastavením parametru dotazu q zakódujte termín s použitím kódování URL.After the user enters their search term, URL encode the term before setting the q query parameter. Například, pokud uživatel zadá Marcus Appel, nastavte q k Marcus + Appel nebo Marcus % 20Appel.For example, if the user enters Marcus Appel, set q to Marcus+Appel or Marcus%20Appel.

Pokud hledaný výraz obsahuje chybu pravopisu, odpověď na vyhledávání obsahuje objektQueryContext.If the search term contains a spelling mistake, the search response includes a QueryContext object. Objekt zobrazí původní pravopis a opravený pravopis použitý pro vyhledávání Bingu.The object shows the original spelling and the corrected spelling that Bing used for the search.

"queryContext": {
    "originalQuery": "hollo wrld",
    "alteredQuery": "hello world",
    "alterationOverrideQuery": "+hollo wrld",
    "adultIntent": false
}

Požadavky na entityRequesting entities

Příklad požadavku naleznete v tématu vytváření prvního požadavku.For an example request, see Making your first request.

OdpověďThe response

Odpověď obsahuje objektSearchResponse.The response contains a SearchResponse object. Pokud Bing najde relevantní entitu nebo místo, obsahuje objekt pole entities, pole places nebo obojí.If Bing finds an entity or place that's relevant, the object includes the entities field, places field, or both. V opačném případě objekt odpovědi neobsahuje žádné pole.Otherwise, the response object does not include either field.

Poznámka

Odpovědi na entity podporují různé trhy, ale odpovědi na místa podporují pouze obchodní místa v USA.Entity responses support multiple markets, but the Places response supports only US Business locations.

Pole entities je objekt EntityAnswer, který obsahuje seznam objektůEntity (viz pole value).The entities field is an EntityAnswer object that contains a list of Entity objects (see the value field). Seznam může obsahovat jednu dominantní entitu nebo více nejednoznačných entit nebo obojí.The list may contain a single dominant entity, multiple disambiguation entities, or both.

Dominantní entita je entita, o které se Bing domnívá, že je jedinou entitou, která vyhovuje požadavku (nedochází k nejednoznačnosti ohledně toho, která entita vyhovuje požadavku).A dominant entity is an entity that Bing believes is the only entity that satisfies the request (there is no ambiguity as to which entity satisfies the request). Pokud může žádosti vyhovět více entit, seznam obsahuje více než jednu nejednoznačnou entitu.If multiple entities could satisfy the request, the list contains more than one disambiguation entity. Například pokud požadavek používá obecný název filmové franšízy, seznam pravděpodobně obsahuje nejednoznačné entity.For example, if the request uses the generic title of a movie franchise, the list likely contains disambiguation entities. Pokud však požadavek specifikuje konkrétní název franšízy, seznam pravděpodobně obsahuje jednu dominantní entitu.But, if the request specifies a specific title from the franchise, the list likely contains a single dominant entity.

Entity obsahují dobře známé osobnosti jako jsou zpěváci, herci, sportovci, modelky atd. Také obsahují místa a památky jako je Mount Rainier nebo Lincoln Memorial a věci jako banán, goldendoodle, kniha nebo název filmu.Entities include well-known personalities such as singers, actors, athletes, models, etc.; places and landmarks such as Mount Rainier or Lincoln Memorial; and things such as a banana, goldendoodle, book, or movie title. Pole EntityPresentationInfo obsahuje pomocné parametry, které určují typ entity.The entityPresentationInfo field contains hints that identify the entity's type. Například, jestli se jedná o osobu, film, zvíře nebo atrakci.For example, if it's a person, movie, animal, or attraction. Seznam možných typů najdete v tématu typy entitFor a list of possible types, see Entity Types

"entityPresentationInfo": {
    "entityScenario": "DominantEntity",
    "entityTypeHints": ["Attraction"],
    "entityTypeDisplayHint": "Mountain"
}, ...

Následující příklad zobrazuje odpověď, která obsahuje dominantní a nejednoznačnou entitu.The following shows a response that includes a dominant and disambiguation entity.

{
    "_type": "SearchResponse",
    "queryContext": {
        "originalQuery": "Mount Rainier"
    },
    "entities": {
        "value": [{
            "contractualRules": [{
                "_type": "ContractualRules/LicenseAttribution",
                "targetPropertyName": "description",
                "mustBeCloseToContent": true,
                "license": {
                    "name": "CC-BY-SA",
                    "url": "http://creativecommons.org/licenses/by-sa/3.0/"
                },
                "licenseNotice": "Text under CC-BY-SA license"
            },
            {
                "_type": "ContractualRules/LinkAttribution",
                "targetPropertyName": "description",
                "mustBeCloseToContent": true,
                "text": "contoso.com",
                "url": "http://contoso.com/mount_rainier"
            },
            {
                "_type": "ContractualRules/MediaAttribution",
                "targetPropertyName": "image",
                "mustBeCloseToContent": true,
                "url": "http://contoso.com/mount-rainier"
            }],
            "webSearchUrl": "https://www.bing.com/search?q=Mount%20Rainier...",
            "name": "Mount Rainier",
            "url": "http://www.northwindtraders.com/",
            "image": {
                "name": "Mount Rainier",
                "thumbnailUrl": "https://www.bing.com/th?id=A4ae343983daa4...",
                "provider": [{
                    "_type": "Organization",
                    "url": "http://contoso.com/mount_rainier"
                }],
                "hostPageUrl": "http://contoso.com/commons/7/72/mount_rain...",
                "width": 110,
                "height": 110
            },
            "description": "Mount Rainier is 14,411 ft tall and the highest mountain...",
            "entityPresentationInfo": {
                "entityScenario": "DominantEntity",
                "entityTypeHints": ["Attraction"]
            },
            "bingId": "38b9431e-cf91-93be-0584-c42a3ecbfdc7"
        },
        {
            "contractualRules": [{
                "_type": "ContractualRules/MediaAttribution",
                "targetPropertyName": "image",
                "mustBeCloseToContent": true,
                "url": "http://contoso.com/mount_rainier_national_park"
            }],
            "webSearchUrl": "https://www.bing.com/search?q=Mount%20Rainier%20National...",
            "name": "Mount Rainier National Park",
            "url": "http://worldwideimporters.com/",
            "image": {
                "name": "Mount Rainier National Park",
                "thumbnailUrl": "https://www.bing.com/th?id=A91bdc5a1b648a695a39...",
                "provider": [{
                    "_type": "Organization",
                    "url": "http://contoso.com/mount_rainier_national_park"
                }],
                "hostPageUrl": "http://contoso.com/en/7/7a...",
                "width": 50,
                "height": 50
            },
            "description": "Mount Rainier National Park is a United States National Park...",
            "entityPresentationInfo": {
                "entityScenario": "DisambiguationItem",
                "entityTypeHints": ["Organization"]
            },
            "bingId": "29d4b681-227a-3924-7bb1-8a54e8666b8c"
        }]
    }
}

Entita obsahuje pole name, description a image.The entity includes a name, description, and image field. Pokud zobrazíte tato pole ve svém uživatelském prostředí, musíte jim přiřadit zdroj.When you display these fields in your user experience, you must attribute them. Pole contractualRules obsahuje seznam atribucí, které musíte použít.The contractualRules field contains a list of attributions that you must apply. Smluvní pravidlo identifikuje pole, na které se vztahuje pravidlo pro atribuci.The contractual rule identifies the field that the attribution applies to. Informace uplatnění atribuce najdete v tématu Atribuce.For information about applying attribution, see Attribution.

"contractualRules": [{
    "_type": "ContractualRules/LicenseAttribution",
    "targetPropertyName": "description",
    "mustBeCloseToContent": true,
    "license": {
        "name": "CC-BY-SA",
        "url": "http://creativecommons.org/licenses/by-sa/3.0/"
    },
    "licenseNotice": "Text under CC-BY-SA license"
},
{
    "_type": "ContractualRules/LinkAttribution",
    "targetPropertyName": "description",
    "mustBeCloseToContent": true,
    "text": "contoso.com",
    "url": "http://contoso.com/wiki/Mount_Rainier"
},
{
    "_type": "ContractualRules/MediaAttribution",
    "targetPropertyName": "image",
    "mustBeCloseToContent": true,
    "url": "http://contoso.com/wiki/Mount_Rainier"
}], ...

Při zobrazení informací o entitách (název, popis a obrázek), musíte taky použít adresu URL v poli webSearchUrl, abyste propojili entitu se stránkou výsledků vyhledávání Bingu, které danou entitu obsahují.When you display the entity information (name, description, and image), you must also use the URL in the webSearchUrl field to link to the Bing search results page that contains the entity.

Pole places je objekt LocalEntityAnswer, který obsahuje seznam objektů Place (viz pole value).The places field is a LocalEntityAnswer object that contains a list of Place objects (see the value field). Seznam obsahuje jeden nebo více místních entit, které vyhovují požadavku.The list contains one or more local entities that satisfy the request.

Místa zahrnují restaurace, hotely nebo místní firmy.Places include restaurant, hotels, or local businesses. Pole EntityPresentationInfo obsahuje pomocné parametry, které určují typ místní entity.The entityPresentationInfo field contains hints that identify the local entity's type. Seznam obsahuje seznam pomocných parametrů, jako je místo, místní firma nebo restaurace.The list contains a list of hints such as Place, LocalBusiness, Restaurant. Každý další použitý pomocný parametr zužuje možnosti typu entity.Each successive hint in the array narrows the entity's type. Seznam možných typů najdete v tématu typy entitFor a list of possible types, see Entity Types

"entityPresentationInfo": {
    "entityScenario": "ListItem",
    "entityTypeHints": ["Place",
    "LocalBusiness",
    "Restaurant"]
}, ...

Poznámka

Odpovědi na entity podporují různé trhy, ale odpovědi na místa podporují pouze obchodní místa v USA.Entity responses support multiple markets, but the Places response supports only US Business locations.

Dotazy na místní entity v okolí jako například restaurace poblíž vyžadují zadání polohy uživatele, aby mohly poskytnout přesné výsledky.Local aware entity queries such as restaurant near me require the user's location to provide accurate results. K určení polohy uživatele byste měli pro své žádosti vždy využívat záhlaví X-Search-Location a X-MSEdge ClientIP.Your requests should always use the X-Search-Location and X-MSEdge-ClientIP headers to specify the user's location. Pokud se Bing domnívá, že je pro dotaz výhodné určení polohy uživatele, nastaví askUserForLocation pole QueryContext na hodnotu true(pravda).If Bing thinks the query would benefit from the user's location, it sets the askUserForLocation field of QueryContext to true.

{
    "_type": "SearchResponse",
    "queryContext": {
        "originalQuery": "Sinful Bakery and Cafe",
        "askUserForLocation": true
    },
    ...
}

Výsledek místa obsahuje jméno místa, adresu, telefonní číslo a adresu URL na web dané entity.A place result includes the place's name, address, telephone number, and URL to the entity's website. Při zobrazení informací o entitách musíte taky použít adresu URL v poli webSearchUrl, abyste propojili entitu se stránkou výsledků vyhledávání Bingu, které danou entitu obsahují.When you display the entity information, you must also use the URL in the webSearchUrl field to link to the Bing search results page that contains the entity.

"places": {
    "value": [{
        "_type": "Restaurant",
        "webSearchUrl": "https://www.bing.com/search?q=Sinful%20Bakery...",
        "name": "Liberty's Delightful Sinful Bakery & Cafe",
        "url": "http://libertysdelightfulsinfulbakeryandcafe.com/",
        "entityPresentationInfo": {
            "entityScenario": "ListItem",
            "entityTypeHints": ["Place",
            "LocalBusiness",
            "Restaurant"]
        },
        "address": {
            "addressLocality": "Seattle",
            "addressRegion": "WA",
            "postalCode": "98112",
            "addressCountry": "US",
            "neighborhood": "Madison Park"
        },
        "telephone": "(800) 555-1212"
    }]
}

Poznámka

Vy nebo třetí strana jednající vaším jménem nesmí používat, uchovávat, ukládat, ukládat do mezipaměti, sdílet, nebo distribuovat jakákoliv data z rozhraní API entit pro účely testování, vývoje, školení, distribuce nebo zpřístupnění službám nebo funkcím jiných společností než Microsoft.You, or a third party on your behalf, may not use, retain, store, cache, share, or distribute any data from the Entities API for the purpose of testing, developing, training, distributing or making available any non-Microsoft service or feature.

Atribuce datData attribution

Odpovědi rozhraní API Bingu pro entity obsahují informace vlastněné třetími stranami.Bing Entity API responses contain information owned by third parties. Je vaší zodpovědností zajistit odpovídající použití, například tím, že budete v souladu s licencemi Creative Commons, na které můžou vaši uživatelé spoléhat.You are responsible to ensure your use is appropriate, for example by complying with any creative commons license your user experience may rely on.

Pokud odpověď nebo výsledek obsahuje pole contractualRules, attributions, nebo provider, musíte provést atribuci dat.If an answer or result includes the contractualRules, attributions, or provider fields, you must attribute the data. Pokud odpověď neobsahuje žádné z těchto polí, není atribuce potřeba.If the answer does not include any of these fields, no attribution is required. Pokud odpověď obsahuje pole contractualRules a pole attributions nebo provider, musíte použít smluvní pravidla pro atribuci dat.If the answer includes the contractualRules field and the attributions and/or provider fields, you must use the contractual rules to attribute the data.

Následující příklad ukazuje entitu, která obsahuje smluvní pravidlo MediaAttribution a Image zahrnující poleprovider.The following example shows an entity that includes a MediaAttribution contractual rule and an Image that includes a provider field. Pravidlo MediaAttribution označuje image jako cíl pravidla, takže v takovém případě ignorujte pole provider image a místo toho použijte k atribuci pravidlo MediaAttribution.The MediaAttribution rule identifies the image as the target of the rule, so you'd ignore the image's provider field and instead use the MediaAttribution rule to provide attribution.

"value": [{
    "contractualRules": [
        ...
        {
            "_type": "ContractualRules/MediaAttribution",
            "targetPropertyName": "image",
            "mustBeCloseToContent": true,
            "url": "http://contoso.com/mount_rainier"
        }
    ],
    ...
    "image": {
        "name": "Mount Rainier",
        "thumbnailUrl": "https://www.bing.com/th?id=A46378861201...",
        "provider": [{
            "_type": "Organization",
            "url": "http://contoso.com/mount_rainier"
        }],
        "hostPageUrl": "http://www.graphicdesigninstitute.com/Uploaded...",
        "width": 110,
        "height": 110
    },
    ...
}]

Pokud smluvní pravidlo obsahuje pole targetPropertyName, pak se pravidlo vztahuje pouze na cílové pole.If a contractual rule includes the targetPropertyName field, the rule applies only to the targeted field. V opačném případě se pravidlo vztahuje na nadřazený objekt, který obsahuje pole contractualRules.Otherwise, the rule applies to the parent object that contains the contractualRules field.

V následujícím příkladu pravidloLinkAttribution obsahuje pole targetPropertyName, takže se pravidlo vztahuje na pole description.In the following example, the LinkAttribution rule includes the targetPropertyName field, so the rule applies to the description field. Pro pravidla, která se vztahují na určitá pole, musíte vložit řádek bezprostředně za cílová data, který bude obsahovat hypertextový odkaz na web zprostředkovatele.For rules that apply to specific fields, you must include a line immediately following the targeted data that contains a hyperlink to the provider's website. Pokud budete například provádět atribuci popisu, vložte bezprostředně za text popisu řádek, který bude obsahovat hypertextový odkaz na data na webu zprostředkovatele, v tomto případě vytvořte odkaz na contoso.com.For example, to attribute the description, include a line immediately following the description text that contains a hyperlink to the data on the provider's website, in this case create a link to contoso.com.

"entities": {
    "value": [{
            ...
            "description": "Marcus Appel is a former American....",
            ...
            "contractualRules": [{
                    "_type": "ContractualRules/LinkAttribution",
                    "targetPropertyName": "description",
                    "mustBeCloseToContent": true,
                    "text": "contoso.com",
                    "url": "http://contoso.com/cr?IG=B8AD73..."
                 },
            ...

Atribuce licencíLicense attribution

Pokud obsahuje seznam smluvních pravidel pravidlo LicenseAttribution, musíte uvést poznámku na řádek bezprostředně za obsah, na který se licence vztahuje.If the list of contractual rules includes a LicenseAttribution rule, you must display the notice on the line immediately following the content that the license applies to. PravidloLicenseAttribution používá pole targetPropertyName k identifikaci předmětu vlastnictví, na které se licence vztahuje.The LicenseAttribution rule uses the targetPropertyName field to identify the property that the license applies to.

Následující příklad ukazuje použití pravidlaLicenseAttribution.The following shows an example that includes a LicenseAttribution rule.

Atribuce licencí

Poznámky k licencím, které uvádíte, musí obsahovat hypertextový odkaz na web obsahující informace o dané licenci.The license notice that you display must include a hyperlink to the website that contains information about the license. Obvykle vytvoříte z názvu licence hypertextový odkaz.Typically, you make the name of the license a hyperlink. Pokud je například poznámka Text je pod licencí CC-BY-SA a CC-BY-SA je název licence, uděláte z CC-BY-SA hypertextový odkaz.For example, if the notice is Text under CC-BY-SA license and CC-BY-SA is the name of the license, you would make CC-BY-SA a hyperlink.

Pravidla LinkAttribution a TextAttribution se obvykle používají k identifikaci zprostředkovatele dat.The LinkAttribution and TextAttribution rules are typically used to identify the provider of the data. Pole targetPropertyName určuje pole, na které se pravidlo vztahuje.The targetPropertyName field identifies the field that the rule applies to.

Pro určení zdroje zprostředkovatelů, vložte řádek bezprostředně za obsah,na který se určení zdroje vztahuje (například za cílové pole).To attribute the providers, include a line immediately following the content that the attributions apply to (for example, the targeted field). Řádek by měl jasně označovat, že zdrojem dat jsou zprostředkovatelé.The line should be clearly labeled to indicate that the providers are the source of the data. Například „Data z: contoso.com“.For example, "Data from: contoso.com". Pro pravidla LinkAttribution musíte vytvořit hypertextový odkaz na web zprostředkovatele.For LinkAttribution rules, you must create a hyperlink to the provider's website.

Následující příklad ukazuje použití pravidel LinkAttribution a TextAttribution.The following shows an example that includes LinkAttribution and TextAttribution rules.

Atribuce odkazu a textu

Atribuce médiíMedia attribution

Pokud entita obsahuje image a vy ji zobrazujete, musíte zadat klikací odkaz na web zprostředkovatele.If the entity includes an image and you display it, you must provide a click-through link to the provider's website. Pokud entita obsahuje pravidloMediaAttribution, použijte k vytvoření klikacího odkazu adresu URL pravidla.If the entity includes a MediaAttribution rule, use the rule's URL to create the click-through link. V opačném případě použijte k vytvoření klikacího odkazu adresu URL, která je v poliprovider dané image.Otherwise, use the URL included in the image's provider field to create the click-through link.

Zde je příklad, který obsahuje pole provider image a smluvní pravidla.The following shows an example that includes an image's provider field and contractual rules. Tento příklad zahrnuje smluvní pravidlo, a proto budete ignorovat pole provider image a použijete pravidlo MediaAttribution.Because the example includes the contractual rule, you ignore the image's provider field and apply the MediaAttribution rule.

Atribuce médií

Vyhledávací a vyhledávání podobná prostředíSearch or search-like experience

Stejně jako u rozhraní API Bingu pro vyhledávání na webu, rozhraní API Bingu pro vyhledávání entit je možné použít jenom jako výsledek přímého dotazu nebo vyhledávání uživatele, nebo jako výsledek akce v rámci aplikace nebo prostředí, která může být logicky interpretovaná jako požadavek vyhledávání uživatele.Just like with Bing Web Search API, the Bing Entity Search API may only be used as a result of a direct user query or search, or as a result of an action within an app or experience that logically can be interpreted as a user’s search request. Pro ilustraci jsou tady uvedené některé příklady přijatelných vyhledávacích a vyhledávání podobných prostředí.For illustration purposes, the following are some examples of acceptable search or search-like experiences.

  • Uživatel zadá dotaz přímo do vyhledávacího pole v aplikaciUser enters a query directly into a search box in an app
  • Uživatel vybere určitý text nebo obrázek a zadá požadavek „více informací“ nebo „další informace“User selects specific text or image and requests “more information” or “additional information”
  • Uživatel se zeptá vyhledávacího robota na určité témaUser asks a search bot about a particular topic
  • Uživatel spočívá na určitém objektu nebo entitě při použití vizuálního typu vyhledáváníUser dwells on a particular object or entity in a visual search type scenario

Pokud si nejste jistí, jestli vaše prostředí může být považované za vyhledávání podobné prostředí, doporučujeme, abyste se obrátili na společnost Microsoft.If you are not sure if your experience can be considered a search-like experience, it is recommended that you check with Microsoft.

Omezování požadavkůThrottling requests

Služba a typ vašeho předplatného určuje počet dotazů, které můžete provést za sekundu (QPS).The service and your subscription type determine the number of queries per second (QPS) that you can make. Ujistěte se, že vaše aplikace obsahuje logiku potřebnou k nepřekročení vaší kvóty.Make sure your application includes the logic to stay within your quota. Při dosažení nebo překročení limitu QPS požadavek selže a vrátí se stavový kód HTTP 429.If the QPS limit is met or exceeded, the request fails and an HTTP 429 status code is returned. Odpověď zahrnuje hlavičku Retry-After, která označuje, jak dlouho je nutné počkat před odesláním dalšího požadavku.The response includes the Retry-After header, which indicates how long you must wait before sending another request.

Odepření služby a omezováníDenial-of-service versus throttling

Služba rozlišuje mezi útokem s cílem odepření služby (DoS) a porušením QPS.The service makes a differentiation between a denial-of-service (DoS) attack and a QPS violation. Pokud služba má podezření na útok DoS, požadavek bude úspěšný (stavový kód HTTP je 200 OK).If the service suspects a DoS attack, the request succeeds (HTTP status code is 200 OK). Text odpovědi však bude prázdný.However, the body of the response is empty.

Další krokyNext steps

Pokud chcete rychle začít s vaším prvním požadavkem, projděte si popis vytvoření prvního požadavku.To get started quickly with your first request, see Making Your First Request.

Seznamte se s referenčními informacemi k rozhraní API Bingu pro vyhledávání entit v7.Familiarize yourself with the Bing Entity Search API v7 reference. Tyto referenční informace obsahují záhlaví a parametry dotazů, které můžete použít při odesílání požadavků na výsledky hledání.The reference contains the headers and query parameters that you use to request search results. Obsahují také definice objektů odpovědi.It also includes definitions of the response objects.

Pokud chcete zlepšit uživatelské prostředí vyhledávacího pole, přečtěte si o rozhraní API pro automatické návrhy Bingu.To improve your search box user experience, see Bing Autosuggest API. Zatímco uživatel zadává termín dotazu, můžete zavoláním tohoto rozhraní API získat relevantní termíny dotazů, které použili jiní uživatelé.As the user enters their query term, you can call this API to get relevant query terms that were used by others.

Nezapomeňte si přečíst požadavky Bingu na zobrazení a použití, abyste neporušili žádná pravidla používání výsledků hledání.Be sure to read Bing Use and Display Requirements so you don't break any of the rules about using the search results.