您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

项目答案搜索 v7 参考Project Answer Search v7 reference

必应答案搜索 API 在接受一个查询参数后,返回 answerTypefactsentitiessearchResponseBing Answer SearchAPI takes a query parameter and returns a searchResponse with answerType: facts or entities.

使用答案搜索 API 的应用程序通过包含在查询参数中的用于预览的 URL 向终结点发送请求。Applications that use the Answer Search API send requests to the endpoint with a URL to preview in a query parameter. 请求必须包含 q=searchTerm 参数和 Ocp-Apim-Subscription-Key 标头。The request must include the q=searchTerm parameter and Ocp-Apim-Subscription-Key header.

JSON 响应可以针对事实和实体(其中包含有关搜索对象的详细信息)进行分析。The JSON response can be parsed for facts and entities that contain details about the object of search.

终结点Endpoint

若要请求答案搜索结果,请向以下终结点发送请求。To request Answer Search results, send a request to the following endpoint. 使用请求标头和 URL 参数可以定义更多规范。Use the headers and URL parameters to define further specifications.

终结点 GET:Endpoint GET:

https://api.labs.cognitive.microsoft.com/answerSearch/v7.0/search?q=<searchTerm>&subscription-key=0123456789ABCDEF&mkt=en-us

请求必须使用 HTTPS 协议并包括以下查询参数:The request must use the HTTPS protocol and include following query parameter:

  • q=<URL>-用于标识搜索对象的查询q=<URL> - The query that identifies the object of search

如需演示如何发出请求的示例,请参阅 C# 快速入门Java 快速入门For examples that show how to make requests, see C# quickstart or Java quickstart.

以下部分提供的技术详细信息涉及影响搜索结果的响应对象、查询参数和标头。The following sections provide technical details about the response objects, query parameters, and headers that affect the search results.

若要了解请求应包含的标头,请参阅标头For information about headers that requests should include, see Headers.

若要了解请求应包含的查询参数,请参阅查询参数For information about query parameters that requests should include, see Query parameters.

若要了解响应应包含的 JSON 对象,请参阅响应对象For information about the JSON objects that the response includes, see Response objects.

最大查询 URL 长度为 2,048 个字符。The maximum query URL length is 2,048 characters. 为了确保 URL 长度不超出限制,查询参数的最大长度应不到 1,500 个字符。To ensure that your URL length does not exceed the limit, the maximum length of your query parameters should be less than 1,500 characters. 如果 URL 超出 2,048 个字符,服务器会返回“404 未找到”。If the URL exceeds 2,048 characters, the server returns 404 Not found.

若要了解结果的使用和显示有哪些规定,请参阅使用和显示要求For information about permitted use and display of results, see Use and display requirements.

备注

某些对其他搜索 API 有意义的请求标头不影响 URL 预览Some request headers that are meaningful for other search APIs don’t affect URL Preview

  • Pragma - 调用方无法控制 URL 预览是否使用缓存Pragma – the caller does not have control over whether URL Preview uses cache
  • Cache-Control - 调用方无法控制 URL 预览是否使用缓存Cache-Control – the caller does not have control over whether URL Preview uses cache
  • User-AgentUser-Agent

另外,某些参数目前对 URL 预览 API 没有意义,但也许可以在将来用于改进全球化。Also, some parameters are not currently meaningful for URL Preview API, but may be used in the future for improved globalization.

标头Headers

下面是请求和响应可能包含的标头。The following are the headers that a request and response may include.

HeaderHeader 描述Description
接受Accept 可选请求标头。Optional request header.

默认的媒体类型为“application/json”。The default media type is application/json. 若要指定响应使用 JSON-LD,请将 Accept 标头设置为“application/ld+json”。To specify that the response use JSON-LD, set the Accept header to application/ld+json.
Accept-LanguageAccept-Language 可选请求标头。Optional request header.

以逗号分隔的语言列表,用于用户界面字符串。A comma-delimited list of languages to use for user interface strings. 此列表以降序方式显示首选项。The list is in decreasing order of preference. 有关详细信息,包括预期格式,请参阅 RFC2616For more information, including expected format, see RFC2616.

此标头和 setLang 查询参数相互排斥—不可同时指定两者。This header and the setLang query parameter are mutually exclusive—do not specify both.

如果设置此标头,则还必须指定 cc 查询参数。If you set this header, you must also specify the cc query parameter. 为了确定针对哪个市场返回结果,必应使用从列表中找到的第一个受支持语言并将其与 cc 参数值相结合。To determine the market to return results for, Bing uses the first supported language it finds from the list and combines it with the cc parameter value. 如果列表不包括支持的语言,必应会查找最接近的语言和支持请求的市场,或将聚合或默认市场用于结果。If the list does not include a supported language, Bing finds the closest language and market that supports the request or it uses an aggregated or default market for the results. 若要确定必应使用的市场,请查看 BingAPIs-Market 标头。To determine the market that Bing used, see the BingAPIs-Market header.

