什麼是專案答案搜尋?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: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

專案答案搜尋和專案視訊趨勢都受限於 Bing 搜尋使用和顯示需求Project Answer Search and Project Video Trends are subject to the Bing Search Use and Display Requirements.

您或代表您的第三方可能無法使用、保留、儲存、快取、共用或散發 URL 預覽 API 的任何資料,以進行測試、開發、訓練、散發或提供給任何非 Microsoft 服務或功能。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. 例如,若要屬性化描述,請在描述文字之後立即加入一行,其中包含提供者網站的超連結。在本例中,請建立 contoso.com 的連結。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. 例如,如果通知是 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