Co je Vyhledávání zpráv Bingu?What is Bing News Search?

Rozhraní API pro vyhledávání zpráv Bingu nabízí prostředí podobné (ale ne totožné) jako zprávy Bingu.The Bing News Search API provides a similar (but not exact) experience to Bing News. Rozhraní API pro vyhledávání zpráv Bingu umožňuje poslat dotaz do vyhledávání Bingu a získat seznam relevantních zpravodajských článků.The Bing News Search API lets you send a search query to Bing and get back a list of relevant news articles.

Pokud vytváříte stránku výsledků hledání pouze se zprávami, na které chcete vyhledávat relevantní zprávy pro vyhledávací dotazy uživatelů, místo obecnějšího rozhraní API Bingu pro vyhledávání na webu volejte toto rozhraní API.If you're building a news-only search results page to find news that's relevant to the user's search query, call this API instead of calling the more general Bing Web Search API. Pokud chcete zprávy i další typy obsahu, jako jsou webové stránky, obrázky a videa, volejte rozhraní API Bingu pro vyhledávání na webu.If you want news and other types of content such as webpages, images, and videos, then call the Bing Web Search API.

Navrhování a používání hledaných termínůSuggesting & using search terms

Pokud nabízíte vyhledávací pole, do kterého může uživatel zadat hledaný termín, můžete hledání vylepšit s využitím rozhraní API pro automatické návrhy Bingu.If you provide a search box where the user enters their search term, use the Bing Autosuggest API to improve the experience. Toto rozhraní API vrací navrhované řetězce dotazů na základě částečné shody hledaných termínů zadávaných uživatelem.The API returns suggested query strings based on partial search terms as the user types.

Jakmile uživatel zadá hledaný termín, před nastavením parametru dotazu q ho zakódujte pomocí kódování URL.After the user enters their search term, URL encode it before setting the q query parameter. Pokud uživatel například zadá sailing dinghies, nastavte parametr q na hodnotu sailing+dinghies nebo sailing%20dinghies.For example, if the user enters sailing dinghies, set q to sailing+dinghies or sailing%20dinghies.

Získání obecných zprávGetting general news

Pokud chcete z webu získat obecné zprávy související s hledaným termínem uživatele, odešlete tento požadavek GET:To get general news articles related to the user's search term from the web, send the following GET request:

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

Pokud voláte některé z rozhraní API Bingu poprvé, nezahrnujte do volání hlavičku ID klienta.If it's your first time calling any of the Bing APIs, don't include the client ID header. ID klienta zahrňte pouze v případě, že jste již dříve volali rozhraní API Bingu a Bing vrátil ID klienta pro příslušnou kombinaci uživatele a zařízení.Only include the client ID if you've previously called a Bing API and Bing returned a client ID for the user and device combination.

Pokud chcete získat zprávy z konkrétní domény, použijte operátor dotazu site:.To get news from a specific domain, use the site: query operator.

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

Následující příklad ukazuje odpověď na předchozí dotaz.The following shows the response to the previous query. Každý zpravodajský článek musíte zobrazit v pořadí uvedeném v odpovědi.You must display each news article in the order provided in the response. Pokud článek zahrnuje shluk článků, měli byste uvést, že existují související články, a zobrazit je, pokud uživatel o jejich zobrazení požádá.If the article has clustered articles, you should indicate that related articles exist and display them if the user requests to see them.

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

Odpověď news (zprávy) vypíše zpravodajské články, které jsou podle Bingu k dotazu relevantní.The news answer lists the news articles that Bing thought were relevant to the query. Pole totalEstimatedMatches obsahuje odhadovaný počet článků, které je možné zobrazit.The totalEstimatedMatches field contains an estimate of the number of articles available to view. Informace o procházení článků po stránkách najdete v článku o stránkování zpráv.For information about paging through the articles, see Paging News.