仅当指定多个语言时,才可使用此标头和 cc 查询参数。Use this header and the cc query parameter only if you specify multiple languages. 否则,请使用 mktsetLang 查询参数。Otherwise, use the mkt and setLang query parameters.

用户界面字符串是用作用户界面中标签的字符串。A user interface string is a string that's used as a label in a user interface. JSON 响应对象中有几个用户界面字符串。There are few user interface strings in the JSON response objects. 响应对象中 Bing.com 属性的任何链接均将应用指定的语言。Any links to Bing.com properties in the response objects apply the specified language.
BingAPIs-MarketBingAPIs-Market 响应标头。Response header.

请求使用的市场。The market used by the request. 形式为 <languageCode>-<countryCode>。The form is <languageCode>-<countryCode>. 例如,en-US。For example, en-US.
BingAPIs-TraceIdBingAPIs-TraceId 响应标头。Response header.

包含请求详细信息的日志条目 ID。The ID of the log entry that contains the details of the request. 发生错误时,捕获此 ID。When an error occurs, capture this ID. 如果无法确定并解决问题,请纳入此 ID 以及提供给支持团队的其他信息。If you are not able to determine and resolve the issue, include this ID along with the other information that you provide the Support team.
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key 必需请求标头。Required request header.

认知服务中注册此服务时收到的订阅密钥。The subscription key that you received when you signed up for this service in Cognitive Services.
PragmaPragma 可选请求标头Optional request header

默认情况下,必应返回缓存的内容(如果适用)。By default, Bing returns cached content, if available. 若要防止必应返回缓存的内容,请将 Pragma 标头设置为 no-cache(例如,Pragma: no-cache)。To prevent Bing from returning cached content, set the Pragma header to no-cache (for example, Pragma: no-cache).
User-AgentUser-Agent 可选请求标头。Optional request header.

发出请求的用户代理。The user agent originating the request. 必应使用用户代理为移动用户提供优化体验。Bing uses the user agent to provide mobile users with an optimized experience. 尽管是可选的,但还是建议始终指定此标头。Although optional, you are encouraged to always specify this header.

user-agent 应该是任何常用浏览器发送的字符串。The user-agent should be the same string that any commonly used browser sends. 有关用户代理的信息,请参阅 RFC 2616For information about user agents, see RFC 2616.

下面是 user-agent 字符串示例。The following are examples of user-agent strings.
  • Windows Phone—Mozilla/5.0(兼容;MSIE 10.0;Windows Phone 8.0;Trident/6.0;IEMobile/10.0;ARM;Touch;NOKIA;Lumia 822)Windows Phone—Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)

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

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

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

  • iPad—Mozilla/5.0(iPad;CPU OS 7_0,如 Mac OS X)AppleWebKit/537.51.1(KHTML,如 Gecko)版本/7.0 Mobile/11A465 Safari/9537.53iPad—Mozilla/5.0 (iPad; CPU OS 7_0 like Mac OS X) AppleWebKit/537.51.1 (KHTML, like Gecko) Version/7.0 Mobile/11A465 Safari/9537.53
X-MSEdge-ClientIDX-MSEdge-ClientID 可选请求和响应标头。Optional request and response header.

必应使用此标头跨必应 API 调用为用户提供一致的行为。Bing uses this header to provide users with consistent behavior across Bing API calls. 必应通常会发布新功能和改进,并将客户端 ID 用作密钥以在不同航班上分配客流量。Bing often flights new features and improvements, and it uses the client ID as a key for assigning traffic on different flights. 如果未跨多个请求将相同的客户端 ID 用于用户,则必应可能将用户分配给多个冲突的航班。If you do not use the same client ID for a user across multiple requests, then Bing may assign the user to multiple conflicting flights. 分配给多个冲突航班可能导致用户体验不一致。Being assigned to multiple conflicting flights can lead to an inconsistent user experience. 例如,如果第二个请求与第一个请求的航班分配不同,体验可能会出现意外。For example, if the second request has a different flight assignment than the first, the experience may be unexpected. 此外,必应可以使用客户端 ID 根据客户端 ID 搜索历史记录来定制 Web 结果,为用户提供更丰富的体验。Also, Bing can use the client ID to tailor web results to that client ID’s search history, providing a richer experience for the user.

通过分析由客户端 ID 生成的活动,必应还会使用此标头来提高结果排名。Bing also uses this header to help improve result rankings by analyzing the activity generated by a client ID. 相关改进有助于提高必应 API 交付的结果质量,从而提高 API 客户的点击率。The relevance improvements help with better quality of results delivered by Bing APIs and in turn enables higher click-through rates for the API consumer.

重要说明:尽管是可选的,但应将此标头视为必需的。IMPORTANT: Although optional, you should consider this header required. 对于同一最终用户和设备组合,如果跨多个请求保留客户端 ID,则 1) API 客户可以获取一致的用户体验;2) 可通过必应 API 提高结果质量,从而提高点击率。Persisting the client ID across multiple requests for the same end user and device combination enables 1) the API consumer to receive a consistent user experience, and 2) higher click-through rates via better quality of results from the Bing APIs.

