使用 Bing 實體 API 搜尋實體Searching for entities with the Bing Entity API

使用 Bing 自動建議 API 建議搜尋字詞Suggest search terms with the Bing Autosuggest API

若您提供使用者可在其中輸入其搜尋字詞的搜尋方塊,請使用 Bing 自動建議 API 來改善使用經驗。If you provide a search box where the user enters their search term, use the Bing Autosuggest API to improve the experience. API 會根據部分搜尋字詞傳回建議的查詢字串,作為使用者類型。The API returns suggested query strings based on partial search terms as the user types.

在使用者輸入其搜尋字詞之後,URL 會先將此字詞編碼,再設定 q 查詢參數。After the user enters their search term, URL encode the term before setting the q query parameter. 例如,若使用者輸入 Marcus Appel,請將 q 設定為 Marcus+AppelMarcus%20AppelFor example, if the user enters Marcus Appel, set q to Marcus+Appel or Marcus%20Appel.

若搜尋字詞包含拼字錯誤,搜尋回應會包含 QueryContext 物件。If the search term contains a spelling mistake, the search response includes a QueryContext object. 物件會顯示 Bing 用於搜尋的原始拼字和已更正的拼字。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
}

Bing 實體搜尋 API 回應The Bing Entity Search API response

API 回應包含 SearchResponse 物件。The API response contains a SearchResponse object. 若 Bing 找到相關的實體或地點,物件會包含 entities 欄位、places 欄位或兩者。If Bing finds an entity or place that's relevant, the object includes the entities field, places field, or both. 否則,回應物件不包含任一欄位。Otherwise, the response object does not include either field.

注意

實體回應支援多個市場,但地點回應支援僅美國公司地點。Entity responses support multiple markets, but the Places response supports only US Business locations.

entities 欄位是包含 Entity 物件清單的 EntityAnswer 物件 (請參閱 value 欄位)。The entities field is an EntityAnswer object that contains a list of Entity objects (see the value field). 此清單可能包含單一主控實體、多個去除混淆實體或兩者。The list may contain a single dominant entity, multiple disambiguation entities, or both.

當 Bing 認定有符合要求的唯一實體時 (確知哪個實體符合要求,沒有模稜兩可的情況),就會傳回主控實體。A dominant entity is returned when Bing believes it to be the only entity that satisfies the request (there is no ambiguity as to which entity satisfies the request). 若可能有多個實體符合要求,清單會包含多個去除混淆實體。If multiple entities could satisfy the request, the list contains more than one disambiguation entity. 例如,若要求使用電影系列的通用標題,清單可能會包含去除混淆實體。For example, if the request uses the generic title of a movie franchise, the list likely contains disambiguation entities. 但若要求指定系列中的特定標題,清單可能會包含單一主控實體。But, if the request specifies a specific title from the franchise, the list likely contains a single dominant entity.

實體包含已知的名人,例如歌手、演員、運動員、模特兒等;地點和地標,例如瑞尼爾山和林肯紀念堂;以及事項,例如香蕉、黃金貴賓犬、書籍或電影標題。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 欄位包含識別實體類型的提示。The entityPresentationInfo field contains hints that identify the entity's type. 例如,若它是人物、電影、動物或景點。For example, if it's a person, movie, animal, or attraction. 如需可能類型的清單,請參閱 Entity Types (實體類型)For a list of possible types, see Entity Types

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

以下顯示包含主控和去除混淆實體的回應。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": "https://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"
        }]
    }
}

此實體包含 namedescriptionimage 欄位。The entity includes a name, description, and image field. 當您在使用者體驗中顯示這些欄位時,您必須屬性化這些欄位。When you display these fields in your user experience, you must attribute them. contractualRules 欄位包含您必須套用的屬性清單。The contractualRules field contains a list of attributions that you must apply. 契約規則會識別套用屬性的欄位。The contractual rule identifies the field that the attribution applies to. 如需套用屬性的資訊,請參閱屬性For information about applying attribution, see Attribution.

