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

使用必应新闻搜索 API 搜索新闻

警告

2020 年 10 月 30 日,必应搜索 API 从认知服务移动到必应搜索服务。 本文档仅供参考。 有关更新的文档,请参阅必应搜索 API 文档。 关于为必应搜索创建新的 Azure 资源的说明,请参阅通过 Azure 市场创建必应搜索资源

使用必应图像搜索 API,可以轻松将必应的认知新闻搜索功能集成到应用程序中。

虽然必应新闻搜索 API 主要用于查找并返回相关的新闻文章,但它还提供了一些在网络上进行智能化、集中化新闻检索的功能。

建议并使用搜索词

如果提供供用户输入搜索词的搜索框,请使用必应自动推荐 API 来改进体验。 此 API 根据用户键入的部分搜索词返回建议的查询字符串。

用户输入搜索词以后,URL 在设置 q 查询参数之前会对搜索词进行编码。 例如,如果用户输入 sailing dinghies,系统会将 q 设置为 sailing+dinghiessailing%20dinghies

获取一般新闻

若要从 Web 获取与用户的搜索词相关的普通新闻文章,请发送以下 GET 请求:

GET https://api.cognitive.microsoft.com/bing/v7.0/news/search?q=sailing+dinghies&mkt=en-us HTTP/1.1
Ocp-Apim-Subscription-Key: 123456789ABCDE
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)
X-Search-ClientIP: 999.999.999.999
X-Search-Location: lat:47.60357;long:-122.3295;re:100
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>
Host: api.cognitive.microsoft.com

如果是首次调用任何必应 API,请勿添加客户端 ID 请求头。 只有在以前调用过必应 API 且必应针对用户和设备组合返回了客户端 ID 的情况下,才包括客户端 ID。

若要从特定的域获取新闻,请使用 site: 查询运算符。

GET https://api.cognitive.microsoft.com/bing/v7.0/news/search?q=sailing+dinghies+site:contososailing.com&mkt=en-us HTTP/1.1

下面的 JSON 示例显示了对上一查询的响应。 作为必应搜索 API 的使用和显示要求的一部分,你必须按照响应中提供的顺序显示每篇新闻文章。 如果该文章有群集的文章,则应表明存在相关的文章并在用户提出请求时显示它们。

{
    "_type" : "News",
    "readLink" : "https:\/\/api.cognitive.microsoft.com\/bing\/v5\/news\/search?q=sailing+dinghies",
    "totalEstimatedMatches" : 88400,
    "value" : [{
        "name" : "Sailing Vies for Four Trophies",
        "url" : "http:\/\/www.bing.com\/cr?IG=CCE2F06CA750455891FE99A72...",
        "image" : {
            "thumbnail" : {
                "contentUrl" : "https:\/\/www.bing.com\/th?id=ON.9C23AA5...",
                "width" : 650,
                "height" : 341
            }
        },
        "description" : "College Rankings, presented by Zim...",
        "provider" : [{
            "_type" : "Organization",
            "name" : "contoso.com"
        }],
        "datePublished" : "2017-04-14T15:28:00"
    },

    ...

    {
        "name" : "Fabrikam Sailing Club to host Mirror Dinghy...",
        "url" : "http:\/\/www.bing.com\/cr?IG=CCE2F06CA750455891F...",
        "image" : {
            "thumbnail" : {
                "contentUrl" : "https:\/\/www.bing.com\/th?id=ON.36...",
                "width" : 448,
                "height" : 300
            }
        },
        "description" : "The sailing club that trained Olympian Ben...",
        "provider" : [{
            "_type" : "Organization",
            "name" : "Contoso"
        }],
        "datePublished" : "2017-04-04T11:02:00",
        "category" : "Sports"
    }]
}

news 应答列出必应认为与查询相关的新闻文章。 totalEstimatedMatches 字段包含一个估计数,是对可以查看的文章数的估计。 若要了解如何按页浏览这些文章,请参阅翻页新闻

该列表中的每篇新闻包含该文章的名称、说明及其在宿主网站上的 URL。 如果文章包含图像,则该对象包括图像的缩略图。 使用 nameurl 可以创建一个超链接,用于将用户转到宿主站点上的新闻。 如果文章包含图像,也请使用 url 为图像嵌入可单击的链接。 请务必使用 provider 来指定文章的属性。

如果必应可以确定新闻文章的类别,则文章会包含 category 字段。

获取当天的头条新闻

若要获取今天的热门新闻文章,可以像以前一样发送相同的一般新闻请求,同时将 q 参数保留为未设置。

GET https://api.cognitive.microsoft.com/bing/v7.0/news/search?q=&mkt=en-us HTTP/1.1
Ocp-Apim-Subscription-Key: 123456789ABCDE
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)
X-Search-ClientIP: 999.999.999.999
X-Search-Location: lat:47.60357;long:-122.3295;re:100
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>
Host: api.cognitive.microsoft.com

获取头条新闻的响应几乎与获取一般新闻的响应相同。 但是,news 应答不包含 totalEstimatedMatches 字段,因为结果数已设定。 头条新闻文章的数目可能因新闻圈而异。 请务必使用 provider 字段来指定文章的属性。

按类别获取新闻

若要按类别获取新闻文章(例如头条体育或娱乐文章),请向必应发送以下 GET 请求:

GET https://api.cognitive.microsoft.com/bing/v7.0/news?category=sports&mkt=en-us HTTP/1.1
Ocp-Apim-Subscription-Key: 123456789ABCDE
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)
X-Search-ClientIP: 999.999.999.999
X-Search-Location: lat:47.60357;long:-122.3295;re:100
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>
Host: api.cognitive.microsoft.com

请使用 category 查询参数来指定要获取的文章的类别。 如需可以指定的新闻类别的列表,请参阅 News Categories by Market(按市场划分的新闻类别)。

按类别获取新闻的响应与获取普通新闻的响应几乎相同。 区别是,文章全都来自指定的类别。

获取标题新闻

若要请求标题新闻文章以及获取所有新闻类别的文章,请向必应发送以下 GET 请求:

GET https://api.cognitive.microsoft.com/bing/v7.0/news?mkt=en-us HTTP/1.1
Ocp-Apim-Subscription-Key: 123456789ABCDE
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)
X-MSEdge-ClientIP: 999.999.999.999
X-Search-Location: lat:47.60357;long:-122.3295;re:100
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>
Host: api.cognitive.microsoft.com

请勿包括 category 查询参数。

获取标题新闻的响应与获取当天的头条新闻的响应相同。 如果文章为标题文章,其 headline 字段会设置为 true

默认情况下,响应包含最多 12 篇标题文章。 若要更改需返回的标题文章的数目,请指定 headlineCount 查询参数。 就每个新闻类别来说,响应还包括最多四篇非标题文章。

响应将群集文章计为一篇文章。 由于一个群集可能有多篇文章,因此就每个类别来说,响应可能包含 12 篇以上的标题文章,4 篇以上的非标题文章。

若要获取社交网络上的热门新闻主题,请向必应发送以下 GET 请求:

GET https://api.cognitive.microsoft.com/bing/v7.0/news/trendingtopics?mkt=en-us HTTP/1.1
Ocp-Apim-Subscription-Key: 123456789ABCDE
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)
X-Search-ClientIP: 999.999.999.999
X-Search-Location: lat:47.60357;long:-122.3295;re:100
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>
X-MSAPI-UserState: <blobFromPriorResponseGoesHere>
Host: api.cognitive.microsoft.com

注意

热门主题仅在美国和中国市场提供。

以下 JSON 是对上一请求的响应。 每篇热门新闻文章包含一个相关的图像、突发新闻标志,以及一个链接到该文章的必应搜索结果的 URL。 请使用 webSearchUrl 字段中的 URL 将用户带到必应搜索结果页。 也可自行使用查询文本来调用 Web 搜索 API,以便显示结果。

{
    "_type" : "TrendingTopics",
    "value" : [{
        "name" : "Canada pot measure",
        "image" : {
            "url" : "https:\/\/www.bing.com\/th?id=OPN.RTNews_hHD...",
            "provider" : [{
                "_type" : "Organization",
                "name" : "Contoso Images"
            }]
        },
        "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=070292D8CEDD...",
        "isBreakingNews" : false,
        "query" : {
            "text" : "Canada marijuana"
        }
    },
    {
        "name" : "Down on Vegas move",
        "image" : {
            "url" : "https:\/\/www.bing.com\/th?id=OPN.RTNews_Bfbmg8h...",
            "provider" : [{
                "_type" : "Organization",
                "name" : "Contoso"
            }]
        },
        "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=070292D8CEDD...",
        "isBreakingNews" : false,
        "query" : {
            "text" : "Marcus Appel Las Vegas"
        }
    },

    ...

    ]
}

如果有其他文章与某篇新闻文章相关,则该新闻文章可能包含 clusteredArticles 字段。 下面显示的文章包含群集文章。

    {
        "name" : "Playoffs 2017: Betting lines, point spreads...",
        "url" : "http:\/\/www.bing.com\/cr?IG=4B7056CEC271408997D115...",
        "image" : {
            "thumbnail" : {
                "contentUrl" : "https:\/\/www.bing.com\/th?id=ON.D7B1...",
                "width" : 700,
                "height" : 393
            }
        },
        "description" : "April 14, 2017 3:37pm EDT April 14, 2017 3:34pm...",
        "provider" : [{
            "_type" : "Organization",
            "name" : "Contoso"
        }],
        "datePublished" : "2017-04-14T19:43:00",
        "category" : "Sports",
        "clusteredArticles" : [{
            "name" : "Playoffs 2017: Betting odds, favorites to win...",
            "url" : "http:\/\/www.bing.com\/cr?IG=4B7056CEC271408997D1159E...",
            "description" : "April 14, 2017 3:30pm EDT April 14, 2017 3:27pm...",
            "provider" : [{
                "_type" : "Organization",
                "name" : "Contoso"
            }],
            "datePublished" : "2017-04-14T19:37:00",
            "category" : "Sports"
        }]
    },

限制请求

服务和订阅类型决定了每秒可以发出的查询数 (QPS)。 请确保应用程序包含防止超出配额限制的逻辑。 如果达到或超出 QPS 限制,则请求会失败,系统会返回 HTTP 429 状态代码。 响应包含 Retry-After 标头,该标头指示需等待多久才能发送另一请求。

拒绝服务与限制

该服务区分拒绝服务 (DoS) 攻击和 QPS 违规。 如果该服务怀疑存在 DoS 攻击,则请求会成功(HTTP 状态代码为“200 正常”)。 但是,响应正文为空。

后续步骤