下面是适用于此标头的基本用法规则。The following are the basic usage rules that apply to this header.
  • 在设备上使用你的应用程序的每个用户必须具有必应生成的唯一客户端 ID。Each user that uses your application on the device must have a unique, Bing generated client ID.

    如果未在请求中包含此标头,必应会生成 ID,然后在 X-MSEdge-ClientID 响应标头中将其返回。If you do not include this header in the request, Bing generates an ID and returns it in the X-MSEdge-ClientID response header. 仅当用户首次在设备上使用应用时,才不可以在请求中包含此标头。The only time that you should NOT include this header in a request is the first time the user uses your app on that device.

  • 针对应用为设备上的此用户生成的每个必应 API 请求,使用客户端 ID。Use the client ID for each Bing API request that your app makes for this user on the device.

  • 注意: 必须确保此客户端 ID 不能链接到任何可以进行身份验证的用户帐户信息。ATTENTION: You must ensure that this Client ID is not linkable to any authenticatable user account information.

  • 保留客户端 ID。Persist the client ID. 若要在浏览器应用中保留 ID,请使用持久性 HTTP Cookie 来确保所有会话均使用此 ID。To persist the ID in a browser app, use a persistent HTTP cookie to ensure the ID is used across all sessions. 请勿使用会话 Cookie。Do not use a session cookie. 对于移动应用等其他应用,请使用设备的持久存储来保留 ID。For other apps such as mobile apps, use the device's persistent storage to persist the ID.

    下次用户在该设备上使用你的应用时,会获取保留的客户端 ID。The next time the user uses your app on that device, get the client ID that you persisted.

注意: 必应响应不一定包含此标头。NOTE: Bing responses may or may not include this header. 如果响应包含此标头,请针对该设备上的用户捕获客户端 ID 并将其用于所有后续必应请求。If the response includes this header, capture the client ID and use it for all subsequent Bing requests for the user on that device.

注意: 如果包含 X-MSEdge-ClientID,不可在请求中包含 Cookie。NOTE: If you include the X-MSEdge-ClientID, you must not include cookies in the request.
X-MSEdge-ClientIPX-MSEdge-ClientIP 可选请求标头。Optional request header.

客户端设备的 IPv4 或 IPv6 地址。The IPv4 or IPv6 address of the client device. IP 地址用于发现用户的位置。The IP address is used to discover the user's location. 必应使用位置信息来确定安全搜索行为。Bing uses the location information to determine safe search behavior.

注意: 尽管是可选的,但还是建议始终指定此标头和 X-Search-Location 标头。NOTE: Although optional, you are encouraged to always specify this header and the X-Search-Location header.

不要混淆地址(例如,通过将最后一个八位字节更改为 0 来混淆地址)。Do not obfuscate the address (for example, by changing the last octet to 0). 混淆地址会导致位置未处于设备实际位置附近,这可能导致必应提供错误的结果。Obfuscating the address results in the location not being anywhere near the device's actual location, which may result in Bing serving erroneous results.
X-Search-LocationX-Search-Location 可选请求标头。Optional request header.

以分号分隔的键/值对列表,描述客户端的地理位置。A semicolon-delimited list of key/value pairs that describe the client's geographical location. 必应使用位置信息来确定安全搜索行为并返回相关的本地内容。Bing uses the location information to determine safe search behavior and to return relevant local content. 以 <键>:<值> 形式指定键/值对。Specify the key/value pair as <key>:<value>. 下面是用于指定用户位置的键。The following are the keys that you use to specify the user's location.

  • lat—客户端位置的纬度,以度为单位。lat—The latitude of the client's location, in degrees. 纬度必须大于或等于 -90.0 且小于或等于 +90.0。The latitude must be greater than or equal to -90.0 and less than or equal to +90.0. 负值表示南纬,正值表示北纬。Negative values indicate southern latitudes and positive values indicate northern latitudes.

  • long—客户端位置的经度,以度为单位。long—The longitude of the client's location, in degrees. 经度必须大于或等于 -180.0 且小于或等于 +180.0。The longitude must be greater than or equal to -180.0 and less than or equal to +180.0. 负值表示西经,正值表示东经。Negative values indicate western longitudes and positive values indicate eastern longitudes.

  • re— 半径(以米为单位),指定坐标的水平准确度。re— The radius, in meters, which specifies the horizontal accuracy of the coordinates. 传递设备定位服务返回的值。Pass the value returned by the device's location service. 典型的值可能是:22m - GPS/Wi-Fi、380m - 蜂窝基站三角网定位、18,000m - 反向 IP 查询。Typical values might be 22m for GPS/Wi-Fi, 380m for cell tower triangulation, and 18,000m for reverse IP lookup.

  • ts— 客户端位于相应位置时的 UTC UNIX 时间戳。ts— The UTC UNIX timestamp of when the client was at the location. (UNIX 时间戳是自 1970 年 1 月 1 日起的秒数。)(The UNIX timestamp is the number of seconds since January 1, 1970.)

  • head—可选。head—Optional. 客户端的相对航向或旅行方向。The client's relative heading or direction of travel. 以度数指定旅行方向(从 0 到 360),相对于正北方向顺时针计数。Specify the direction of travel as degrees from 0 through 360, counting clockwise relative to true north. 如果 sp 键为非零值,则指定此键。Specify this key only if the sp key is nonzero.

  • sp— 客户端设备移动的水平速度(速度),以米/秒为单位。sp— The horizontal velocity (speed), in meters per second, that the client device is traveling.

  • alt— 客户端设备的高度,以米为单位。alt— The altitude of the client device, in meters.

  • are—可选。are—Optional. 半径(以米为单位),指定坐标的垂直准确度。The radius, in meters, that specifies the vertical accuracy of the coordinates. 半径默认为 50 公里。Radius defaults to 50 Kilometers. 只有在指定 alt 键的情况下才指定此键。Specify this key only if you specify the alt key.

