Project URL Preview とはWhat is Project URL Preview?

URL Preview エンドポイントは、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 Preview API は、Web リソースの簡単な説明をサポートしています。The URL Preview API supports brief descriptions of Web resources. 開発者はこれを使用して、高度なプレビュー エクスペリエンスを構築します。Developers use it to build rich preview experiences. ユーザーは、Web ページ、ニュース、ブログ、フォーラムなどを共有したり、ブックマークしたりできます。この API は、コンテンツ モデレーションにも使用できます。Users can share or bookmark webpages, news, blogs, forums, etc. This API can also be used for content moderation.

アプリケーションは URL Preview を使用して、プレビューする 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

Project URL Preview からのデータのみを使用して、ソーシャル メディアやチャットボットなどのサービスでエンド ユーザーによって開始される 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. Project URL Preview から受信したデータは、いずれもコピー、保存、キャッシュしないでください。D not copy, store, or cache any data you receive from Project URL Preview. Web サイトやコンテンツの所有者からプレビューを無効にするよう要請があった場合は、その意向を尊重してください。Honor any requests to disable previews that you may receive from website or content owners.

お客様およびお客様の代理を務める第三者のいずれも、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 testing, developing, training, distributing or making available any non-Microsoft service or feature.

スロットル リクエストThrottling requests

サービスとサブスクリプションの種類によって、1 秒あたりのクエリ数 (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 OK)。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