Každý zpravodajský článek v seznamu obsahuje název, popis a adresu URL článku na webu hostitele.Each news article in the list includes the article's name, description, and URL to the article on the host's website. Pokud článek obsahuje obrázek, zahrnuje objekt miniaturu obrázku.If the article contains an image, the object includes a thumbnail of the image. Pomocí name a url vytvořte hypertextový odkaz, který uživatele přenese na zpravodajský článek na webu hostitele.Use name and url to create a hyperlink that takes the user to the news article on the host's site. Pokud článek obsahuje obrázek, pomocí url umožněte, aby se na obrázek dalo kliknout.If the article includes an image, also make the image clickable using url. Nezapomeňte uvést zdroj článku pomocí provider.Be sure to use provider to attribute the article.

Pokud Bing dokáže určit kategorii zpravodajského článku, obsahuje článek pole category.If Bing can determine the category of news article, the article includes the category field.

Získání dnešních nejčtenějších zprávGetting today's top news

Pokud chcete získat dnešní nejčtenější zpravodajské články, proveďte stejný požadavek jako pro získání obecných zpráv, ale nenastavujte q.To get today's top news articles, you'd make the same request as getting general news except that you'd leave q unset.

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

Odpověď pro získání nejčtenějších zpráv je skoro stejná jako pro získání obecných zpráv.The response for getting top news is almost the same as getting general news. Odpověď news ale neobsahuje pole totalEstimatedMatches, protože existuje stanovený počet výsledků.However, the news answer doesn't include the totalEstimatedMatches field because there's a set number of results. Počet nejčtenějších zpravodajských článků se může lišit v závislosti na zpravodajském cyklu.The number of top news articles may vary depending on the news cycle. Nezapomeňte uvést zdroj článku pomocí provider.Be sure to use provider to attribute the article.

Získání zpráv podle kategorieGetting news by category

Pokud chcete získat zpravodajské články podle kategorií, třeba hlavní sportovní zprávy nebo zprávy ze zábavního průmyslu, pošlete do Bingu tento požadavek GET:To get news articles by category, such as the top sports or entertainment articles, send the following GET request to Bing:

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

Pomocí parametru dotazu category (kategorie) určete kategorii článků, které chcete získat.Use the category query parameter to specify the category of articles to get. Seznam možných zpravodajských kategorií, které můžete určit, najdete ve zpravodajských kategoriích podle trhu.For a list of possible news categories that you may specify, see News Categories by Market.

Odpověď pro získání zpráv podle kategorie je skoro stejná jako pro získání obecných zpráv.The response for getting news by category is almost the same as getting general news. Články jsou ale všechny ze zadané kategorie.However, the articles are all from the specified category.

Získání hlavních zprávGetting headline news

Pokud chcete požádat o hlavní zpravodajské články a získat články ze všech zpravodajských kategorií, pošlete do Bingu tento požadavek GET:To request headline news articles and get articles from all news categories, send the following GET request to Bing:

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

Nezahrnujte parametr dotazu category.Do not include the category query parameter.

Odpověď pro získání hlavních zpráv je skoro stejná jako pro získání dnešních nejčtenějších zpráv.The response for getting headline news is the same as getting today's top news. Pokud je článek hlavním článkem, jeho pole headline je nastavené na true.If the article is a headline article, its headline field is set to true.

Ve výchozím nastavení odpověď obsahuje až 12 hlavních článků.By default, the response includes up to 12 headline articles. Pokud chcete počet hlavních článků k vrácení změnit, zadejte parametr dotazu headlineCount.To change the number of headline articles to return, specify the headlineCount query parameter. Odpověď obsahuje také až čtyři nehlavní články v každé kategorii zpráv.The response also includes up to four non-headline articles per news category.

Odpověď počítá shluky článků jako jeden článek.The response counts clusters as one article. Protože shluk článků může obsahovat několik článků, může odpověď obsahovat více než 12 hlavních článků a více než čtyři nehlavní články v každé kategorii.Because a cluster may have several articles, the response may include more than 12 headline articles and more than four non-headline articles per category.