注意: 尽管这些键是可选的,但提供的信息越多,位置结果越精确。NOTE: Although these keys are optional, the more information that you provide, the more accurate the location results are.

注意: 建议始终指定用户的地理位置。NOTE: You are encouraged to always specify the user's geographical location. 如果客户端的 IP 地址未准确反映用户的物理位置(例如,如果客户端使用 VPN),则提供位置尤其重要。Providing the location is especially important if the client's IP address does not accurately reflect the user's physical location (for example, if the client uses VPN). 为了获得最佳结果,应包含此标头和 X-MSEdge-ClientIP 标头,但应至少包含此标头。For optimal results, you should include this header and the X-MSEdge-ClientIP header, but at a minimum, you should include this header.

备注

请记住,使用条款要求遵守所有适用的法律,包含这些标头的用法。Remember that the Terms of Use require compliance with all applicable laws, including regarding use of these headers. 例如,在某些管辖区(如欧洲),在用户设备上放置某些跟踪设备之前,需要获得用户同意。For example, in certain jurisdictions, such as Europe, there are requirements to obtain user consent before placing certain tracking devices on user devices.

查询参数Query parameters

请求可以包含以下查询参数。The request may include the following query parameters. 请查看所需参数的“必需”列。See the Required column for required parameters. 必须对查询参数进行 URL 编码。You must URL encode the query parameters.

名称Name Value typeType 必填Required
mktmkt 产生结果的市场。The market where the results come from.

如需获取可能的市场值列表,请参阅“市场代码”。For a list of possible market values, see Market Codes.

注意: URL 预览 API 目前仅支持 en-us(美国英语)市场和语言。NOTE: The URL Preview API currently only supports en-us market and language.

StringString Yes
qq 要预览的 URLThe URL to preview StringString Yes
responseFormatresponseFormat 可用于响应的媒体类型。The media type to use for the response. 下面是可能的不区分大小写的值。The following are the possible case-insensitive values.
  • JSONJSON
  • JSONLDJSONLD

默认值为 JSON。The default is JSON. 若要了解响应应包含的 JSON 对象,请参阅响应对象For information about the JSON objects that the response contains, see Response Objects.

如果指定 JsonLd,则响应正文会包含 JSON-LD 对象,后者包含搜索结果。If you specify JsonLd, the response body includes JSON-LD objects that contain the search results. 有关 JSON-LD 的信息,请参阅 JSON-LDFor information about the JSON-LD, see JSON-LD.
StringString No
safeSearchsafeSearch 用于筛选成人内容的筛选器。A filter used to filter adult content. 下面是可能的不区分大小写的筛选值。The following are the possible case-insensitive filter values.
  • 关闭—返回包含成人文本、图像或视频的网页。Off—Return webpages with adult text, images, or videos.

  • 中等—返回包含成人文本但不包含成人图像或视频的网页。Moderate—Return webpages with adult text, but not adult images or videos.

  • 严格—不返回包含成人文本、图像或视频的网页。Strict—Do not return webpages with adult text, images, or videos.

默认级别为“中等”。The default is Moderate.

注意: 如果请求来自必应成人策略要求将 safeSearch 设置为“严格”的某一市场,必应会忽略 safeSearch 值并使用“严格”。NOTE: If the request comes from a market that Bing's adult policy requires that safeSearch is set to Strict, Bing ignores the safeSearch value and uses Strict.

注意: 如果使用 site: 查询运算符,则不管 safeSearch 查询参数设置如何,仍有可能出现响应中包含成人内容的情况。NOTE: If you use the site: query operator, there is the chance that the response may contain adult content regardless of what the safeSearch query parameter is set to. 只有在知道网站内容且方案允许使用成人内容的情况下,才应使用 site:Use site: only if you are aware of the content on the site and your scenario supports the possibility of adult content.
StringString No
setLangsetLang 可用于用户界面字符串的语言。The language to use for user interface strings. 使用 ISO 639-1 2 字母语言代码指定语言。Specify the language using the ISO 639-1 2-letter language code. 例如,英语的语言代码是 EN。For example, the language code for English is EN. 默认为 EN(英语)。The default is EN (English).