"contractualRules": [{
    "_type": "ContractualRules/LicenseAttribution",
    "targetPropertyName": "description",
    "mustBeCloseToContent": true,
    "license": {
        "name": "CC-BY-SA",
        "url": "https://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"
}], ...

當您顯示實體資訊 (名稱、描述和影像) 時,您也必須使用 webSearchUrl 欄位中的 URL 連結至包含實體的 Bing 搜尋結果頁面。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.

尋找地點Find places

places 欄位是包含 Place 物件清單的 LocalEntityAnswer 物件 (如需詳細資訊,請參閱 實體類型 欄位)。The places field is a LocalEntityAnswer object that contains a list of Place objects (see the Entity Types for more information). 清單包含一或多個符合要求的本地實體。The list contains one or more local entities that satisfy the request.

地點包含餐廳、旅館或本地商家。Places include restaurant, hotels, or local businesses. entityPresentationInfo 欄位包含識別本地實體類型的提示。The entityPresentationInfo field contains hints that identify the local entity's type. 清單包含地點、本地商家、餐廳等提示清單。The list contains a list of hints such as Place, LocalBusiness, Restaurant. 陣列中的每個後續提示都會縮小實體的類型。Each successive hint in the array narrows the entity's type. 如需可能類型的清單,請參閱 Entity Types (實體類型)For a list of possible types, see Entity Types

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

注意

實體回應支援多個市場,但地點回應支援僅美國公司地點。Entity responses support multiple markets, but the Places response supports only US Business locations.

本地感知實體查詢 (例如「我附近的餐廳」**) 需要使用者的位置以提供精確的結果。Local aware entity queries such as restaurant near me require the user's location to provide accurate results. 您的要求應該一律使用 X-Search-Location 和 X-MSEdge-ClientIP 標頭來指定使用者的位置。Your requests should always use the X-Search-Location and X-MSEdge-ClientIP headers to specify the user's location. 若 Bing 認為使用者的位置對查詢有利,則會將 QueryContextaskUserForLocation 欄位設定為 trueIf 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
    },
    ...
}

地點結果包含地點的名稱、地址、電話號碼和實體網站的 URL。A place result includes the place's name, address, telephone number, and URL to the entity's website. 當您顯示實體資訊時,您也必須使用 webSearchUrl 欄位中的 URL 連結至包含實體的 Bing 搜尋結果頁面。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"
    }]
}

注意

您或代表您的第三方可能無法使用、保留、儲存、快取、共用或散發實體 API 的任何資料,以進行測試、開發、訓練、散發或提供給任何非 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.

資料屬性Data attribution

Bing 實體 API 回應包含第三方所擁有的資訊。Bing Entity API responses contain information owned by third parties. 您會負責確定使用適當,例如遵守任何您使用者體驗可能依賴的 Creative Commons 授權。You are responsible to ensure your use is appropriate, for example by complying with any creative commons license your user experience may rely on.

若回應或結果包含 contractualRulesattributionsprovider 欄位,您必須屬性化資料。If an answer or result includes the contractualRules, attributions, or provider fields, you must attribute the data. 若回應不包含上述任何欄位,則不需要任何屬性。If the answer does not include any of these fields, no attribution is required. 若回應包含 contractualRules 欄位以及 attributions 和/或 provider 欄位,您必須使用契約規則來屬性化資料。If the answer includes the contractualRules field and the attributions and/or provider fields, you must use the contractual rules to attribute the data.

下列範例顯示包含 MediaAttribution 契約規則的實體,以及包含 provider 欄位的影像。The following example shows an entity that includes a MediaAttribution contractual rule and an Image that includes a provider field. MediaAttribution 規則會識別影像作為規則的目標,因此您會忽略影像的 provider 欄位,並改用 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
    },
    ...
}]

若契約規則包含 targetPropertyName 欄位,該規則只會套用至目標欄位。If a contractual rule includes the targetPropertyName field, the rule applies only to the targeted field. 否則,該規則會套用至包含 contractualRules 欄位的父物件。Otherwise, the rule applies to the parent object that contains the contractualRules field.

在下列範例中,LinkAttribution 規則包含 targetPropertyName 欄位,因此該規則會套用至 description 欄位。In the following example, the LinkAttribution rule includes the targetPropertyName field, so the rule applies to the description field. 針對套用至特定欄位的規則,您必須在目標資料之後立即加入一行,其中包含提供者網站的超連結。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. 例如,若要屬性化描述,請在描述文字之後立即加入一行,其中包含提供者網站的超連結。在本例中,請建立 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..."
                 },
            ...
  

授權屬性License attribution

若契約規則清單包含 LicenseAttribution 規則,您必須在緊接於套用授權之內容後面的該行上顯示通知。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 規則使用 targetPropertyName 欄位來識別套用授權的屬性。The LicenseAttribution rule uses the targetPropertyName field to identify the property that the license applies to.

以下示範內含 LicenseAttribution 規則的範例。The following shows an example that includes a LicenseAttribution rule.

授權屬性

