¿Qué es Project Answer Search?What is Project Answer Search?

Project Answer Search API usa el punto de conexión Bing v7 para obtener respuestas a preguntas.Project Answer Search API uses the Bing v7 endpoint to get answers to interrogative queries. Una pregunta como "What is the circumference of the earth?" (¿Cuál es la circunferencia de la Tierra?)A question such as "What is the circumference of the earth?" devuelve una respuesta con información objetiva.returns an answer with factual information. Una consulta sobre una persona, un lugar o una cosa devuelve información sobre la entidad identificada por la consulta.A query for a person, place, or thing returns information about the entity identified by the query. Estos escenarios pueden resultar útiles en aplicaciones como bots de conversaciones, aplicaciones de mensajería, lectores, etc.These scenarios can be useful in applications such as conversational bots, messaging apps, readers, etc.

Las consultas devuelven respuestas que dependen del escenario de consulta: siempre se devuelven páginas web, mientras que los hechos o las entidades se devuelven si resulta pertinente.Queries return responses that depend on the query scenario: webpages are always returned, while facts and/or entities are returned if relevant.

Punto de conexiónEndpoint

Para obtener respuestas a una pregunta o información sobre una persona, un lugar o una cosa, envíe una solicitud al punto de conexión de 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. Use los encabezados y parámetros de dirección URL para varias especificaciones.Use the headers and URL parameters for various specifications. Incluya el encabezado Ocp-Apim-Subscription-Key con un token válido.Include Ocp-Apim-Subscription-Key header with a valid token. El parámetro market es obligatorio.The market parameter is required. Solo se admite el parámetro market en-us actualmente.Only en-us market is currently supported.

La siguiente consulta obtiene respuestas a la pregunta: "What is the circumference of the earth?" (¿Cuál es la circunferencia de la Tierra?).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

El parámetro de dirección URL q= es obligatorio para especificar el objeto de búsqueda.The URL parameter q= is required to specify the object of search.

Objeto de respuestaResponse object

La respuesta incluye encabezados HTTP, páginas web, hechos o entidades.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"
          }
        }
      ]
    }
  }
}

Términos de usoTerms of use

Project Answer Search y Project Video Trends están sujetas a los requisitos de uso y visualización de Bing Search.Project Answer Search and Project Video Trends are subject to the Bing Search Use and Display Requirements.

Tenga en cuenta que ni usted, ni un tercero en su nombre, pueden usar, retener, guardar, almacenar en caché, compartir o distribuir datos de URL Preview API con el fin de probar, desarrollar, entrenar, distribuir o ponerlos a disposición cualquier servicio o característica que no sea de 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.

Solicitudes de limitaciónThrottling requests

El servicio y el tipo de suscripción determinan el número de consultas que puede realizar por segundo (QPS).The service and your subscription type determines the number of queries that you may make per second (QPS). Debe asegurarse de que la aplicación incluye la lógica necesaria para mantenerse dentro de su cuota.You should ensure that your application includes the logic necessary to stay within your quota. Si se supera el QPS, la solicitud produce un error con código de estado HTTP 429.If you exceed your QPS, the request fails with HTTP status code 429. La respuesta también incluye el encabezado Retry-After, que contiene el número de segundos que debe esperar antes de enviar otra solicitud.The response also includes the Retry-After header, which contains the number of seconds that you should wait before sending another request.

Denegación de servicio (DOS) frente a LimitaciónDenial of Service (DOS) versus Throttling

El servicio diferencia entre un ataque de DOS y una infracción del número máximo de solicitudes por segundo (QPS).The service differentiates between a DOS attack and QPS violation. Si el servicio sospecha de un ataque de denegación de servicio, la solicitud se realiza correctamente (código de estado HTTP 200 OK); sin embargo, el cuerpo de la respuesta está vacío.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.

Atribución de datosData attribution

Las respuestas de Project Answer Search contienen información que es propiedad de terceros.Project Answer Search responses contain information owned by third parties. Usted es responsable de garantizar que su uso sea apropiado; por ejemplo, debe cumplir con cualquier licencia de Creative Commons en la que se base su experiencia de usuario.You are responsible to ensure your use is appropriate, for example by complying with any creative commons license your user experience may rely on.

Si una respuesta o resultado incluye los campos contractualRules, attributions o provider, debe atribuir los datos.If an answer or result includes the contractualRules, attributions, or provider fields, you must attribute the data. Si la respuesta no incluye ninguno de estos campos, no es necesario realizar la atribución.If the answer does not include any of these fields, no attribution is required. Si la respuesta incluye el campo contractualRules y los campos attributions o provider, debe usar las reglas contractuales para atribuir los datos.If the answer includes the contractualRules field and the attributions and/or provider fields, you must use the contractual rules to attribute the data.

