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

警告

必应搜索 API 将从认知服务迁移到 必应搜索服务Bing Search APIs are moving from Cognitive Services to Bing Search Services. 在接下来的三年中,将支持使用认知服务进行预配的必应搜索 API,或者在企业协议结束后(以先发生者为准)。Bing Search APIs provisioned using Cognitive Services will be supported for the next three years or until the end of your Enterprise Agreement, whichever happens first.

有关迁移说明,请参阅 必应搜索服务For migration instructions, see Bing Search Services.

拼写检查 API v7 参考Spell Check API v7 reference

拼写检查 API 允许您检查文本字符串中的拼写和语法错误。The Spell Check API lets you check a text string for spelling and grammar errors. 本部分提供有关查询参数和用于请求拼写检查的标头以及包含结果的 JSON 响应对象的技术详细信息。This section provides technical details about the query parameters and headers that you use to request spell checking, and the JSON response objects that contain the results. 有关演示如何发出请求的示例,请参阅 拼写检查文本字符串For examples that show how to make requests, see Spell check a text string.

有关请求应包括的标头的信息,请参阅 请求标头For information about the headers that requests should include, see Request Headers.

有关请求应包括的查询参数的信息,请参阅 查询参数For information about the query parameters that requests should include, see Query Parameters.

有关响应可能包含的 JSON 对象的信息,请参阅 Response 对象For information about the JSON objects that the response may include, see Response Objects.

有关允许的使用和显示结果的信息,请参阅 必应搜索 API 使用和显示要求For information about permitted use and display of results, see Bing Search API Use and Display requirements.

备注

由于 URL 格式和参数可能会在未另行通知的情况下有所更改,请按现状使用所有 URL。Because URL formats and parameters are subject to change without notice, use all URLs as-is. 不应依赖于 URL 格式或参数,除非另有说明。You should not take dependencies on the URL format or parameters except where noted.

终结点Endpoints

若要检查文本块的拼写和语法,请将 GET 或 POST 请求发送到:To check the spelling and grammar of a block of text, send a GET or POST request to:

https://api.cognitive.microsoft.com/bing/v7.0/SpellCheck

请求必须使用 HTTPS 协议。The request must use the HTTPS protocol.

由于查询字符串长度限制,你通常会使用 POST 请求,除非你只检查短字符串。Because of the query string length limit, you typically use a POST request unless you're checking only short strings.

对于多服务订阅,必须在 URL 中包含区域。For multi-service subscriptions, you must include the region in the URL. 例如: westus.api.cognitive.microsoft.com。For example: westus.api.cognitive.microsoft.com. 请参阅 支持的区域See Supported Regions.

备注

最大 URL 长度为 2,048 个字符。The maximum 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.

请求标头Request headers

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

HeaderHeader 说明Description
AcceptAccept 可选请求标头。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.

如果指定市场 代码中未列出的市场,此值可能不同于在 有关 查询参数中指定的市场。If you specify a market that is not listed in Market Codes, this value may differ from the market you specified in the mkt query parameter. 如果为无法协调的 "抄送" 和 " 接受语言 " 指定值,则这一点同样适用。The same is true if you specify values for cc and Accept-Language that can't be reconciled.
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-) 。To prevent cached content, set the Pragma header to no-cache (for example, Pragma: no-cache).
重试-之后Retry-After 响应标头。Response header.

如果超过了每秒 (QPS) 或每月 (QPM) 允许的查询数,则响应包括此标头。The response includes this header if you exceed the number of queries allowed per second (QPS) or per month (QPM). 标头包含在发送其他请求之前必须等待的秒数。The header contains the number of seconds that you must wait before sending another request.
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.

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

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

  • 保留客户端 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. 将键/值对指定为 <key> : <value> 。Specify the key/value pair as <key>:<value>. 下面是用于指定用户位置的键。The following are the keys that you use to specify the user's location.

  • lat—必需。lat—Required. 客户位置的纬度,以度为单位。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—Required. 客户位置的经度,以度为单位。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—Required. 半径(以米为单位),指定坐标的水平准确性。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—可选。ts—Optional. 客户位于相应位置时的 UTC UNIX 时间戳。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—Optional. 客户设备移动的水平速度(速度),以米/秒为单位。The horizontal velocity (speed), in meters per second, that the client device is traveling.

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

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

  • 为 — 可选。disp—Optional. 用户的地理位置,格式为: <City、State>。The user’s geographic location in the form, disp:<City, State>. 例如,在华盛顿州的西雅图。For example, disp:Seattle, Washington. 这是使用 lat/long 键指定的用户位置的显示文本版本。This is the display text version of the user’s location that you specified using the lat/long keys. 如果此值与 lat/长坐标冲突,必应使用 "指示" 值作为用户的位置。If this value conflicts with the lat/long coordinates, Bing uses the disp value as the user's location.

