什麼是專案 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 預覽,藉由對於預覽的 URL 指派的查詢將 Web 要求傳送至端點。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.

您或代表您的第三方不得使用、保留、儲存、快取、共用或散發 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 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