您顯示的授權通知必須包括網站的超連結,其中包含授權的相關資訊。The license notice that you display must include a hyperlink to the website that contains information about the license. 一般而言,您會將授權名稱設為超連結。Typically, you make the name of the license a hyperlink. 例如,若通知是 CC-BY-SA 授權文字,而 CC-BY-SA 是授權名稱,您會將 CC-BY-SA 設為超連結。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.

LinkAttributionTextAttribution 規則通常可用來識別資料的提供者。The LinkAttribution and TextAttribution rules are typically used to identify the provider of the data. targetPropertyName 欄位會識別套用規則的欄位。The targetPropertyName field identifies the field that the rule applies to.

若要屬性化提供者,請在套用屬性的內容 (例如目標欄位) 之後立即加入一行。To attribute the providers, include a line immediately following the content that the attributions apply to (for example, the targeted field). 該行應該清楚標示,指出提供者是資料的來源。The line should be clearly labeled to indicate that the providers are the source of the data. 例如,"Data from: contoso.com"。For example, "Data from: contoso.com". 針對 LinkAttribution 規則,您必須建立提供者網站的超連結。For LinkAttribution rules, you must create a hyperlink to the provider's website.

以下示範內含 LinkAttributionTextAttribution 規則的範例。The following shows an example that includes LinkAttribution and TextAttribution rules.

連結文字屬性

媒體屬性Media attribution

若實體包含影像,而且您會顯示該影像,您必須提供提供者網站的點選連結。If the entity includes an image and you display it, you must provide a click-through link to the provider's website. 若實體包含 MediaAttribution 規則,請使用規則的 URL 建立點選連結。If the entity includes a MediaAttribution rule, use the rule's URL to create the click-through link. 否則,請使用包含在影像 provider 欄位中的 URL 建立點選連結。Otherwise, use the URL included in the image's provider field to create the click-through link.

以下示範內含影像 provider 欄位和契約規則的範例。The following shows an example that includes an image's provider field and contractual rules. 由於範例包含契約規則,因此您會忽略影像的 provider 欄位並套用 MediaAttribution 規則。Because the example includes the contractual rule, you ignore the image's provider field and apply the MediaAttribution rule.

媒體屬性

搜尋或類似搜尋體驗Search or search-like experience

如同使用 Bing Web 搜尋 API,Bing 實體搜尋 API 只能作為直接使用者查詢或搜尋的結果,或是作為邏輯上可解譯為使用者搜尋要求之應用程式或體驗內的動作結果。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. 為了方便說明,以下是可接受之搜尋或類似搜尋體驗的一些範例。For illustration purposes, the following are some examples of acceptable search or search-like experiences.

  • 使用者直接在應用程式的搜尋方塊中輸入查詢User enters a query directly into a search box in an app
  • 使用者選取特定文字或影像,並要求「更多資訊」或「其他資訊」User selects specific text or image and requests “more information” or “additional information”
  • 使用者詢問搜尋 Bot 特定主題的相關資訊User asks a search bot about a particular topic
  • 使用者詳述圖像式搜尋類型案例中的特定物件或實體User dwells on a particular object or entity in a visual search type scenario

若您不確定您的體驗是否可視為類似搜尋體驗,建議您與 Microsoft 確認。If you are not sure if your experience can be considered a search-like experience, it is recommended that you check with Microsoft.

節流要求Throttling requests

服務與您的訂用帳戶類型將決定您所適用的每秒查詢數目 (QPS)。The service and your subscription type determine the number of queries per second (QPS) that you can make. 請確定您的應用程式包含維持在配額範圍內所需的邏輯。Make sure your application includes the logic to stay within your quota. 如果已達到或超過 QPS 限制,要求即會失敗,且會傳回 HTTP 429 狀態碼。If the QPS limit is met or exceeded, the request fails and an HTTP 429 status code is returned. 回應會包含 Retry-After 標頭,指出您必須等待多久後才能傳送另一個要求。The response includes the Retry-After header, which indicates how long you must wait before sending another request.

拒絕服務與節流Denial-of-service versus throttling

服務會區分拒絕服務 (DoS) 攻擊和 QPS 違規。The service makes a differentiation between a denial-of-service (DoS) attack and a QPS violation. 如果服務懷疑有 DoS 攻擊,要求仍會成功 (HTTP 狀態碼為「200 確定」),If the service suspects a DoS attack, the request succeeds (HTTP status code is 200 OK). 但回應本文會是空的。However, the body of the response is empty.

後續步驟Next steps

  • 嘗試透過快速入門開始使用 Bing 實體搜尋 API 來搜尋實體。Try a Quickstart to get started searching for entities with the Bing Entity Search API.