注意: 如果查询包含位置,必应忽略此标头。NOTE: Bing ignores this header if the query includes a location. 例如,如果此标头将用户的位置反映为旧金山,但该查询是 餐馆西雅图,必应返回位于华盛顿州西雅图的餐厅。For example, if this header reflects the user’s location as San Francisco, but the query is restaurants seattle, Bing returns restaurants located in Seattle, Washington.

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

注意:**** 尽管是可选的,但还是建议始终指定用户的地理位置。NOTE: Although optional, 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). 为获得最佳结果,应包括此标头和 ClientIP 标头,但至少应包括此标头。For optimal results, you should include this header and the X-Search-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 following are the query parameters that the request may include. “必需”列指示是否必须指定参数 。The Required column indicates whether you must specify the parameter. 必须对查询参数值进行 URL 编码。You must URL encode the query parameter values.

名称Name Value 类型Type 必须Required
actionTypeactionType 一个字符串,该字符串由日志记录用于确定请求是来自交互式会话还是页面负载。A string that's used by logging to determine whether the request is coming from an interactive session or a page load. 下面是可能的值。The following are the possible values.
  • 编辑 — 请求来自交互式会话Edit—The request is from an interactive session
  • —从页面加载加载请求Load—The request is from a page load
StringString No
appNameappName 应用的唯一名称。The unique name of your app.

名称必须是必应的名称。The name must be known by Bing. 不要包含此参数,除非你之前已联系 Bing 获取唯一的应用名称。Do not include this parameter unless you have previously contacted Bing to get a unique app name. 若要获取唯一名称,请与必应商业开发经理联系。To get a unique name, contact your Bing Business Development manager.
StringString No
cccc 结果来源的国家/地区的 2 个字符国家/地区代码。A 2-character country code of the country where the results come from. 有关可能值的列表,请参阅 市场代码For a list of possible values, see Market Codes.

如果设置此参数,则还必须指定 Accept-language 标头。If you set this parameter, you must also specify the Accept-Language header. 必应使用它在指定语言中找到的第一个受支持的语言,并将其与国家/地区代码组合在一起,以确定要为其返回结果的市场。Bing uses the first supported language it finds in the specified languages and combines it with the country code to determine the market to return results for. 如果语言列表不包括支持的语言,必应会查找最接近的语言和支持请求的市场。If the languages list does not include a supported language, Bing finds the closest language and market that supports the request. 或者,必应为结果使用聚合或默认市场。Or, Bing may use an aggregated or default market for the results.

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

此参数和 mkt 查询参数相互排斥—不可同时指定两者。This parameter and the mkt query parameter are mutually exclusive—do not specify both.
StringString No
clientMachineNameclientMachineName 发出请求的设备的唯一名称。A unique name of the device that the request is being made from. 为每个设备生成一个唯一值 (值不重要) 。Generate a unique value for each device (the value is unimportant).

服务使用该 ID 来帮助调试问题并改善更正质量。The service uses the ID to help debug issues and improve the quality of corrections.
StringString No
docIddocId 标识文本所属文档的唯一 ID。A unique ID that identifies the document that the text belongs to. 为每个文档生成唯一值 (值不重要) 。Generate a unique value for each document (the value is unimportant).

服务使用该 ID 来帮助调试问题并改善更正质量。The service uses the ID to help debug issues and improve the quality of corrections.
StringString No
mktmkt 产生结果的市场。The market where the results come from. 通常, mkt 是用户从中发出请求的国家/地区。Typically, mkt is the country where the user is making the request from. 但是,如果用户不在必应提供结果的国家/地区,则可能是一个不同的国家/地区。However, it could be a different country if the user is not located in a country where Bing delivers results. 市场必须采用形式 <language code> - <country code> 。The market must be in the form <language code>-<country code>. 例如,en-US。For example, en-US. 字符串不区分大小写。The string is case insensitive. 如需可能的市场值的列表,请参阅市场代码For a list of possible market values, see Market Codes.