Pokud chcete získat zpravodajská témata, která jsou na vzestupu na sociálních sítích, pošlete do Bingu tento požadavek GET:To get news topics that are trending on social networks, send the following GET request to Bing:

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

Poznámka

Témata na vzestupu jsou dostupná jenom na americkém a čínském trhu.Trending Topics is available only in the en-US and zh-CN markets.

Odpovědí na předchozí požadavek je následující kód JSON.The following JSON is the response to the preceding request. Každý zpravodajský článek na vzestupu obsahuje související obrázek, příznak mimořádné zprávy a adresu URL výsledků hledání článku na Bingu.Each trending news article includes a related image, breaking news flag, and a URL to the Bing search results for the article. Použijte adresu URL v poli webSearchUrl k přenesení uživatele na stránku s výsledky hledání Bingu.Use the URL in the webSearchUrl field to take the user to the Bing search results page. Nebo použijte text dotazu k volání rozhraní API Bingu pro vyhledávání na webu, abyste výsledky sami zobrazili.Or, use the query text to call the Web Search API to display the results yourself.

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

    ...

    ]
}

Pokud existují další články, které se zpravodajským článkem souvisejí, může zpravodajský článek obsahovat pole clusteredArticles.If there are other articles that are related to a news article, the news article may include the clusteredArticles field. Následuje ukázka článku se shlukem takových článků.The following shows an article with clustered articles.

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

Omezování požadavkůThrottling requests

Služba a typ vašeho předplatného určuje počet dotazů, které můžete provést za sekundu (QPS).The service and your subscription type determine the number of queries per second (QPS) that you can make. Ujistěte se, že vaše aplikace obsahuje logiku potřebnou k nepřekročení vaší kvóty.Make sure your application includes the logic to stay within your quota. Při dosažení nebo překročení limitu QPS požadavek selže a vrátí se stavový kód HTTP 429.If the QPS limit is met or exceeded, the request fails and an HTTP 429 status code is returned. Odpověď zahrnuje hlavičku Retry-After, která označuje, jak dlouho je nutné počkat před odesláním dalšího požadavku.The response includes the Retry-After header, which indicates how long you must wait before sending another request.

Odepření služby a omezováníDenial-of-service versus throttling

Služba rozlišuje mezi útokem s cílem odepření služby (DoS) a porušením QPS.The service makes a differentiation between a denial-of-service (DoS) attack and a QPS violation. Pokud služba má podezření na útok DoS, požadavek bude úspěšný (stavový kód HTTP je 200 OK).If the service suspects a DoS attack, the request succeeds (HTTP status code is 200 OK). Text odpovědi však bude prázdný.However, the body of the response is empty.

Další krokyNext steps

Pokud chcete rychle začít s vaším prvním požadavkem, projděte si popis vytvoření prvního požadavku.To get started quickly with your first request, see Making Your First Request.

Seznamte se s referenčními informacemi k rozhraní API Bingu pro vyhledávání zpráv v7.Familiarize yourself with the Bing News Search API v7 reference. Tyto referenční informace obsahují seznam koncových bodů, hlaviček a parametrů dotazů, které můžete použít při odesílání požadavků na výsledky hledání.The reference contains the list of endpoints, headers, and query parameters that you'd use to request search results. Obsahují také definice objektů odpovědi.It also includes definitions of the response objects.

Pokud chcete zlepšit uživatelské prostředí vyhledávacího pole, přečtěte si o rozhraní API pro automatické návrhy Bingu.To improve your search box user experience, see Bing Autosuggest API. Zatímco uživatel zadává termín dotazu, můžete zavoláním tohoto rozhraní API získat relevantní termíny dotazů, které použili jiní uživatelé.As the user enters their query term, you can call this API to get relevant query terms that were used by others.

Nezapomeňte si přečíst požadavky Bingu na zobrazení a použití, abyste neporušili žádná pravidla používání výsledků hledání.Be sure to read Bing Use and Display Requirements so you don't break any of the rules about using the search results.