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

Rozhraní API Bingu pro vyhledávání entit odešle dotaz vyhledávání na Bingu a načte výsledky, které zahrnují entit a místa.The Bing Entity Search API sends a search query to Bing and gets results that include entities and places. Místo výsledky obsahovat restaurace, hotelu 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é lidí, míst (turistických zajímavostí, státy, země atd.) nebo věcí.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, obsahuje odpovědi na vyhledávání QueryContext objektu.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
}

Žádost o entityRequesting entities

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

OdpověďThe response

Odpověď obsahuje SearchResponse objektu.The response contains a SearchResponse object. Pokud Bingu najde entity nebo místo, které se týkají, obsahuje objekt entities pole, places pole 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ě objektu odpovědi neobsahuje buď pole.Otherwise, the response object does not include either field.

Poznámka

Entity odpovědí podporují různé trhy, ale odpověď míst podporuje pouze nám obchodní umístění.Entity responses support multiple markets, but the Places response supports only US Business locations.

entities Pole je EntityAnswer objekt, který obsahuje seznam Entity objekty (najdete v článku value pole).The entities field is an EntityAnswer object that contains a list of Entity objects (see the value field). Seznam může obsahovat jednu entitu dominantní či více entit odstraňování mnohoznačností.The list may contain a single dominant entity, multiple disambiguation entities, or both.

Dominantní entita je entita, která Bingu se řídí zásadou je pouze entity, která splňuje požadavek (nedochází k nejednoznačnosti ohledně toho, která splňuje entita 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 více entit může vyhověli žádosti, seznam obsahuje více než jednu entitu odstraňování mnohoznačností.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 filmu franšízová, pravděpodobně seznam obsahuje entity odstraňování mnohoznačností.For example, if the request uses the generic title of a movie franchise, the list likely contains disambiguation entities. Ale pokud žádost o konkrétní softwarový z franšízová, pravděpodobně seznam obsahuje dominantní jednu 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 například zpěváci objektů actor, sportovců z celého světa, modelů, např.; místa a památek například Rainier připojení nebo Lincoln Památný; a věci, jako je například název banánů, goldendoodle, knihy nebo video.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. EntityPresentationInfo pole obsahuje pomocné parametry, které určují typ entity.The entityPresentationInfo field contains hints that identify the entity's type. Například, pokud je osoba, videa, aby nebo přitažlivosti.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 entitu dominantní a odstraňování mnohoznačností.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"
        }]
    }
}

Obsahuje entitu name, description, a image pole.The entity includes a name, description, and image field. Tato pole se zobrazí v prostředí pro uživatele, musíte je atribut.When you display these fields in your user experience, you must attribute them. contractualRules Pole obsahuje seznam Poděkování, které je nutné použít.The contractualRules field contains a list of attributions that you must apply. Smluvní pravidlo identifikuje pole, které se vztahuje na přidělení.The contractual rule identifies the field that the attribution applies to. Informace o použití attribution najdete v tématu Attribution.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 webSearchUrl pole pro vyhledávání Bingu výsledky stránky obsahující tuto entitu.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.

places Je pole LocalEntityAnswer objekt, který obsahuje seznam místo objekty (najdete v článku value pole).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é odpovídají 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. EntityPresentationInfo pole 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, LocalBusiness, restauraci.The list contains a list of hints such as Place, LocalBusiness, Restaurant. Každý po sobě jdoucích pomocný parametr jako pole způsobí zúžení 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

Entity odpovědí podporují různé trhy, ale odpověď míst podporuje pouze nám obchodní umístění.Entity responses support multiple markets, but the Places response supports only US Business locations.

Entity místní podporou dotazů jako například restaurace poblíž vyžadují podle umístění uživatele poskytnou přesné výsledky.Local aware entity queries such as restaurant near me require the user's location to provide accurate results. Své žádosti vždy používejte X-Search-umístění a hlavičky X-MSEdge ClientIP k určení umístění uživatele.Your requests should always use the X-Search-Location and X-MSEdge-ClientIP headers to specify the user's location. Když se Bingu domnívá, dotaz je výhodná podle umístění uživatele, nastaví askUserForLocation pole QueryContext k true.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
    },
    ...
}

Místo výsledek obsahuje název na místě, adresa, telefonní číslo a adresa URL webu 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 webSearchUrl pole pro vyhledávání Bingu výsledky stránky obsahující tuto entitu.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

Jste nebo třetích stran vaším jménem nemusí použít, zachovat, ukládat, ukládat do mezipaměti, sdílet, nebo distribuovat všechna data z entity rozhraní API pro účely testování, vývoje, školení, distribuci nebo zpřístupnění službám jiných společností než Microsoft nebo funkce.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.

Přidělení datData attribution

Odpovědi rozhraní API Bingu pro Entity obsahují informace, které vlastní třetími stranami.Bing Entity API responses contain information owned by third parties. Budete muset zajistit, aby že využití je vhodná, například při dodržení licence creative commons, které využívají ke svému činnost koncového uživatele.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 contractualRules, attributions, nebo provider polí, musí atribut data.If an answer or result includes the contractualRules, attributions, or provider fields, you must attribute the data. Pokud odpověď nesmí obsahovat žádný z těchto polí, není třeba žádná přiřazení.If the answer does not include any of these fields, no attribution is required. V případě, že odpověď obsahuje contractualRules pole a attributions a/nebo provider polí, musíte použít smluvní pravidla pro atribut data.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 entita, která obsahuje smluvní pravidlo MediaAttribution a bitovou kopii, která zahrnuje provider pole.The following example shows an entity that includes a MediaAttribution contractual rule and an Image that includes a provider field. Pravidlo MediaAttribution označuje obrázek, který jako cíl pravidla, takže by ignorovat na obrázku provider pole a místo toho použít pravidlo MediaAttribution k označení autorství.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 obsahuje smluvní pravidlo targetPropertyName pole, 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 contractualRules pole.Otherwise, the rule applies to the parent object that contains the contractualRules field.