注意: 如果已知,则建议您始终指定市场。NOTE: If known, you are encouraged to always specify the market. 指定市场有助于必应路由请求,并返回适当的最佳响应。Specifying the market helps Bing route the request and return an appropriate and optimal response. 如果你指定了 市场代码中未列出的市场,必应根据可能更改的内部映射使用最适合的市场代码。If you specify a market that is not listed in Market Codes, Bing uses a best fit market code based on an internal mapping that is subject to change.

此参数和 cc 查询参数相互排斥—不可同时指定两者。This parameter and the cc query parameter are mutually exclusive—do not specify both.
StringString No
mode 要执行的拼写和语法检查的类型。The type of spelling and grammar checks to perform. 下面是值 () 不区分大小写的可能值。The following are the possible values (the values are case insensitive). 默认值为 ProofThe default is Proof.
  • Proof - 适用于文档方案—Proof - for documents scenario—
    • Proof 拼写模式提供最广泛的检查,可以添加大写、基本标点符号和其他功能,帮助用户创建文档。The Proof spelling mode provides the most comprehensive checks, adding capitalization, basic punctuation, and other features to aid document creation. 但它仅在 en-us (英语-美国) 、es (西班牙语) 、pt-BR (葡萄牙) 市场 (注意:仅适用于西班牙语和葡萄牙语) 的 beta 版本。but it's available only in the en-US (English-United States), es-ES(Spanish), pt-BR(Portuguese) markets (Note: just beta version for Spanish and Portuguese). 对于所有其他市场,请将 mode 查询参数设置为 Spell。For all other markets, set the mode query parameter to Spell.

      注意: 如果查询文本的长度超过4096,则将其截断为4096个字符,然后进行处理。NOTE: If the length of query text exceeds 4096, it will be truncated to 4096 characters, then get processed.


  • Spell - 适用于 Web 搜索/查询方案—Spell - for web searches/queries scenario—
    • "拼写" 更积极地返回更好的搜索结果。‘Spell’ is more aggressive in order to return better search results. 拼写模式查找大多数拼写错误,但找不到某些证明捕获的语法错误,例如,大小写和重复单词。The Spell mode finds most spelling mistakes but doesn't find some of the grammar errors that Proof catches, for example, capitalization and repeated words.

      注意: 支持的最大查询长度如下所示。NOTE: The max query length supported is as below. 如果查询超出界限,则从结果看来,查询似乎并没有更改。If query exceed the bound, the result appears that the query is not altered.
      • 65 字符用于 en 、de、es、fr、pl、pt、sv、ru、nl、nb、tr、tr、zh-chs、ko。65 characters for language code of en, de, es, fr, pl, pt, sv, ru, nl, nb, tr-tr, it, zh, ko.
      • 65 个字符的限制适用于其他语言代码65 characters for others
StringString No
preContextTextpreContextText 文本 字符串提供上下文的字符串。A string that gives context to the text string. 例如, text 字符串 花瓣 有效。For example, the text string petal is valid. 但是,如果将设置 preContextText 为 " 自行车",则上下文会发生更改,并且文本字符串将无效。However, if you set preContextText to bike, the context changes and the text string becomes not valid. 在这种情况下,API 建议你将花瓣为 (如**自行车脚踏板) 中所示。In this case, the API suggests that you change petal to pedal (as in bike pedal).

不会检查此文本的语法或拼写错误。This text is not checked for grammar or spelling errors.

textString、 preContextText string 和 string 的组合长度不能 postContextText 超过10000个字符。The combined length of the text string, preContextText string, and postContextText string may not exceed 10,000 characters.

可以在 GET 请求的查询字符串中或在 POST 请求的正文中指定此参数。You may specify this parameter in the query string of a GET request or in the body of a POST request.
StringString No
postContextTextpostContextText 文本 字符串提供上下文的字符串。A string that gives context to the text string. 例如,读取的 text 字符串read有效。For example, the text string read is valid. 但是,如果将设置 postContextText 为 " 地毯",上下文会更改,并且文本字符串将无效。However, if you set postContextText to carpet, the context changes and the text string becomes not valid. 在这种情况下,API 建议你将读取 (为红色**地毯) 。In this case, the API suggests that you change read to red (as in red carpet).

不会检查此文本的语法或拼写错误。This text is not checked for grammar or spelling errors.

textString、 preContextText string 和 string 的组合长度不能 postContextText 超过10000个字符。The combined length of the text string, preContextText string, and postContextText string may not exceed 10,000 characters.

