Project Answer Search とはWhat is Project Answer Search?

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.

クエリでは、そのシナリオに応じた応答が返されます。Web ページは常に返されますが、事実エンティティについては、該当するクエリの場合に限り返されます。Queries return responses that depend on the query scenario: webpages are always returned, while facts and/or entities are returned if relevant.

エンドポイントEndpoint

人、場所、または物に関する質問の回答または情報を取得するには、Answer Search 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 ヘッダー、Web ページ、事実、および/またはエンティティが含まれます。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": "http://creativecommons.org/licenses/by-sa/3.0/"
            },
            "licenseNotice": "Text under CC-BY-SA license"
          },
          {
            "_type": "ContractualRules/LinkAttribution",
            "targetPropertyName": "description",
            "mustBeCloseToContent": true,
            "text": "Wikipedia",
            "url": "http://en.wikipedia.org/wiki/Earth"
          },
          {
            "_type": "ContractualRules/MediaAttribution",
            "targetPropertyName": "image",
            "mustBeCloseToContent": true,
            "url": "http://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": "http://en.wikipedia.org/wiki/Earth"
            }
          ],
          "hostPageUrl": "http://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 と Project Video Trends には、Bing Search の使用と表示に関する要件が適用されます。Project Answer Search and Project Video Trends are subject to the Bing Search Use and Display Requirements.

お客様およびお客様の代理を務める第三者のいずれも、URL Preview 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

サービスとサブスクリプションの種類によって、1 秒あたりのクエリ数 (QPS) が決まります。The service and your subscription type determines the number of queries that you may make per second (QPS). アプリケーションがクォータを超えないために必要なロジックを含んでいることを確認してください。You should ensure that your application includes the logic necessary to stay within your quota. QPS を超過した場合、要求は HTTP 状態コード 429 で失敗します。If you exceed your QPS, the request fails with HTTP status code 429. また、応答には Retry-After ヘッダーも含まれています。これには、別の要求を送信するまでに待つ必要がある秒数が格納されます。The response also includes the Retry-After header, which contains the number of seconds that you should wait before sending another request.

サービス拒否 (DOS) と調整Denial of Service (DOS) versus Throttling

サービスは、DOS 攻撃と QPS 違反を区別します。The service differentiates between a DOS attack and QPS violation. サービスがサービス拒否攻撃を疑っている場合、要求は成功します (HTTP 状態コードは 200 OK) が、応答の本文は空です。If the service suspects a denial of service attack, the request succeeds (HTTP status code is 200 OK); however, the body of the response is empty.

データの帰属表示Data attribution

Project Answer Search の応答には、第三者が所有する情報が含まれます。Project Answer Search responses contain information owned by third parties. お客様は、ユーザー エクスペリエンスで利用するクリエイティブ コモンズ ライセンスがあればそれを遵守するなど、情報を適切に利用する責任を負います。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. 特定のフィールドに適用される規則の場合、対象となるデータの直後に提供元の Web サイトへのハイパーリンクを含めた 1 行を追加する必要があります。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. たとえば、説明の帰属を表示する場合には、説明テキストの直後にデータの提供元の Web サイト上のデータへのハイパーリンクを含めた 1 行を追加します。このケースでは、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.

ライセンスの帰属表示

表示するライセンス通知には、ライセンスに関する情報を掲載している Web サイトへのハイパーリンクを含める必要があります。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 license (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.

提供元を表示するには、帰属表示を適用するコンテンツ (対象となるフィールドなど) の直後に行を 1 つ追加します。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 規則の場合、提供元の Web サイトへのハイパーリンクを作成する必要があります。For LinkAttribution rules, you must create a hyperlink to the provider's website.

LinkAttribution および TextAttribution の規則を含む例を次に示します。The following shows an example that includes LinkAttribution and TextAttribution rules.

リンクとテキストの帰属表示

メディアの帰属表示Media Attribution

エンティティに画像が含まれており、その画像を表示する場合には、提供元の Web サイトへのクリックスルー リンクを提供する必要があります。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