你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

NewsOperations.SearchWithHttpMessagesAsync 方法

参考

定义

命名空间:: Microsoft.Azure.CognitiveServices.Search.NewsSearch

程序集:: Microsoft.Azure.CognitiveServices.Search.NewsSearch.dll

包:: Microsoft.Azure.CognitiveServices.Search.NewsSearch v2.0.0

重要

一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。

新闻搜索 API 允许向必应发送搜索查询，并返回与搜索查询相关的新闻列表。本部分提供有关用于请求新闻的查询参数和标头以及包含它们的 JSON 响应对象的技术详细信息。有关演示如何发出请求的示例，请参阅在 Web 上搜索新闻。

public System.Threading.Tasks.Task<Microsoft.Rest.HttpOperationResponse<Microsoft.Azure.CognitiveServices.Search.NewsSearch.Models.News>> SearchWithHttpMessagesAsync (string query, string acceptLanguage = default, string userAgent = default, string clientId = default, string clientIp = default, string location = default, string countryCode = default, int? count = default, string freshness = default, string market = default, int? offset = default, bool? originalImage = default, string safeSearch = default, string setLang = default, string sortBy = default, bool? textDecorations = default, string textFormat = default, System.Collections.Generic.Dictionary<string,System.Collections.Generic.List<string>> customHeaders = default, System.Threading.CancellationToken cancellationToken = default);

abstract member SearchWithHttpMessagesAsync : string * string * string * string * string * string * string * Nullable<int> * string * string * Nullable<int> * Nullable<bool> * string * string * string * Nullable<bool> * string * System.Collections.Generic.Dictionary<string, System.Collections.Generic.List<string>> * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Rest.HttpOperationResponse<Microsoft.Azure.CognitiveServices.Search.NewsSearch.Models.News>>
override this.SearchWithHttpMessagesAsync : string * string * string * string * string * string * string * Nullable<int> * string * string * Nullable<int> * Nullable<bool> * string * string * string * Nullable<bool> * string * System.Collections.Generic.Dictionary<string, System.Collections.Generic.List<string>> * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Rest.HttpOperationResponse<Microsoft.Azure.CognitiveServices.Search.NewsSearch.Models.News>>

Public Function SearchWithHttpMessagesAsync (query As String, Optional acceptLanguage As String = Nothing, Optional userAgent As String = Nothing, Optional clientId As String = Nothing, Optional clientIp As String = Nothing, Optional location As String = Nothing, Optional countryCode As String = Nothing, Optional count As Nullable(Of Integer) = Nothing, Optional freshness As String = Nothing, Optional market As String = Nothing, Optional offset As Nullable(Of Integer) = Nothing, Optional originalImage As Nullable(Of Boolean) = Nothing, Optional safeSearch As String = Nothing, Optional setLang As String = Nothing, Optional sortBy As String = Nothing, Optional textDecorations As Nullable(Of Boolean) = Nothing, Optional textFormat As String = Nothing, Optional customHeaders As Dictionary(Of String, List(Of String)) = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of HttpOperationResponse(Of News))

参数

query: String

用户的搜索查询字符串。查询字符串不能为空。查询字符串可能包含必应高级运算符。例如，若要将新闻限制为特定域，请使用 site：运算符。仅对新闻搜索 API 使用此参数。调用热门主题 API 或新闻类别 API 时，请勿指定此参数。

acceptLanguage: String

用于用户界面字符串的一种或多种语言的逗号分隔列表。此列表以降序方式显示首选项。有关其他信息（包括预期格式），请参阅 RFC2616。此标头和 setLang 查询参数互斥;不要同时指定这两者。如果设置此标头，则还必须指定 cc 查询参数。为了确定返回结果的市场，必应使用它从列表中找到的第一个受支持语言，并将其与 cc 参数值组合在一起。如果列表不包括支持的语言，必应会查找最接近的语言和支持请求的市场，或将聚合或默认市场用于结果。若要确定必应使用的市场，请查看 BingAPIs-Market 标头。仅当指定多种语言时，才使用此标头和 cc 查询参数。否则，请使用 mkt 和 setLang 查询参数。用户界面字符串是用作用户界面中标签的字符串。 JSON 响应对象中有几个用户界面字符串。响应对象中 Bing.com 属性的任何链接均将应用指定的语言。