尽管是可选项,但应始终指定语言。Although optional, you should always specify the language. 通常情况下,请将 setLang 设置为 mkt 所指定的语言,除非用户希望以另一语言显示用户界面字符串。Typically, you set setLang to the same language specified by mkt unless the user wants the user interface strings displayed in a different language.

此参数和 Accept-Language 标头相互排斥—不可同时指定两者。This parameter and the Accept-Language header are mutually exclusive—do not specify both.

用户界面字符串是用作用户界面中标签的字符串。A user interface string is a string that's used as a label in a user interface. JSON 响应对象中有几个用户界面字符串。There are few user interface strings in the JSON response objects. 此外,响应对象中 Bing.com 属性的任何链接均会应用指定的语言。Also, any links to Bing.com properties in the response objects apply the specified language.
StringString No

响应对象Response Objects

就像在 Web 搜索 API 中一样,响应架构为 [WebPage] 或 ErrorResponse。The response schema is either a [WebPage] or ErrorResponse, as in the Web Search API. 如果请求失败,则顶级对象为 ErrorResponse 对象。If the request fails, the top-level object is the ErrorResponse object.

ObjectObject 描述Description
[WebPage][WebPage] 包含预览属性的顶级 JSON 对象。Top level JSON object that contains attributes of preview.
[Fact][Fact] 包含事实的顶级 JSON 对象。Top level JSON object that contains facts.
[Entities][Entities 包含实体详细信息的顶级 JSON 对象。Top level JSON object that contains entity details.

ErrorError

定义已发生的错误。Defines the error that occurred.

元素Element 描述Description 类型Type
codecode 用于标识错误类别的错误代码。The error code that identifies the category of error. 如需可能的代码的列表,请参阅错误代码For a list of possible codes, see Error Codes. StringString
messagemessage 对错误的说明。A description of the error. StringString
moreDetailsmoreDetails 一个说明,提供关于错误的其他信息。A description that provides additional information about the error. StringString
parameterparameter 请求中导致错误的查询参数。The query parameter in the request that caused the error. StringString
subCodesubCode 用于标识错误的错误代码。The error code that identifies the error. 例如,如果 code 为 InvalidRequest,则 subCode 可以为 ParameterInvalid 或 ParameterInvalidValue。For example, if code is InvalidRequest, subCode may be ParameterInvalid or ParameterInvalidValue. StringString
valuevalue 查询参数的无效值。The query parameter's value that was not valid. StringString

ErrorResponseErrorResponse

请求失败时响应包含的顶级对象。The top-level object that the response includes when the request fails.

姓名Name Value 类型Type
_type_type 类型提示。Type hint. StringString
errorserrors 错误的列表,用于说明请求失败原因。A list of errors that describe the reasons why the request failed. 错误Error

许可证License

定义文本或照片的使用许可证。Defines the license under which the text or photo may be used.

名称Name ReplTest1Value 类型Type
namename 许可证的名称。The name of the license. StringString
urlurl 为用户提供许可证详细信息的网站的 URL。The URL to a website where the user can get more information about the license.

使用名称和 URL 创建超链接。Use the name and URL to create a hyperlink.
StringString

LicenseAttributionLicenseAttribution

定义许可证属性的协定规则。Defines a contractual rule for license attribution.

名称Name ReplTest1Value 类型Type
_type_type 一种类型提示,设置为 LicenseAttribution。A type hint, which is set to LicenseAttribution. StringString
许可证license 内容使用许可证。The license under which the content may be used. 许可证License
licenseNoticelicenseNotice 将显示在目标字段旁边的许可证。The license to display next to the targeted field. 例如,“文本需 CC-BY-SA 许可证”。For example, "Text under CC-BY-SA license".

license 字段中使用许可证的名称和 URL,以便创建介绍许可证详细信息的网站的超链接。Use the license's name and URL in the license field to create a hyperlink to the website that describes the details of the license. 然后,将 licenseNotice 字符串中的许可证名称(例如 CC-BY-SA)替换为刚创建的超链接。Then, replace the license name in the licenseNotice string (for example, CC-BY-SA) with the hyperlink you just created.
StringString
mustBeCloseToContentmustBeCloseToContent 一个布尔值,确定是否必须将规则的内容置于规则所应用到的字段的附近。A Boolean value that determines whether the contents of the rule must be placed in close proximity to the field that the rule applies to. 如果为 true,则必须将内容置于附近。If true, the contents must be placed in close proximity. 如果为 false,或者此字段不存在,则内容可由调用方随意放置。If false, or this field does not exist, the contents may be placed at the caller's discretion. BooleanBoolean
targetPropertyNametargetPropertyName 规则应用到的字段的名称。The name of the field that the rule applies to. StringString

定义超链接的组件。Defines the components of a hyperlink.

名称Name ReplTest1Value 类型Type
_type_type 类型提示。Type hint. StringString
texttext 显示文本。The display text. StringString
urlurl 一个 URL。A URL. 使用 URL 和显示文本创建超链接。Use the URL and display text to create a hyperlink. StringString

LinkAttributionLinkAttribution

定义链接属性的协定规则。Defines a contractual rule for link attribution.

名称Name ReplTest1Value 类型Type
_type_type 一种类型提示,设置为 LinkAttribution。A type hint, which is set to LinkAttribution. StringString
mustBeCloseToContentmustBeCloseToContent 一个布尔值,确定是否必须将规则的内容置于规则所应用到的字段的附近。A Boolean value that determines whether the contents of the rule must be placed in close proximity to the field that the rule applies to. 如果为 true,则必须将内容置于附近。If true, the contents must be placed in close proximity. 如果为 false,或者此字段不存在,则内容可由调用方随意放置。If false, or this field does not exist, the contents may be placed at the caller's discretion. BooleanBoolean
targetPropertyNametargetPropertyName 规则应用到的字段的名称。The name of the field that the rule applies to.

如果目标未指定,则此属性适用于整个实体,会在实体呈现后立即显示。If a target is not specified, the attribution applies to the entity as a whole and should be displayed immediately following the entity presentation. 如果有多个文本和链接属性规则未指定目标,则应将它们连接起来,并使用“数据来自: ”标签来显示它们。If there are multiple text and link attribution rules that do not specify a target, you should concatenate them and display them using a "Data from: " label. 例如,“数据来自 <提供者名称 1> | <提供者名称 2>”。For example, “Data from <provider name1> | <provider name2>".
StringString
texttext 属性文本。The attribution text. StringString
urlurl 提供者网站的 URL。The URL to the provider's website. 使用 text 和 URL 创建超链接。Use text and URL to create of hyperlink. StringString

MediaAttributionMediaAttribution

定义媒体属性的协定规则。Defines a contractual rule for media attribution.

姓名Name ReplTest1Value 类型Type
_type_type 一种类型提示,设置为 MediaAttribution。A type hint, which is set to MediaAttribution. StringString
mustBeCloseToContentmustBeCloseToContent 一个布尔值,确定是否必须将规则的内容置于规则所应用到的字段的附近。A Boolean value that determines whether the contents of the rule must be placed in close proximity to the field that the rule applies to. 如果为 true,则必须将内容置于附近。If true, the contents must be placed in close proximity. 如果为 false,或者此字段不存在,则内容可由调用方随意放置。If false, or this field does not exist, the contents may be placed at the caller's discretion. BooleanBoolean
targetPropertyNametargetPropertyName 规则应用到的字段的名称。The name of the field that the rule applies to. StringString
urlurl 一种 URL,用于创建媒体内容的超链接。The URL that you use to create of hyperlink of the media content. 例如,如果目标为图像,则可使用此 URL 使图像变得可以单击。For example, if the target is an image, you would use the URL to make the image clickable. StringString

组织Organization

定义发布者。Defines a publisher.

注意,发布者可能提供其名称和/或网站。Note that a publisher may provide their name or their website or both.

名称Name Value typeType
namename 发布者名称。The publisher's name. StringString
urlurl 发布者网站的 URL。The URL to the publisher's website.

请注意,发布者可能未提供网站。Note that the publisher may not provide a website.
StringString

WebPageWebPage

定义预览版网页的信息。Defines information about a the Web page in preview.

名称Name ReplTest1Value typeType
namename 页面标题,不一定是 HTML 标题The page title, not necessarily the HTML title StringString
urlurl 进行了实际爬网的 URL(请求可能已随之进行了重定向)The URL that was actually crawled (request may have followed redirects) StringString
descriptiondescription 对页面和内容的简要说明Brief description of the page and content StringString
isFamilyFriendlyisFamilyFriendly 对 Web 索引中的项来说最准确;实时提取完全根据 URL 而非页面内容来执行此检测Most accurate for items in the web index; realtime fetches do this detection based solely on the URL and not the page content booleanboolean
primaryImageOfPage/contentUrlprimaryImageOfPage/contentUrl 将包括在预览版中的代表性图像的 URLThe URL to a representative image to include in the preview StringString

QueryContextQueryContext

定义必应用于请求的查询上下文。Defines the query context that Bing used for the request.

元素Element 描述Description 类型Type
adultIntentadultIntent 一个布尔值,表示指定的查询是否有成人意向。A Boolean value that indicates whether the specified query has adult intent. 如果查询有成人意向,则此值为 true,否则为 falseThe value is true if the query has adult intent; otherwise, false. BooleanBoolean
alterationOverrideQueryalterationOverrideQuery 一个查询字符串,用于强制必应使用原始字符串。The query string to use to force Bing to use the original string. 例如,如果查询字符串为 saling downwind,则替代查询字符串为 +saling downwindFor example, if the query string is saling downwind, the override query string will be +saling downwind. 记住将查询字符串编码,编码后的字符串为 %2Bsaling+downwindRemember to encode the query string which results in %2Bsaling+downwind.

只有在原始查询字符串包含拼写错误的情况下,才会包含此字段。This field is included only if the original query string contains a spelling mistake.
StringString
alteredQueryalteredQuery 必应用来执行查询的查询字符串。The query string used by Bing to perform the query. 如果原始查询字符串包含拼写错误,必应会使用更改的查询字符串。Bing uses the altered query string if the original query string contained spelling mistakes. 例如,如果查询字符串为 saling downwind,则更改的查询字符串为 sailing downwindFor example, if the query string is saling downwind, the altered query string will be sailing downwind.

只有在原始查询字符串包含拼写错误的情况下,才会包含此字段。This field is included only if the original query string contains a spelling mistake.
StringString
askUserForLocationaskUserForLocation 一个布尔值,指示必应是否需要用户的位置才能提供准确结果。A Boolean value that indicates whether Bing requires the user's location to provide accurate results. 如果已使用 X-MSEdge-ClientIPX-Search-Location 标头指定用户的位置,则可忽略此字段。If you specified the user's location by using the X-MSEdge-ClientIP and X-Search-Location headers, you can ignore this field.

对于需要用户的位置才能提供准确结果的位置感知型查询,例如“今天的天气”或“我附近的餐馆”,此字段设置为 trueFor location aware queries, such as "today's weather" or "restaurants near me" that need the user's location to provide accurate results, this field is set to true.

对于包含位置的位置感知型查询(例如“西雅图的天气”),此字段设置为 falseFor location aware queries that include the location (for example, "Seattle weather"), this field is set to false. 对于非位置感知型查询,例如“最佳销售者”,此字段也设置为 falseThis field is also set to false for queries that are not location aware, such as "best sellers".
BooleanBoolean
originalQueryoriginalQuery 请求中指定的查询字符串。The query string as specified in the request. StringString

IdentifiableIdentifiable

名称Name Value 类型Type
idid 一个资源标识符A resource identifier StringString

RankingGroupRankingGroup

定义搜索结果组,例如 mainline。Defines a search results group, such as mainline.

姓名Name ReplTest1Value 类型Type
项目items 要显示在组中的搜索结果的列表。A list of search results to display in the group. RankingItemRankingItem

RankingItemRankingItem

定义要显示的搜索结果项。Defines a search result item to display.

名称Name Value 类型Type
resultIndexresultIndex 要显示答案中的项的从零开始的索引。A zero-based index of the item in the answer to display. 如果项不包含此字段,则显示答案中的所有项。If the item does not include this field, display all items in the answer. 例如,显示“新闻”答案中的所有新闻文章。For example, display all news articles in the News answer. 整数Integer
answerTypeanswerType 一个答案,包含要显示的项。The answer that contains the item to display. 例如,新闻。For example, News.

使用此类型查找 SearchResponse 对象中的答案。Use the type to find the answer in the SearchResponse object. 此类型是 SearchResponse 字段的名称。The type is the name of a SearchResponse field.

不过,只有在此对象包含值字段的情况下,才使用答案类型;否则,请忽略它。However, use the answer type only if this object includes the value field; otherwise, ignore it.
StringString
textualIndextextualIndex textualAnswers 中要显示的答案的索引。The index of the answer in textualAnswers to display. 无符号整数Unsigned Integer
valuevalue 一个 ID,用于标识要显示的答案或要显示的答案的项。The ID that identifies either an answer to display or an item of an answer to display. 如果此 ID 标识某个答案,则显示该答案的所有项。If the ID identifies an answer, display all items of the answer. IdentifiableIdentifiable

RankingResponseRankingResponse

定义应将内容置于搜索结果页的何处以及应采用什么顺序。Defines where on the search results page content should be placed and in what order.

姓名Name Value
mainlinemainline 要显示在主线中的搜索结果。The search results to display in the mainline.
polepole 要获得最明显的处理(例如,显示在主线和边栏上方)的搜索结果。The search results that should be afforded the most visible treatment (for example, displayed above the mainline and sidebar).
sidebarsidebar 要显示在边栏中的搜索结果。The search results to display in the sidebar.

SearchResponseSearchResponse

定义请求成功时响应包含的顶级对象。Defines the top-level object that the response includes when the request succeeds.

请注意,如果该服务怀疑存在拒绝服务攻击,则请求会成功(HTTP 状态代码为“200 正常”),但响应正文将为空。Note that if the service suspects a denial of service attack, the request will succeed (HTTP status code is 200 OK); however, the body of the response will be empty.

名称Name Value 类型Type
_type_type 一种类型提示,设置为 SearchResponse。Type hint, which is set to SearchResponse. StringString
WebPageWebPage 一个 JSON 对象,用于定义预览版A JSON object that defines the preview stringstring

TextAttributionTextAttribution

定义纯文本属性的协定规则。Defines a contractual rule for plain text attribution.

名称Name ReplTest1Value typeType
_type_type 一种类型提示,设置为 TextAttribution。A type hint, which is set to TextAttribution. StringString
texttext 属性文本。The attribution text.

文本属性适用于整个实体,会在实体呈现后立即显示。Text attribution applies to the entity as a whole and should be displayed immediately following the entity presentation. 如果有多个文本或链接属性规则未指定目标,则应将它们连接起来,并使用“数据来自: ”标签来显示它们。If there are multiple text or link attribution rules that do not specify a target, you should concatenate them and display them using a "Data from: " label.
StringString

错误代码Error codes

下面是请求可能返回的 HTTP 状态代码。The following are the possible HTTP status codes that a request returns.

状态代码Status Code 描述Description
200200 成功。Success.
400400 查询参数之一缺失或无效。One of the query parameters is missing or not valid.
401401 订阅密钥缺失或无效。The subscription key is missing or is not valid.
403403 用户已经过身份验证(例如,用户使用了有效的订阅密钥),但无权访问请求的资源。The user is authenticated (for example, they used a valid subscription key) but they don’t have permission to the requested resource.

如果调用方超出其每月查询配额,必应也可能会返回此状态。Bing may also return this status if the caller exceeded their queries per month quota.
410410 请求使用了 HTTP 而非 HTTPS 协议。The request used HTTP instead of the HTTPS protocol. HTTPS 是唯一支持的协议。HTTPS is the only supported protocol.
429429 调用方超出其每秒查询配额。The caller exceeded their queries per second quota.
500500 意外的服务器错误。Unexpected server error.

如果请求失败,响应会包含一个 ErrorResponse 对象,该对象包含一系列用于描述错误原因的 Error 对象。If the request fails, the response contains an ErrorResponse object, which contains a list of Error objects that describe what caused of error. 如果错误与参数相关,则 parameter 字段会标识导致问题的参数。If the error is related to a parameter, the parameter field identifies the parameter that is the issue. 如果错误与参数值相关,则 value 字段会标识无效的参数值。And if the error is related to a parameter value, the value field identifies the value that is not valid.

{
  "_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."
    }
  ]
}

