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

什么是项目 URL 预览?What is Project URL Preview?

URL 预览终结点采用 URL 查询参数并返回 JSON 响应,其中包含目标资源的名称、简要说明以及要在预览中显示的图像的链接。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. 响应还包含 isFamilyFriendly 标志,指示 URL 是否包含成人、盗版或其他非法内容。The response also includes the isFamilyFriendly flag that indicates whether the URL contains adult, pirated, or other illegal content.

若要获取 URL 预览结果,请提交 GET 请求,并在 Ocp-Apim-Subscription-Key 标头中包含有效令牌 :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

响应: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"
  }
}

方案Scenarios

URL 预览 API 支持 Web 资源的简要描述。The URL Preview API supports brief descriptions of Web resources. 开发人员可使用其构建丰富的预览体验。Developers use it to build rich preview experiences. 用户可共享网页、新闻、博客、论坛等或为其添加书签。此 API 还可用于内容审核。Users can share or bookmark webpages, news, blogs, forums, etc. This API can also be used for content moderation.

应用程序使用 URL 预览将 Web 请求发送到终结点,并将一个查询分配给要预览的 URL。Applications use URL Preview to send Web requests to the endpoint with a query assigned to the URL to preview. JSON 响应包含后列预览信息:名称、资源描述、familyFriendly 标志以及链接,通过这些链接可在线访问代表性图像和完整资源 。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.

使用条款Terms of use

仅使用项目 URL 预览中的数据,在社交媒体、聊天机器人或类似产品上共享的由最终用户启动的 URL 中显示使用超链接链接到其源站点的预览代码片段和缩略图图像。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. 不得复制、存储或缓存从项目 URL 预览收到的任何数据。D not copy, store, or cache any data you receive from Project URL Preview. 需执行后列操作请求:禁用可能从网站或内容所有者处收到的预览。Honor any requests to disable previews that you may receive from website or content owners.

你或代表你的第三方不得出于测试、开发、训练、分发或提供任何非 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 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.

后续步骤Next steps