userAgent: String

发出请求的用户代理。必应使用用户代理为移动用户提供优化体验。尽管是可选的，但还是建议始终指定此标头。 user-agent 应该是任何常用浏览器发送的字符串。有关用户代理的信息，请参阅 RFC 2616。下面是用户代理字符串的示例。 Windows Phone：Mozilla/5.0 (兼容;MSIE 10.0;Windows Phone 8.0;Trident/6.0;IEMobile/10.0;手臂;触摸;诺基亚;卢米亚 822) 。 Android：Mozilla /5.0 (Linux;美国;Android 2.3.5;en - us;SCH - I500 Build / GINGERBREAD) AppleWebKit / 533.1 (KHTML;如 Gecko) 版本 / 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.20120423。电脑：Mozilla / 5.0 (Windows NT 6.3;WOW64;Trident / 7.0;触摸;rv：11.0) 像壁虎。 iPad： Mozilla / 5.0 (iPad;CPU OS 7_0，如 Mac OS X) AppleWebKit / 537.51.1 (KHTML，如 Gecko) 版本 / 7.0 Mobile / 11A465 Safari / 9537.53

clientId: String

必应使用此标头跨必应 API 调用为用户提供一致的行为。必应通常会发布新功能和改进，并将客户端 ID 用作密钥以在不同航班上分配客流量。如果未跨多个请求将相同的客户端 ID 用于用户，则必应可能将用户分配给多个冲突的航班。分配给多个冲突航班可能导致用户体验不一致。例如，如果第二个请求与第一个请求的航班分配不同，体验可能会出现意外。此外，必应可以使用客户端 ID 根据客户端 ID 搜索历史记录来定制 Web 结果，为用户提供更丰富的体验。通过分析由客户端 ID 生成的活动，必应还会使用此标头来提高结果排名。相关改进有助于提高必应 API 交付的结果质量，从而提高 API 客户的点击率。重要提示：尽管是可选的，但应将此标头视为必选。对于同一最终用户和设备组合，如果跨多个请求保留客户端 ID，则 1) API 客户可以获取一致的用户体验；2) 可通过必应 API 提高结果质量，从而提高点击率。在设备上使用你的应用程序的每个用户必须具有必应生成的唯一客户端 ID。如果未在请求中包含此标头，必应会生成 ID，然后在 X-MSEdge-ClientID 响应标头中将其返回。仅当用户首次在设备上使用应用时，才不可以在请求中包含此标头。针对应用为设备上的此用户生成的每个必应 API 请求，使用客户端 ID。保留客户端 ID。若要在浏览器应用中保留 ID，请使用持久性 HTTP Cookie 来确保所有会话均使用此 ID。请勿使用会话 Cookie。对于移动应用等其他应用，请使用设备的持久存储来保留 ID。下次用户在该设备上使用你的应用时，会获取保留的客户端 ID。必应响应不一定包含此标头。如果响应包含此标头，请针对该设备上的用户捕获客户端 ID 并将其用于所有后续必应请求。如果包含 X-MSEdge-ClientID，不可在请求中包含 Cookie。

clientIp: String

客户端设备的 IPv4 或 IPv6 地址。 IP 地址用于发现用户的位置。必应使用位置信息来确定安全搜索行为。尽管是可选的，但还是建议始终指定此标头和 X-Search-Location 标头。不要混淆地址（例如，通过将最后一个八位字节更改为 0 来混淆地址）。混淆地址会导致位置未处于设备实际位置附近，这可能导致必应提供错误的结果。

location: String

