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 determines the number of queries that you may make per second (QPS). アプリケーションがクォータを超えないために必要なロジックを含んでいることを確認してください。You should ensure that your application includes the logic necessary to stay within your quota. QPS を超過した場合、要求は HTTP 状態コード 429 で失敗します。If you exceed your QPS, the request fails with HTTP status code 429. また、応答には Retry-After ヘッダーも含まれています。これには、別の要求を送信するまでに待つ必要がある秒数が格納されます。The response also includes the Retry-After header, which contains the number of seconds that you should wait before sending another request.

サービス拒否 (DOS) と調整Denial of Service (DOS) versus Throttling

サービスは、DOS 攻撃と QPS 違反を区別します。The service differentiates between a DOS attack and QPS violation. サービスがサービス拒否攻撃を疑っている場合、要求は成功します (HTTP 状態コードは 200 OK) が、応答の本文は空です。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.

次の手順Next steps