V následujícím příkladu LinkAttribution pravidlo obsahuje targetPropertyName pole, aby se pravidlo vztahuje description pole.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 konkrétní pole musí obsahovat řádek bezprostředně následuje cílových dat, která obsahuje hypertextový odkaz na webu poskytovatele.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. Například kterému budou připsány popis, přidejte řádek bezprostředně následující text, který obsahuje hypertextový odkaz na data na webu poskytovatele, v tomto případě vytvořit 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..."
                 },
            ...

Přiřazení licencíLicense attribution

Pokud obsahuje seznam pravidel smluvní LicenseAttribution pravidlo, je třeba zobrazit oznámení na řádek bezprostředně za obsah, který se vztahuje licence na.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. LicenseAttribution Pravidlo používá targetPropertyName pole pro vlastnost, která se vztahuje licence k identifikaci.The LicenseAttribution rule uses the targetPropertyName field to identify the property that the license applies to.

Následující příklad zobrazuje příklad, který zahrnuje LicenseAttribution pravidlo.The following shows an example that includes a LicenseAttribution rule.

Přiřazení licencí

Licence Všimněte si, že zobrazení musí obsahovat hypertextový odkaz na web, který obsahuje informace o licenci.The license notice that you display must include a hyperlink to the website that contains information about the license. Obvykle vytvořit název licence hypertextový odkaz.Typically, you make the name of the license a hyperlink. Například, pokud je oznámení Text v rámci licence kopie SA a kopie SA je název licence, byste vytvořit kopie 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.

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

Pro atribut zprostředkovatele, přidejte řádek bezprostředně následující obsah, který se použije Poděkování (třeba na cílové pole).To attribute the providers, include a line immediately following the content that the attributions apply to (for example, the targeted field). Označuje, že zprostředkovatelů je zdroj dat by měly být jasně popsány řádku.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 LinkAttribution pravidla, je nutné vytvořit hypertextový odkaz na webu poskytovatele.For LinkAttribution rules, you must create a hyperlink to the provider's website.

Následující příklad zobrazuje příklad, který zahrnuje LinkAttribution a TextAttribution pravidla.The following shows an example that includes LinkAttribution and TextAttribution rules.

Attribution text odkazu

Attribution médiaMedia attribution

Pokud entita obsahuje bitovou kopii a je zobrazit, je nutné zadat odkaz pomocí kliknutí na webu poskytovatele.If the entity includes an image and you display it, you must provide a click-through link to the provider's website. Pokud obsahuje entitu MediaAttribution pravidla, použijte adresu URL pravidla pro vytvoření odkazu pomocí kliknutí.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 adresu URL do image zahrnout provider pole pro vytvoření odkazu pomocí kliknutí.Otherwise, use the URL included in the image's provider field to create the click-through link.

Ukazuje následující příklad, který zahrnuje obrazu provider pole 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 můžete ignorovat na obrázku provider pole a použít MediaAttribution pravidlo.Because the example includes the contractual rule, you ignore the image's provider field and apply the MediaAttribution rule.

Attribution média

Hledání nebo role experience systému jako v hledáníSearch or search-like experience

Stejně jako s rozhraním API webové vyhledávání Bingu, rozhraní API Bingu pro vyhledávání entit se použít jenom jako výsledek dotazu s přímým přístupem uživatele nebo vyhledávání, nebo jako výsledek akce v rámci aplikace nebo prostředí, které logicky může být interpretován jako požadavek hledá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 se následující je několik příkladů přijatelné vyhledávání nebo hledá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 požadavky "Další informace o" nebo "Další informace"User selects specific text or image and requests “more information” or “additional information”
  • Uživatel požádá robota vyhledávání o určitém tématuUser asks a search bot about a particular topic
  • Uživatel dwells na určitý objekt nebo entity ve scénáři typ vizuálního 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žována za hledání podobných prostředí, doporučujeme zkontrolovat, zda se 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 determines the number of queries that you may make per second (QPS). Ujistěte se, že vaše aplikace obsahuje logiku potřebnou k nepřekročení vaší kvóty.You should ensure that your application includes the logic necessary to stay within your quota. Pokud překročíte vaše QPS, požadavek selže se stavovým kódem HTTP 429.If you exceed your QPS, the request fails with HTTP status code 429. Odpověď obsahuje také hlavičku Retry-After, která obsahuje počet sekund, po které se má vyčkat před odesláním dalšího požadavku.The response also includes the Retry-After header, which contains the number of seconds that you should wait before sending another request.

Odepření služby (DOS) a omezeníDenial of Service (DOS) versus Throttling

Služba rozlišuje útoky DOS a porušení QPS.The service differentiates between a DOS attack and QPS violation. Pokud služba má 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ý.If the service suspects a denial of service attack, the request succeeds (HTTP status code is 200 OK); however, the body of the response is empty.

Další postupNext steps

Abyste mohli rychle začít s vaší první žádost, naleznete v tématu provádění svůj první požadavek.To get started quickly with your first request, see Making Your First Request.

Seznamte se s API pro vyhledávání entit Bingu v7 odkaz.Familiarize yourself with the Bing Entity Search API v7 reference. Odkaz obsahuje hlavičky a parametry dotazu, které používáte k vyžádání 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.