以分号分隔的键/值对列表，描述客户端的地理位置。必应使用位置信息来确定安全搜索行为并返回相关的本地内容。以 <键>:<值> 形式指定键/值对。下面是用于指定用户位置的键。 lat (所需的) ：客户端位置的纬度（以度为单位）。纬度必须大于或等于 -90.0 且小于或等于 +90.0。负值表示南纬，正值表示北纬。需要 long () ：客户端位置的经度（以度为单位）。经度必须大于或等于 -180.0 且小于或等于 +180.0。负值表示西经，正值表示东经。 re (必需) ：半径（以米为单位），指定坐标的水平精度。传递设备定位服务返回的值。典型的值可能是：22m - GPS/Wi-Fi、380m - 蜂窝基站三角网定位、18,000m - 反向 IP 查询。 ts (可选) ：客户端位于该位置时的 UTC UNIX 时间戳。 (UNIX 时间戳是自 1970 年 1 月 1 日以来的秒数。) 头 (可选) ：客户端的相对航向或行驶方向。以度数指定旅行方向（从 0 到 360），相对于正北方向顺时针计数。仅当 sp 键为非零时，才指定此键。 sp (可选) ：客户端设备正在行驶的水平速度 (速度) 以米/秒为单位。 alt (可选) ：客户端设备的海拔高度（以米为单位）。 (可选) ：半径（以米为单位），指定坐标的垂直精度。仅当指定 alt 键时，才指定此键。尽管许多键是可选的，但提供的信息越多，位置结果越精确。尽管是可选的，但还是建议始终指定用户的地理位置。如果客户端的 IP 地址未准确反映用户的物理位置（例如，如果客户端使用 VPN），则提供位置尤其重要。为了获得最佳结果，应包含此标头和 X-MSEdge-ClientIP 标头，但应至少包含此标头。

countryCode: String

结果来源的国家/地区的 2 个字符国家/地区代码。此 API 仅支持美国市场。如果指定此查询参数，则必须将其设置为我们。如果设置此参数，则还必须指定 Accept-language 标头。必应使用从语言列表中找到的第一种受支持语言，并将该语言与指定的国家/地区代码组合在一起，以确定返回结果的市场。如果语言列表不包含支持的语言，必应会查找支持请求的最近语言和市场，或者可能会对结果使用聚合市场或默认市场，而不是指定的市场。仅当指定多种语言时，才应使用此查询参数和Accept-Language查询参数;否则，应使用 mkt 和 setLang 查询参数。此参数和 mkt 查询参数相互排斥，不可同时指定两者。

count: Nullable<Int32>

响应中要返回的新闻文章数。提供的实际结果数可能小于请求获取的结果数。默认值为 10，最大值为 100。实际传递的数量可能小于请求的数量。可以将此参数与 offset 参数一起使用来对结果进行分页。例如，如果用户界面每页显示 20 篇文章，请将 count 设置为 20，offset 设置为 0 以获取结果的第一页。对于每个后续页，将偏移量递增 20 (例如 0、20、40) 。多个页面可能在结果中包含一些重叠。

freshness: String

按必应发现新闻的日期和时间筛选新闻。下面是可能的筛选器值。日期：返回过去 24 小时内发现的新闻。周：返回过去 7 天内发现的新闻。月：返回过去 30 天内发现的新闻。仅对新闻搜索 API 使用此参数。调用新闻类别 API 或热门主题 API 时，请勿指定此参数。可能的值包括：“Day”、“Week”、“Month”

market: String

产生结果的市场。通常，mkt 是用户发出请求的国家/地区。但是，如果用户不位于必应提供结果的国家/地区，则可能是不同的国家/地区。市场必须采用语言代码>-国家/<地区代码>的形式<。例如，en-US。字符串不区分大小写。有关可能的市场值的列表，请参阅市场代码。注意：如果已知，建议始终指定市场。指定市场有助于必应路由请求，并返回适当的最佳响应。如果指定的市场未在市场代码中列出，必应会根据可能会更改的内部映射使用最适合的市场代码。此参数和 cc 查询参数相互排斥，不可同时指定两者。