下面是可能的错误代码和子错误代码值。The following are the possible error code and sub-error code values.

代码Code SubCodeSubCode 描述Description
ServerErrorServerError UnexpectedErrorUnexpectedError
ResourceErrorResourceError
NotImplementedNotImplemented
HTTP 状态代码为 500。HTTP status code is 500.
InvalidRequestInvalidRequest ParameterMissingParameterMissing
ParameterInvalidValueParameterInvalidValue
HttpNotAllowedHttpNotAllowed
阻止Blocked
只要请求的任何部分无效,必应就会返回 InvalidRequest。Bing returns InvalidRequest whenever any part of the request is not valid. 例如,缺少必需参数或参数值无效。For example, a required parameter is missing or a parameter value is not valid.

如果错误是 ParameterMissing 或 ParameterInvalidValue,则 HTTP 状态代码为 400。If the error is ParameterMissing or ParameterInvalidValue, the HTTP status code is 400.

如果使用 HTTP 协议而不是 HTTPS 协议,则必应会返回 HttpNotAllowed,且 HTTP 状态代码为 410。If you use the HTTP protocol instead of HTTPS, Bing returns HttpNotAllowed, and the HTTP status code is 410.
RateLimitExceededRateLimitExceeded 无子代码No sub-codes 每当超过每秒查询数 (QPS) 或每月查询数 (QPM) 配额时,必应都会返回 RateLimitExceeded。Bing returns RateLimitExceeded whenever you exceed your queries per second (QPS) or queries per month (QPM) quota.

