¿Qué es Project URL Preview?What is Project URL Preview?

El punto de conexión de URL Preview adopta un parámetro de consulta de dirección URL y devuelve una respuesta JSON con el nombre del recurso de destino, una breve descripción y un vínculo a una imagen para mostrarla en una vista previa.The URL Preview endpoint takes a URL query parameter and returns a JSON response with the name of the target resource, a brief description, and a link to an image to display in a preview. La respuesta incluye también la marca isFamilyFriendly, que indica si la dirección URL contiene contenido para adultos, pirateado o ilegal.The response also includes the isFamilyFriendly flag that indicates whether the URL contains adult, pirated, or other illegal content.

Para obtener los resultados de URL Preview, envíe una solicitud GET e incluya el encabezado Ocp-Apim-Subscription-Key con un token válido:To get URL preview results, submit a GET request, and include the Ocp-Apim-Subscription-Key header with a valid token:

https://api.labs.cognitive.microsoft.com/urlpreview/v7.0/search?q=https://swiftkey.com

La respuesta:The response:

HTTP Headers:
BingAPIs-TraceId: 3CC74C94769440C0851D9DF0869FCE7F
BingAPIs-SessionId: 52219085A6364692958C9C83983A0DBA
X-MSEdge-ClientID: 13D44DC2DE946B4B0F25460CDF036AD6
BingAPIs-Market: en-US
X-MSEdge-Ref: Ref A: 3CC74C94769440C0851D9DF0869FCE7F Ref B: CO1EDGE0315 Ref C: 2018-04-11T18:47:40Z
{
  "_type": "WebPage",
  "name": "SwiftKey - Smart prediction technology for easier mobile typing",
  "url": "https:\/\/swiftkey.com\/en",
  "description": "Discover the best Android and iPhone and iPad apps for faster, easier typing with emoji, colorful themes and more - download SwiftKey Keyboard free today.",
  "isFamilyFriendly": true,
  "primaryImageOfPage": {
    "contentUrl": "https:\/\/swiftkey.com\/images\/og\/default.jpg"
  }
}

EscenariosScenarios

URL Preview API admite descripciones breves de recursos web.The URL Preview API supports brief descriptions of Web resources. Los desarrolladores la usan para crear experiencias enriquecidas de vista previa.Developers use it to build rich preview experiences. Los usuarios pueden compartir o marcar páginas web, noticias, blogs, foros, etc. Esta API también puede utilizarse para moderación de contenido.Users can share or bookmark webpages, news, blogs, forums, etc. This API can also be used for content moderation.

Las aplicaciones usan URL Preview para enviar solicitudes web al punto de conexión con una consulta asignada a la dirección URL para la vista previa.Applications use URL Preview to send Web requests to the endpoint with a query assigned to the URL to preview. La respuesta JSON contiene la información de vista previa: el nombre, la descripción del recurso, la marca familyFriendly y los vínculos que proporcionen acceso a una imagen representativa y al recurso completo en línea.The JSON response contains the preview information: name, description of the resource, familyFriendly flag, and links that provide access to a representative image and to the complete resource online.

Términos de usoTerms of use

Utilice únicamente los datos de Project URL Preview para mostrar fragmentos de código de versión preliminar e imágenes en miniatura con hipervínculos a sus sitios de origen, en la URL iniciada por el usuario final compartida en redes sociales, bot de chat u ofertas similares.Use only the data from Project URL Preview to display preview snippets and thumbnail images hyperlinked to their source sites, in end user-initiated URL sharing on social media, chat bot or similar offerings. No copie, almacene ni almacene en caché los datos que reciba de Project URL Preview.D not copy, store, or cache any data you receive from Project URL Preview. Respete las solicitudes para deshabilitar las versiones preliminares que pueda recibir del sitio web o los propietarios del contenido.Honor any requests to disable previews that you may receive from website or content owners.

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 poner 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 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 determine the number of queries per second (QPS) that you can make. Asegúrese de que la aplicación incluye la lógica necesaria para mantenerse dentro de su cuota.Make sure your application includes the logic to stay within your quota. Si se alcanza el límite de consultas por segundo, o se supera, se produce un error en la solicitud y se devolverá el código de estado HTTP 429.If the QPS limit is met or exceeded, the request fails and an HTTP 429 status code is returned. La respuesta incluye el encabezado Retry-After, que indica cuánto tiempo debe esperar antes de enviar otra solicitud.The response includes the Retry-After header, which indicates how long you must wait before sending another request.

Denegación de servicio frente a LimitaciónDenial-of-service versus throttling

El servicio diferencia entre un ataque de denegación de servicio (DoS) y una infracción de las consultas por segundo.The service makes a differentiation between a denial-of-service (DoS) attack and a 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).If the service suspects a DoS attack, the request succeeds (HTTP status code is 200 OK). Sin embargo, el cuerpo de la respuesta está vacío.However, the body of the response is empty.

Pasos siguientesNext steps