offset: Nullable<Int32>

从零开始的偏移量，指示在返回新闻之前要跳过的新闻数。默认值为 0。偏移量应小于 totalEstimatedMatches (

count) 。使用此参数和 count 参数对结果进行分页。例如，如果用户界面每页显示 20 条新闻，请将 count 设置为 20，将偏移量设置为 0 以获取结果的第一页。对于每个后续页，将偏移量递增 20 (例如 0、20、40) 。多个页面可能在结果中包含一些重叠。

originalImage: Nullable<Boolean>

一个布尔值，用于确定图像的 contentUrl 包含指向原始文章图像的缩略图还是图像本身的 URL。如果文章包含图像，并且此参数设置为 true，则图像的 contentUrl 属性包含可用于从发布者网站下载原始图像的 URL。否则，如果此参数为 false，则图像的 contentUrl 和 thumbnailUrl URL 都指向同一缩略图图像。仅对新闻搜索 API 使用此参数。调用热门主题 API 或新闻类别 API 时，请勿指定此参数。

safeSearch: String

筛选成人内容的新闻。下面是可能的筛选器值。关闭：返回包含成人文本、图像或视频的新闻文章。中等：返回包含成人文本但不返回成人图像或视频的新闻文章。严格：请勿返回包含成人文本、图像或视频的新闻文章。如果请求来自必应成人策略要求将 safeSearch 设置为 Strict 的市场，必应将忽略 safeSearch 值并使用 Strict。如果使用 site： query 运算符，则无论 safeSearch 查询参数设置为什么，响应都可能包含成人内容。使用网站：仅当你知道网站上的内容并且你的方案支持成人内容的可能性时。可能的值包括：“Off”、“Moderate”、“Strict”

setLang: String

可用于用户界面字符串的语言。使用 ISO 639-1 2 字母语言代码指定语言。例如，英语的语言代码是 EN。默认为 EN（英语）。尽管是可选项，但应始终指定语言。通常，将 setLang 设置为 mkt 指定的相同语言，除非用户希望用户界面字符串以其他语言显示。此参数和 Accept-Language 标头互斥;不要同时指定这两者。用户界面字符串是用作用户界面中标签的字符串。 JSON 响应对象中有几个用户界面字符串。此外，响应对象中 Bing.com 属性的任何链接均会应用指定的语言。

sortBy: String

返回新闻的顺序。下面是可能的不区分大小写的值。日期：如果请求是通过新闻搜索 API 进行的，则响应将返回按日期从最近到最早的日期排序的新闻文章。如果请求通过新闻趋势主题 API，则响应将返回按日期从最近到最早的日期排序的趋势主题。

textDecorations: Nullable<Boolean>

一个布尔值，用于确定显示字符串是否包含修饰标记，例如命中突出显示字符。如果为 true，则字符串可能包含标记。默认值为 false。若要指定是使用 Unicode 字符还是 HTML 标记作为标记，请参阅 textFormat 查询参数。有关命中突出显示的信息，请参阅命中突出显示。

textFormat: String

用于文本修饰的标记的类型 (请参阅 textDecorations 查询参数) 。可能的值为 Raw - 使用 Unicode 字符标记需要特殊格式的内容。 Unicode 字符的范围是 E000 到 E019。例如，必应使用 E000 和 E001 标记查询词的开始和结束，以便突出显示命中。 HTML - 使用 HTML 标记标记需要特殊格式的内容。例如，使用 <b> 标记突出显示显示字符串中的查询词。默认值为 Raw。对于包含可转义 HTML 字符（如、和）<的显示字符串，如果 textFormat 设置为 HTML，则必应根据需要转义字符（例如< (转义为 <&) 。 > 可能的值包括：“Raw”、“Html”