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

什么是项目答案搜索?What is Project Answer Search?

项目答案搜索 API 使用 Bing v7 终结点获取疑问式询问的答案。Project Answer Search API uses the Bing v7 endpoint to get answers to interrogative queries. “地球的周长是多少?”此类问题A question such as "What is the circumference of the earth?" 返回带有事实信息的答案。returns an answer with factual information. 对人员、地点或事物的查询则返回与查询识别的实体相关的信息。A query for a person, place, or thing returns information about the entity identified by the query. 这些方案在对话机器人、消息应用、读取器等应用程序中十分有用。These scenarios can be useful in applications such as conversational bots, messaging apps, readers, etc.

查询返回取决于查询方案的响应:始终返回网页,同时如果相关,则返回事实和/或实体Queries return responses that depend on the query scenario: webpages are always returned, while facts and/or entities are returned if relevant.

终结点Endpoint

要获取问题答案或人员、地点或事物相关信息,请向答案搜索 API 终结点发送请求。To get answers to a question or information about a person, place, or thing, send a request to the Answer Search API endpoint. 使用标头和 URL 参数获取各类规范。Use the headers and URL parameters for various specifications. 借助有效令牌包括“Ocp-Apim-Subscription-Key” 标头。Include Ocp-Apim-Subscription-Key header with a valid token. 市场参数是必需的。The market parameter is required. 当前仅支持 en-us 市场。Only en-us market is currently supported.

以下查询可获取此问题的答案:“地球的周长是多少?”The following query gets answers to the question: "What is the circumference of the earth?"

得:GET:

https://api.labs.cognitive.microsoft.com/answerSearch/v7.0/search?q=what+is+circumference+of+the=earth?&mkt=en-us

需要使用 URL 参数 q= 来指定搜索对象。The URL parameter q= is required to specify the object of search.

响应对象Response object

响应包括 HTTP 标头、网页、事实和/或实体。The response includes HTTP headers, webpages, facts, and/or entities.

BingAPIs-TraceId: AB2E75C998614ADB8EBF5110DF648298
X-MSEdge-ClientID: 1E48FC4F7B8768C80B14F7997A106906
BingAPIs-SessionId: 0504DDD6DAE84861A4842306F8DA7A58
BingAPIs-Market: en-US
X-MSEdge-Ref: Ref A: AB2E75C998614ADB8EBF5110DF648298 Ref B: CO1EDGE0322 Ref C: 2018-04-19T19:57:13Z

JSON Response:

{
  "_type": "SearchResponse",
  "queryContext": {
    "originalQuery": "what is the circumference of earth"
  },
  "webPages": {
    "webSearchUrl": "https://www.bing.com/search?q\u003dwhat+is+the+circumference+of+earth",
    "totalEstimatedMatches": 217000,
    "value": [
      {
        "id": "https://www.bingapis.com/api/v7/#WebPages.0",
        "name": "Circumference of the Earth - Universe Today",
        "url": "https://www.universetoday.com/26461/circumference-of-the-earth/",
        "isFamilyFriendly": true,
        "displayUrl": "https://www.universetoday.com/26461/circumference-of-the-earth",
        "snippet": "The circumference of the Earth in kilometers is 40,075 km, and the circumference of the Earth in miles is 24,901. In other words, if you could drive your car around the equator of the Earth (yes, even over the oceans), you’d put on an extra 40,075 km on the odometer.",
        "deepLinks": [
          {
            "name": "About Earth",
            "url": "https://www.universetoday.com/14382/10-interesting-facts-about-planet-earth/"
          }
        ],
        "dateLastCrawled": "2018-04-12T14:13:00.0000000Z",
        "language": "en"
      },
      {
        "id": "https://www.bingapis.com/api/v7/#WebPages.1",
        "name": "Earth - Wikipedia",
        "url": "https://en.wikipedia.org/wiki/Earth",
        "about": [
          {
            "name": "Earth"
          },
          {
            "name": "Earth"
          }
        ],
        "isFamilyFriendly": true,
        "displayUrl": "https://en.wikipedia.org/wiki/Earth",
        "snippet": "Circumference: 40 075.017 km equatorial (24 901.461 mi) ... Earth is the third planet from the Sun and the only object in the Universe known to harbor life.",
        "deepLinks": [
          {
            "name": "Moon",
            "url": "https://en.wikipedia.org/wiki/Moon"
          },
          {
            "name": "Planet",
            "url": "https://en.wikipedia.org/wiki/Planet"
          },
          {
            "name": "Quasi-Satellites",
            "url": "https://en.wikipedia.org/wiki/Quasi-satellite"
          },
          {
            "name": "World Population",
            "url": "https://en.wikipedia.org/wiki/World_population"
          },
   . . .

    ]
  },
  "entities": {
    "value": [
      {
        "id": "https://www.bingapis.com/api/v7/#Entities.0",
        "contractualRules": [
          {
            "_type": "ContractualRules/LicenseAttribution",
            "targetPropertyName": "description",
            "mustBeCloseToContent": true,
            "license": {
              "name": "CC-BY-SA",
              "url": "https://creativecommons.org/licenses/by-sa/3.0/"
            },
            "licenseNotice": "Text under CC-BY-SA license"
          },
          {
            "_type": "ContractualRules/LinkAttribution",
            "targetPropertyName": "description",
            "mustBeCloseToContent": true,
            "text": "Wikipedia",
            "url": "https://en.wikipedia.org/wiki/Earth"
          },
          {
            "_type": "ContractualRules/MediaAttribution",
            "targetPropertyName": "image",
            "mustBeCloseToContent": true,
            "url": "https://en.wikipedia.org/wiki/Earth"
          }
        ],
        "webSearchUrl": "https://www.bing.com/entityexplore?q\u003dEarth\u0026filters\u003dsid:%226ddb3372-4801-5567-321e-e8a53bd774a4%22\u0026elv\u003dAXXfrEiqqD9r3GuelwApulpmymQx!ODfuQu*veOQHkvP0!Zbvi5F5tVcMSDJvDEWiQWwrdueYTtIszgj03oFQHykYYLYgq3q5!Sf00QxXGIS",
        "name": "Earth",
        "image": {
          "name": "Earth",
          "thumbnailUrl": "https://www.bing.com/th?id\u003dA3ab623665ab412f386c162bd29f0683a\u0026w\u003d110\u0026h\u003d110\u0026c\u003d7\u0026rs\u003d1\u0026qlt\u003d80\u0026cdv\u003d1\u0026pid\u003d16.1",
          "provider": [
            {
              "_type": "Organization",
              "url": "https://en.wikipedia.org/wiki/Earth"
            }
          ],
          "hostPageUrl": "https://upload.wikimedia.org/wikipedia/commons/9/97/The_Earth_seen_from_Apollo_17.jpg",
          "width": 110,
          "height": 110,
          "sourceWidth": 799,
          "sourceHeight": 800
        },
        "description": "Earth is the third planet from the Sun and the only object in the Universe known to harbor life. According to radiometric dating and other sources of evidence, Earth formed over 4.5 billion years ago. Earth\u0027s gravity interacts with other objects in space, especially the Sun and the Moon, Earth\u0027s only natural satellite. Earth revolves around the Sun in 365.26 days, a period known as an Earth year. During this time, Earth rotates about its axis about 366.26 times.",
        "entityPresentationInfo": {
          "entityScenario": "DominantEntity",
          "entityTypeHints": [
            "Generic"
          ]
        },
        "bingId": "6ddb3372-4801-5567-321e-e8a53bd774a4"
      }
    ]
  },
  "facts": {
    "id": "https://www.bingapis.com/api/v7/#Facts",
    "contractualRules": [
      {
        "_type": "ContractualRules/LinkAttribution",
        "text": "www.universetoday.com/26461/circumference-of-the-earth/",
        "url": "http://www.universetoday.com/26461/circumference-of-the-earth/"
      }
    ],
    "attributions": [
      {
        "providerDisplayName": "www.universetoday.com/26461/circumference-of-the-earth/",
        "seeMoreUrl": "http://www.universetoday.com/26461/circumference-of-the-earth/"
      }
    ],
    "value": [
      {
        "description": "The circumference of the Earth in kilometers is 40,075 km, and the circumference of the Earth in miles is 24,901. In other words, if you could drive your car around the equator of the Earth (yes, even over the oceans), you’d put on an extra 40,075 km on the odometer.",
        "subjectName": ""
      }
    ]
  },
  "rankingResponse": {
    "mainline": {
      "items": [
        {
          "answerType": "Facts",
          "value": {
            "id": "https://www.bingapis.com/api/v7/#Facts"
          }
        },
        {
          "answerType": "WebPages",
          "resultIndex": 0,
          "value": {
            "id": "https://www.bingapis.com/api/v7/#WebPages.0"
          }
        },
        {
          "answerType": "WebPages",
          "resultIndex": 1,
          "value": {
            "id": "https://www.bingapis.com/api/v7/#WebPages.1"
          }
        },
        {
          "answerType": "WebPages",
          "resultIndex": 2,
          "value": {
            "id": "https://www.bingapis.com/api/v7/#WebPages.2"
          }
        },
        
        . . . 
      ]
    },
    "sidebar": {
      "items": [
        {
          "answerType": "Entities",
          "resultIndex": 0,
          "value": {
            "id": "https://www.bingapis.com/api/v7/#Entities.0"
          }
        }
      ]
    }
  }
}

使用条款Terms of use

项目答案搜索和项目视频趋势受必应搜索使用和显示要求约束。Project Answer Search and Project Video Trends are subject to the Bing Search Use and Display Requirements.

你或代表你的第三方不得出于测试、开发、定型、分发或提供任何非 Microsoft 服务或功能目的使用、保留、存储、缓存、共享或分发来自 URL 预览 API 的任何数据。You, or a third party on your behalf, may not use, retain, store, cache, share, or distribute any data from the URL Preview API for the purpose of testing, developing, training, distributing or making available any non-Microsoft service or feature.

限制请求Throttling requests

服务和订阅类型决定了每秒可以发出的查询数 (QPS)。The service and your subscription type determine the number of queries per second (QPS) that you can make. 请确保应用程序包含防止超出配额限制的逻辑。Make sure your application includes the logic to stay within your quota. 如果达到或超出 QPS 限制,则请求会失败,系统会返回 HTTP 429 状态代码。If the QPS limit is met or exceeded, the request fails and an HTTP 429 status code is returned. 响应包含 Retry-After 标头,该标头指示需等待多久才能发送另一请求。The response includes the Retry-After header, which indicates how long you must wait before sending another request.

拒绝服务与限制Denial-of-service versus throttling

该服务区分拒绝服务 (DoS) 攻击和 QPS 违规。The service makes a differentiation between a denial-of-service (DoS) attack and a QPS violation. 如果该服务怀疑存在 DoS 攻击,则请求会成功(HTTP 状态代码为“200 正常”)。If the service suspects a DoS attack, the request succeeds (HTTP status code is 200 OK). 但是,响应正文为空。However, the body of the response is empty.

数据属性Data attribution

项目答案搜索响应包含第三方拥有的信息。Project Answer Search responses contain information owned by third parties. 有责任确保使用适当,例如通过遵守用户体验可能依据的任何 Creative Commons 许可证要求。You are responsible to ensure your use is appropriate, for example by complying with any creative commons license your user experience may rely on.

如果答案或结果包含 contractualRulesattributionsprovider 字段,则必须对数据归类。If an answer or result includes the contractualRules, attributions, or provider fields, you must attribute the data. 如果答案不包含这些字段中的任意一个,则无需进行归属。If the answer does not include any of these fields, no attribution is required. 如果答案包括 contractualRules 字段以及 attributions 和/或 provider 字段,则必须使用合同规则对数据进行归属。If the answer includes the contractualRules field and the attributions and/or provider fields, you must use the contractual rules to attribute the data.

以下示例显示了包括 MediaAttribution 合同规则的实体和包括 provider 字段的图像。The following example shows an entity that includes a MediaAttribution contractual rule and an Image that includes a provider field. MediaAttribution 规则将图像识别为规则的目标,因此将忽略图像的 provider 字段,改用 MediaAttribution 规则提供属性。The MediaAttribution rule identifies the image as the target of the rule, so you'd ignore the image's provider field and instead use the MediaAttribution rule to provide attribution.

        "value" : [{
            "contractualRules" : [
                . . .
                {
                    "_type" : "ContractualRules\/MediaAttribution",
                    "targetPropertyName" : "image",
                    "mustBeCloseToContent" : true,
                    "url" : "http:\/\/en.wikipedia.org\/wiki\/Space_Needle"
                }
            ],
            . . .
            "image" : {
                "name" : "Space Needle",
                "thumbnailUrl" : "https:\/\/www.bing.com\/th?id=A46378861201...",
                "provider" : [{
                    "_type" : "Organization",
                    "url" : "http:\/\/en.wikipedia.org\/wiki\/Space_Needle"
                }],
                "hostPageUrl" : "http:\/\/www.citydictionary.com\/Uploaded...",
                "width" : 110,
                "height" : 110
            },
            . . .
        }]

如果合同规则包括 targetPropertyName 字段,则该规则仅适用于目标字段。If a contractual rule includes the targetPropertyName field, the rule applies only to the targeted field. 否则,该规则适用于包含 contractualRules 字段的父对象。Otherwise, the rule applies to the parent object that contains the contractualRules field.

在以下示例中,LinkAttribution 规则包含 targetPropertyName 字段,因此该规则适用于 description 字段。In the following example, the LinkAttribution rule includes the targetPropertyName field, so the rule applies to the description field. 对于适用于特定字段的规则,必须包括紧接目标数据的一行,其中目标数据包含指向提供程序网站的超链接。For rules that apply to specific fields, you must include a line immediately following the targeted data that contains a hyperlink to the provider's website. 例如,要对描述进行归属,请包括紧接描述文本的一行,其中描述文本包含指向提供程序网站上数据的超链接,在这种情况下创建指向 en.wikipedia.org 的链接。For example, to attribute the description, include a line immediately following the description text that contains a hyperlink to the data on the provider's website, in this case create a link to en.wikipedia.org.

"entities" : {  
    "value" : [{  
            . . .  
            "description" : "Peyton Williams Manning is a former American....",  
            . . .  
            "contractualRules" : [{  
                    "_type" : "ContractualRules\/LinkAttribution",  
                    "targetPropertyName" : "description",  
                    "mustBeCloseToContent" : true,  
                    "text" : "en.wikipedia.org",  
                    "url" : "http:\/\/www.bing.com\/cr?IG=B8AD73..."  
                 },  
            . . .  
  

许可证属性License Attribution

如果合同规则列表包括 LicenseAttribution 规则,则必须在紧接许可证适用内容的一行上显示通知。If the list of contractual rules includes a LicenseAttribution rule, you must display the notice on the line immediately following the content that the license applies to. LicenseAttribution 规则使用 targetPropertyName 字段识别许可证适用的属性。The LicenseAttribution rule uses the targetPropertyName field to identify the property that the license applies to.

以下内容显示了包括 LicenseAttribution 规则的示例。The following shows an example that includes a LicenseAttribution rule.

许可证属性

你显示的许可证通知必须包括指向包含许可证相关信息的网站的超链接。The license notice that you display must include a hyperlink to the website that contains information about the license. 通常会将许可证名称作为超链接。Typically, you make the name of the license a hyperlink. 例如,如果通知是“Text under CC-BY-SA”许可证 ,其中 CC-BY-SA 是许可证名称,则使 CC-BY-SA 成为超链接。For example, if the notice is Text under CC-BY-SA license and CC-BY-SA is the name of the license, you would make CC-BY-SA a hyperlink.

LinkAttributionTextAttribution 规则通常用于识别数据提供程序。The LinkAttribution and TextAttribution rules are typically used to identify the provider of the data. targetPropertyName 字段识别该规则适用的字段。The targetPropertyName field identifies the field that the rule applies to.

要归属提供程序,则包括紧跟属性适用内容的一行(例如,目标字段)。To attribute the providers, include a line immediately following the content that the attributions apply to (for example, the targeted field). 应明确标记该行,以指示提供程序是数据的来源。The line should be clearly labeled to indicate that the providers are the source of the data. 例如,“数据来自:en.wikipedia.org”。For example, "Data from: en.wikipedia.org". 对于 LinkAttribution 规则,必须创建指向提供程序网站的超链接。For LinkAttribution rules, you must create a hyperlink to the provider's website.

以下内容显示了包括 LinkAttributionTextAttribution 规则的示例。The following shows an example that includes LinkAttribution and TextAttribution rules.

链接文本属性

媒体属性Media Attribution

如果实体包括图像并且将其显示,则必须提供指向提供程序网站的点击链接。If the entity includes an image and you display it, you must provide a click-through link to the provider's website. 如果实体包括 MediaAttribution 规则,则使用规则的 URL 创建点击链接。If the entity includes a MediaAttribution rule, use the rule's URL to create the click-through link. 否则,请使用包括在图像的 provider 字段中的 URL 创建点击链接。Otherwise, use the URL included in the image's provider field to create the click-through link.

以下内容显示了包括图像的 provider 字段和合同规则的示例。The following shows an example that includes an image's provider field and contractual rules. 因为该示例包括合同规则,则将忽略图像的 provider 字段并应用 MediaAttribution 规则。Because the example includes the contractual rule, you will ignore the image's provider field and apply the MediaAttribution rule.

媒体属性

后续步骤Next steps