可以在 GET 请求的查询字符串中或在 POST 请求的正文中指定此参数。You may specify this parameter in the query string of a GET request or in the body of a POST request.
StringString No
sessionIdsessionId 标识此用户会话的唯一 ID。A unique ID that identifies this user session. 为每个用户会话生成唯一值 (值不重要) 。Generate a unique value for each user session (the value is unimportant).

服务使用该 ID 来帮助调试问题并改善更正质量。The service uses the ID to help debug issues and improve the quality of corrections.
StringString No
setLangsetLang 可用于用户界面字符串的语言。The language to use for user interface strings. 您可以使用两个字母或四个字母的代码指定语言。You may specify the language using either a 2-letter or 4-letter code. 首选使用4字母代码。Using 4-letter codes is preferred.

有关支持的语言代码的列表,请参阅 必应支持的语言For a list of supported language codes, see Bing supported languages.

必应加载本地化的字符串(如果 setlang 包含有效的2字母非特定区域性代码 (Fr) 或 (fr-ca) 的有效的4字母特定区域性代码。Bing loads the localized strings if setlang contains a valid 2-letter neutral culture code (fr) or a valid 4-letter specific culture code (fr-ca). 例如,对于 fr-ca,必应加载 fr-fr 区域性代码字符串。For example, for fr-ca, Bing loads the fr neutral culture code strings.

setlang例如,如果不是有效 (例如, Zh-chs) 或必应不支持该语言 (例如, afAf-na) ,必应默认为en (英语) 。If setlang is not valid (for example, zh) or Bing doesn’t support the language (for example, af, af-na), Bing defaults to en (English).

若要指定2字母代码,请将此参数设置为 ISO 639-1 语言代码。To specify the 2-letter code, set this parameter to an ISO 639-1 language code.

若要指定4个字母的代码,请使用格式 <国家/地区> 其中 是 (非特定区域性的 iso 639-1 语言代码) ,<国家/地区> 是特定区域性 (代码的 iso 3166 国家/地区。To specify the 4-letter code, use the form -<country/region> where is an ISO 639-1 language code (neutral culture) and <country/region> is an ISO 3166 country/region (specific culture) code. 例如,使用 en-us 作为美国英语。For example, use en-US for United States 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
texttext 要检查拼写和语法错误的文本字符串。The text string to check for spelling and grammar errors.

textString、 preContextText string 和 string 的组合长度不能 postContextText 超过10000个字符。The combined length of the text string, preContextText string, and postContextText string may not exceed 10,000 characters.

可以在 GET 请求的查询字符串中或在 POST 请求的正文中指定此参数。You may specify this parameter in the query string of a GET request or in the body of a POST request. 由于查询字符串长度限制,你通常会使用 POST 请求,除非你只检查短字符串。Because of the query string length limit, you'll typically use a POST request unless you're checking only short strings.
StringString Yes
userIduserId 标识用户的唯一 ID。A unique ID that identifies the user. 为每个用户生成一个唯一值 (值不重要) 。Generate a unique value for each user (the value is unimportant).

服务使用该 ID 来帮助调试问题并改善更正质量。The service uses the ID to help debug issues and improve the quality of corrections.
StringString No

响应对象Response objects

以下是响应中可以包含的 JSON 响应对象。The following are the JSON response objects that the response may include. 如果请求成功,则响应中的顶级对象是 拼写检查 对象。If the request is successful, the top-level object in the response is the SpellCheck object. 如果请求失败,则顶级对象为 ErrorResponseIf the request fails, the top-level object is ErrorResponse.

ObjectObject 说明Description
错误Error 发生的错误。The error that occurred.
ErrorResponseErrorResponse 请求失败时响应包含的顶级对象。The top-level object that the response includes when the request fails.
FlaggedTokenFlaggedToken 语法不正确或拼写错误的单词。The word that may be grammatically incorrect or not spelled correctly.
拼写检查SpellCheck 请求成功时,响应包括的顶级对象。The top-level object that the response includes when the request succeeds.
TokenSuggestionTokenSuggestion 建议的拼写或语法更正。The suggested spelling or grammar correction.

错误Error

定义已发生的错误。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[]

FlaggedTokenFlaggedToken

拼写错误或语法不正确的单词。The word that is not spelled correctly or is grammatically incorrect.

名称Name Value 类型Type
offsetoffset 文本 查询字符串的开头到已标记的单词的从零开始的偏移量。The zero-based offset from the beginning of the text query string to the word that was flagged. IntegerInteger
繁多suggestions 更正拼写或语法错误的单词的列表。A list of words that correct the spelling or grammar error. 此列表以降序方式显示首选项。The list is in decreasing order of preference. TokenSuggestion[]TokenSuggestion[]
令牌token text查询字符串中拼写错误或语法不正确的单词。The word in the text query string that is not spelled correctly or is grammatically incorrect. StringString
类别type 导致单词被标记的错误的类型。The type of error that caused the word to be flagged. 下面是可能的值。The following are the possible values.
  • RepeatedToken 一 — 词重复 (例如,温 天气) RepeatedToken—The word was repeated in succession (for example, the warm warm weather)

  • UnknownToken — 所有其他拼写或语法错误UnknownToken—All other spelling or grammar errors
StringString

拼写检查SpellCheck

请求成功时,响应包括的顶级对象。The top-level object that the response includes when the request succeeds.

如果服务怀疑发生拒绝服务攻击,请求会成功 (HTTP 状态代码为 200 OK) ,但响应正文为空。If the service suspects a denial of service attack, the request succeeds (HTTP status code is 200 OK), but the body of the response is empty.

名称Name Value 类型Type
_type_type 一个类型提示,它设置为拼写检查。A type hint, which is set to SpellCheck. StringString
flaggedTokensflaggedTokens 文本中被标记为不正确或语法不正确的单词的列表。A list of words in text that were flagged as not being spelled correctly or are grammatically incorrect.

如果未找到拼写或语法错误,或指定的市场不受支持,则数组为空。If no spelling or grammar errors were found, or the specified market is not supported, the array is empty.
FlaggedToken[]FlaggedToken[]

TokenSuggestionTokenSuggestion

建议的拼写或语法更正。The suggested spelling or grammar correction.

名称Name Value 类型Type
分值score 一个值,该值指示建议的更正正确的置信度级别。A value that indicates the level of confidence that the suggested correction is correct. 如果 mode 查询参数设置为 "拼写",则此字段设置为1.0。If the modequery parameter is set to Spell, this field is set to 1.0. DoubleDouble
仅供参考suggestion 建议用于替换标记的单词的单词。The suggested word to replace the flagged word.

如果标记的单词是重复的单词 (参阅 type) ,则此字符串为空。If the flagged word is a repeated word (see type), this string is empty.
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.

市场代码Market codes

下表列出了可用于指定mkt查询参数的市场代码值。The following table lists the market code values that you may use to specify the mkt query parameter. 必应仅为这些市场返回内容。Bing returns content for only these markets. 列表可能随时变动。The list is subject to change.

有关可在cc查询参数中指定的国家/地区代码的列表,请参阅国家/地区代码For a list of country codes that you may specify in the cc query parameter, see Country codes.

国家/地区Country/Region 语言Language 市场代码Market code
阿根廷Argentina 西班牙语Spanish es-ARes-AR
澳大利亚Australia 英语English en-AUen-AU
奥地利Austria 德语German de-ATde-AT
比利时Belgium 荷兰语Dutch nl-BEnl-BE
比利时Belgium 法语French fr-BEfr-BE
巴西Brazil 葡萄牙语Portuguese pt-BRpt-BR
CanadaCanada 英语English en-CAen-CA
CanadaCanada 法语French fr-CAfr-CA
智利Chile 西班牙语Spanish es-CLes-CL
丹麦Denmark 丹麦语Danish da-DKda-DK
芬兰Finland 芬兰语Finnish fi-FIfi-FI
法国France 法语French fr-FRfr-FR
德国Germany 德语German de-DEde-DE
香港特别行政区Hong Kong SAR 繁体中文Traditional Chinese zh-HKzh-HK
印度India 英语English en-INen-IN
印度尼西亚Indonesia 英语English en-IDen-ID
意大利Italy 意大利语Italian it-ITit-IT
日本Japan 日语Japanese ja-JPja-JP
韩国Korea 韩语Korean ko-KRko-KR
马来西亚Malaysia 英语English en-MYen-MY
墨西哥Mexico 西班牙语Spanish es-MXes-MX
荷兰Netherlands 荷兰语Dutch nl-NLnl-NL
新西兰New Zealand 英语English en-NZen-NZ
挪威Norway 挪威语Norwegian no-NOno-NO
中华人民共和国People's republic of China 中文Chinese zh-CNzh-CN
波兰Poland 波兰语Polish pl-PLpl-PL
菲律宾共和国Republic of the Philippines 英语English en-PHen-PH
俄罗斯Russia 俄语Russian ru-RUru-RU
南非South Africa 英语English en-ZAen-ZA
西班牙Spain 西班牙语Spanish es-ESes-ES
瑞典Sweden 瑞典语Swedish sv-SEsv-SE
瑞士Switzerland 法语French fr-CHfr-CH
瑞士Switzerland 德语German de-CHde-CH
中国台湾Taiwan 繁体中文Traditional Chinese zh-TWzh-TW
土耳其Turkey 土耳其语Turkish tr-TRtr-TR
United KingdomUnited Kingdom 英语English en-GBen-GB
United StatesUnited States 英语English zh-CNen-US
United StatesUnited States 西班牙语Spanish es-USes-US

国家/地区代码Country codes

下面是可使用 cc 查询参数指定的国家/地区代码。The following are the country codes that you may specify in the cc query parameter. 列表可能随时变动。The list is subject to change.

国家/地区Country/Region 国家/地区代码Country Code
阿根廷Argentina ARAR
澳大利亚Australia AUAU
奥地利Austria ATAT
比利时Belgium BEBE
巴西Brazil BRBR
CanadaCanada CACA
智利Chile CLCL
丹麦Denmark DKDK
芬兰Finland FIFI
法国France FRFR
德国Germany DEDE
香港特别行政区Hong Kong SAR HKHK
印度India ININ
印度尼西亚Indonesia IDID
意大利Italy ITIT
日本Japan JPJP
韩国Korea KRKR
马来西亚Malaysia MYMY
墨西哥Mexico MXMX
荷兰Netherlands NLNL
新西兰New Zealand NZNZ
挪威Norway NO
中华人民共和国People's Republic of China CNCN
波兰Poland PLPL
葡萄牙Portugal PTPT
菲律宾共和国Republic of the Philippines PHPH
俄罗斯Russia RURU
沙特阿拉伯Saudi Arabia SASA
南非South Africa ZAZA
西班牙Spain ESES
瑞典Sweden SESE
瑞士Switzerland CHCH
中国台湾Taiwan TWTW
土耳其Turkey TRTR
United KingdomUnited Kingdom GBGB
United StatesUnited States 美国US

必应支持的语言Bing supported languages

以下是可在setLang查询参数中指定的必应支持的语言。The following are the Bing supported languages that you may specify in the setLang query parameter. 列表可能随时变动。The list is subject to change.

支持的语言Supported Languages 语言代码Language Code
阿拉伯语Arabic arar
巴斯克语Basque eueu
孟加拉语Bengali bnbn
保加利亚语Bulgarian bgbg
加泰罗尼亚语Catalan caca
中文(简体)Chinese (Simplified) zh-hanszh-hans
中文(繁体)Chinese (Traditional) zh-hantzh-hant
克罗地亚语Croatian hrhr
捷克语Czech cscs
丹麦语Danish dada
荷兰语Dutch nlnl
英语English enen
英语-英国English-United Kingdom en-gben-gb
爱沙尼亚语Estonian etet
芬兰语Finnish fifi
法语French frfr
加利西亚语Galician glgl
德语German dede
古吉拉特语Gujarati gugu
希伯来语Hebrew hehe
HindiHindi hihi
匈牙利语Hungarian huhu
冰岛语Icelandic isis
意大利语Italian itit
日语Japanese Jpjp
卡纳达语Kannada knkn
韩语Korean koko
拉脱维亚语Latvian lvlv
立陶宛语Lithuanian ltlt
马来语Malay msms
马拉雅拉姆语Malayalam  mlml
马拉地语Marathi mrmr
挪威语(博克马尔语)Norwegian (Bokmål) nbnb
波兰语Polish plpl
葡萄牙语(巴西)Portuguese (Brazil) pt-brpt-br
葡萄牙语(葡萄牙)Portuguese (Portugal) pt-ptpt-pt
旁遮普语Punjabi papa
罗马尼亚语Romanian roro
俄语Russian ruru
塞尔维亚语(青色)Serbian (Cyrylic) sr
斯洛伐克语Slovak sksk
斯洛文尼亚语Slovenian slsl
西班牙语Spanish eses
瑞典语Swedish svsv
泰米尔语Tamil tata
泰卢固语Telugu tete
泰语Thai thth
土耳其语Turkish trtr
乌克兰语Ukrainian ukuk
越南语Vietnamese vivi