En el siguiente ejemplo se muestra una entidad que incluye una regla contractual MediaAttribution y una imagen que incluye un campo provider.The following example shows an entity that includes a MediaAttribution contractual rule and an Image that includes a provider field. La regla MediaAttribution identifica la imagen como el destino de la regla, por lo que debe ignorar el campo provider de la imagen y, en su lugar, usar la regla MediaAttribution para proporcionar la atribución.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
            },
            . . .
        }]

Si una regla contractual incluye el campo targetPropertyName, la regla solo se aplica al campo de destino.If a contractual rule includes the targetPropertyName field, the rule applies only to the targeted field. De lo contrario, la regla se aplica al objeto principal que contiene el campo contractualRules.Otherwise, the rule applies to the parent object that contains the contractualRules field.

En el siguiente ejemplo, la regla LinkAttribution incluye el campo targetPropertyName, por lo que la regla se aplica al campo description.In the following example, the LinkAttribution rule includes the targetPropertyName field, so the rule applies to the description field. En cuanto a las reglas que se aplican a campos específicos, debe incluir una línea inmediatamente después de los datos de destino que contienen un hipervínculo al sitio web del proveedor.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. Por ejemplo, para atribuir la descripción, incluya una línea inmediatamente después del texto descriptivo que contiene un hipervínculo a los datos del sitio web del proveedor; en este caso, debe crear un vínculo a es.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..."  
                 },  
            . . .  

Atribución de licenciasLicense Attribution

Si la lista de reglas contractuales incluye una regla LicenseAttribution, debe mostrar el aviso en la línea inmediatamente después del contenido al que se aplica la licencia.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. La regla LicenseAttribution usa el campo targetPropertyName para identificar la propiedad a la que se aplica la licencia.The LicenseAttribution rule uses the targetPropertyName field to identify the property that the license applies to.

A continuación, se muestra un ejemplo que incluye una regla LicenseAttribution.The following shows an example that includes a LicenseAttribution rule.

Atribución de licencias

El aviso de licencia que muestre debe incluir un hipervínculo al sitio web que contiene información sobre la licencia.The license notice that you display must include a hyperlink to the website that contains information about the license. Por lo general, debe convertir el nombre de la licencia en un hipervínculo.Typically, you make the name of the license a hyperlink. Por ejemplo, si el aviso es Texto con licencia CC-BY-SA y CC-BY-SA es el nombre de la licencia, debe hacer que CC-BY-SA sea un hipervínculo.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.

Las reglas LinkAttribution y TextAttribution se usan generalmente para identificar al proveedor de los datos.The LinkAttribution and TextAttribution rules are typically used to identify the provider of the data. El campo targetPropertyName identifica el campo al que se aplica la regla.The targetPropertyName field identifies the field that the rule applies to.

Para atribuir los proveedores, incluya una línea inmediatamente después del contenido al que se aplican las atribuciones (por ejemplo, el campo de destino).To attribute the providers, include a line immediately following the content that the attributions apply to (for example, the targeted field). La línea debe estar claramente etiquetada para indicar que los proveedores son la fuente de los datos.The line should be clearly labeled to indicate that the providers are the source of the data. Por ejemplo, "Datos de: es.wikipedia.org".For example, "Data from: en.wikipedia.org". En cuanto a las reglas LinkAttribution, debe crear un hipervínculo al sitio web del proveedor.For LinkAttribution rules, you must create a hyperlink to the provider's website.

A continuación, se muestra un ejemplo que incluye las reglas LinkAttribution y TextAttribution.The following shows an example that includes LinkAttribution and TextAttribution rules.

Atribución de texto del vínculo

Atribución de mediosMedia Attribution

Si la entidad incluye una imagen y la visualiza, debe proporcionar un vínculo para obtener acceso al sitio web del proveedor con un simple clic.If the entity includes an image and you display it, you must provide a click-through link to the provider's website. Si la entidad incluye una regla MediaAttribution, use la dirección URL de la regla para crear el vínculo al cual obtener acceso haciendo clic.If the entity includes a MediaAttribution rule, use the rule's URL to create the click-through link. De lo contrario, use la dirección URL incluida en el campo provider de la imagen para crear el vínculo al que se puede acceder con un solo clic.Otherwise, use the URL included in the image's provider field to create the click-through link.

A continuación, se muestra un ejemplo que incluye el campo provider de una imagen y las reglas contractuales.The following shows an example that includes an image's provider field and contractual rules. Como el ejemplo incluye la regla contractual, debe ignorar el campo provider de la imagen y aplicar la regla MediaAttribution.Because the example includes the contractual rule, you will ignore the image's provider field and apply the MediaAttribution rule.

Atribución de medios

Pasos siguientesNext steps