如果超过 QPS,则必应会回 HTTP 状态代码 429;如果超过 QPM,则必应会返回 403。If you exceed QPS, Bing returns HTTP status code 429, and if you exceed QPM, Bing returns 403.
InvalidAuthorizationInvalidAuthorization AuthorizationMissingAuthorizationMissing
AuthorizationRedundancyAuthorizationRedundancy
当必应无法验证调用方身份时,必应会返回 InvalidAuthorization。Bing returns InvalidAuthorization when Bing cannot authenticate the caller. 例如,缺少 Ocp-Apim-Subscription-Key 头或订阅密钥无效。For example, the Ocp-Apim-Subscription-Key header is missing or the subscription key is not valid.

如果指定多个身份验证方法,便会发生冗余。Redundancy occurs if you specify more than one authentication method.

如果错误是 InvalidAuthorization,HTTP 状态代码为 401。If the error is InvalidAuthorization, the HTTP status code is 401.
InsufficientAuthorizationInsufficientAuthorization AuthorizationDisabledAuthorizationDisabled
AuthorizationExpiredAuthorizationExpired
当调用方无权访问资源时,必应会返回 InsufficientAuthorization。Bing returns InsufficientAuthorization when the caller does not have permissions to access the resource. 如果订阅密钥已遭禁用或到期,就会发生此类错误。This can occur if the subscription key has been disabled or has expired.

如果错误是 InsufficientAuthorization,HTTP 状态代码为 403。If the error is InsufficientAuthorization, the HTTP status code is 403.

后续步骤Next steps