画像検索クエリをカスタマイズおよび提案するCustomize and suggest image search queries

警告

Bing Search API は、Cognitive Services から Bing Search Services に移行されます。Bing Search APIs are moving from Cognitive Services to Bing Search Services. 2020 年 10 月 30 日 以降、Bing Search の新しいインスタンスは、こちらに記載されているプロセスに従ってプロビジョニングする必要があります。Starting October 30, 2020, any new instances of Bing Search need to be provisioned following the process documented here. Cognitive Services を使用してプロビジョニングされた Bing Search API は、次の 3 年間、または Enterprise Agreement の終わり (どちらか先に発生した方) までサポートされます。Bing Search APIs provisioned using Cognitive Services will be supported for the next three years or until the end of your Enterprise Agreement, whichever happens first. 移行手順については、Bing Search Services に関する記事を参照してください。For migration instructions, see Bing Search Services.

この記事を使用して、クエリをカスタマイズし、Bing Image Search API に送信する検索語句を提案する方法について学習します。Use this article to learn how to customize queries and suggest search terms to send to the Bing Image Search API.

検索語句を提案するSuggest search terms

検索語句を入力するための検索ボックスがアプリに備わっている場合は、Bing Autosuggest API を利用して利便性を高めることができます。If your app has a search box where search terms are entered, you can use the Bing Autosuggest API to improve the experience. API でおすすめ検索語句をリアルタイム表示できます。The API can display suggested search terms in real time. この API は、検索語句の一部分や Cognitive Services に基づいてクエリ文字列の候補を返します。The API returns suggested query strings based on partial search terms and Cognitive Services.

クエリをピボットするPivot the query

元の検索クエリを Bing が分割できる場合、返された Images オブジェクトには pivotSuggestions が含まれます。If Bing can segment the original search query, the returned Images object contains pivotSuggestions. ピボット候補を任意の検索語句としてユーザーに表示できます。Pivot suggestions can be displayed as optional search terms to the user. たとえば、元のクエリが「Microsoft Surface」である場合、そのクエリが Bing によって MicrosoftSurface に分割され、それぞれについてピボット候補を得ることができます。For example, if the original query was Microsoft Surface, Bing might segment the query into Microsoft and Surface and provide suggested pivots for each. このような候補は、任意のクエリ語句としてユーザーに表示できます。These suggestions can be displayed as optional query terms to the user.

次の例は、Microsoft Surface に関するピボット候補を示しています。The following example shows the pivot suggestions for Microsoft Surface:

{
    "_type": "Images",
    "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=microsoft%20surface&FORM=OIIARP",
    "totalEstimatedMatches": 1000,
    "value": [...],
    "queryExpansions": [...],
    "pivotSuggestions": [{
        "pivot": "microsoft",
        "suggestions": [{
            "text": "Contoso Surface",
            "displayText": "Contoso",
            "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=OtterBox+Surface&FORM=IRQBPS",
            "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?q=Contoso...",
                    "searchLink": "https:\/\/api.cognitive.microsoft.com\/api...",
            "thumbnail": {
                "thumbnailUrl": "https:\/\/tse3.mm.bing.net\/th?q=Contoso+Surface..."
            }
        },
        {
            "text": "Adatum Surface",
            "displayText": "Adatum",
            "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Adatum+Surface&FORM=IRQBPS",
            "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?q=...",
            "thumbnail": {
                "thumbnailUrl": "https:\/\/tse3.mm.bing.net\/th?q=Adatum+Surface&pid=Ap..."
            }
        },
        ...
        ]
    },
    {
        "pivot": "surface",
        "suggestions": [{
            "text": "Microsoft Surface4",
            "displayText": "Surface4",
            "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Microsoft+Surface...",
            "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?...",
            "thumbnail": {
                "thumbnailUrl": "https:\/\/tse4.mm.bing.net\/th?q=Microsoft..."
            }
        },
        {
            "text": "Microsoft Tablet",
            "displayText": "Tablet",
            "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Microsoft+Tablet&FORM=IRQBPS",
            "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?...",
            "thumbnail": {
                "thumbnailUrl": "https:\/\/tse3.mm.bing.net\/th?q=Microsoft+Tablet..."
            }
        },
        ...
    ],
    "nextOffsetAddCount": 0
}

pivotSuggestions フィールドには、元のクエリを分割することによって得られたセグメント (ピボット) のリストが含まれています。The pivotSuggestions field contains the list of segments (pivots) that the original query was broken into. 応答には、ピボットごとにおすすめクエリを含んだ Query オブジェクトのリストが格納されます。For each pivot, the response contains a list of Query objects that contain suggested queries. text フィールドには、候補のクエリが含まれます。The text field contains the suggested query. displayText フィールドには、元のクエリでピボットを置換する語句が含まれます。The displayText field contains the term that replaces the pivot in the original query. "Release Date of Surface" はその一例です。An example is Release Date of Surface.

ユーザーが探しているものがピボット クエリ文字列であれば、text フィールドと thumbnail フィールドを使用し、ピボット クエリ文字列を表示します。If the pivot query string is what the user is looking for, use the text and thumbnail fields to display the pivot query strings. webSearchUrl URL または searchLink URL を利用し、サムネイルとテキストをクリック可能にします。Make the thumbnail and text clickable by using the webSearchUrl URL or the searchLink URL. webSearchUrl を使用し、Bing 検索結果にユーザーを送信します。Use webSearchUrl to send the user to the Bing search results. 独自の結果ページを提供する場合、searchLink を使用します。If you provide your own results page, use searchLink.

クエリを展開するExpand the query

Bing がクエリを展開して元の検索を絞り込むことができる場合、Images オブジェクトには queryExpansions フィールドが含まれます。If Bing can expand the query to narrow the original search, the Images object contains the queryExpansions field. たとえば、クエリが Microsoft Surface であれば、クエリは次のように展開されます。For example, if the query was Microsoft Surface, the expanded queries might be:

  • Microsoft Surface Pro 3Microsoft Surface Pro 3.
  • Microsoft Surface RTMicrosoft Surface RT.
  • Microsoft Surface PhoneMicrosoft Surface Phone.
  • Microsoft Surface HubMicrosoft Surface Hub.

次の例は、Microsoft Surface の展開されたクエリを示しています。The following example shows the expanded queries for Microsoft Surface.

{
    "_type": "Images",
    "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=microsoft%20surface...",
    "totalEstimatedMatches": 1000,
    "value": [...],
    "queryExpansions":  [{
        "text": "Microsoft Surface Pro 3",
        "displayText": "Pro 3",
        "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Microsoft+Surface+Pro+3...",
        "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?q=Microsoft...",
        "thumbnail": {
            "thumbnailUrl": "https:\/\/tse4.mm.bing.net\/th?q=Microsoft+Surface+Pro+3..."
        }
    },
    {
        "text": "Microsoft Surface RT",
        "displayText": "RT",
        "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Microsoft+Surface+RT...",
        "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?q=...",
        "thumbnail": {
            "thumbnailUrl": "https:\/\/tse4.mm.bing.net\/th?q=Microsoft+Surface+RT..."
        }
    },
    {
        "text": "Microsoft Surface Phone",
        "displayText": "Phone",
        "webSearchUrl": "https:\/\/www.bing.com\/images\/search?q=Microsoft+Surface+Phone",
        "searchLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/images\/search?q=...",
        "thumbnail": {
            "thumbnailUrl": "https:\/\/tse4.mm.bing.net\/th?q=Microsoft+Surface+Phone..."
        }
    }],
    "pivotSuggestions": [...],
    "nextOffsetAddCount": 0
}

queryExpansions フィールドには、Query オブジェクトのリストが含まれています。The queryExpansions field contains a list of Query objects. text フィールドには、展開されたクエリが含まれています。The text field contains the expanded query. displayText フィールドには、展開語句が含まれています。The displayText field contains the expansion term. ユーザーが探しているものが展開されたクエリ文字列であれば、text フィールドと thumbnail フィールドを使用し、展開されたクエリ文字列を表示します。If the expanded query string is what the user is looking for, use the text and thumbnail fields to display the expanded query strings. webSearchUrl URL または searchLink URL を利用し、サムネイルとテキストをクリック可能にします。Make the thumbnail and text clickable by using the webSearchUrl URL or the searchLink URL. webSearchUrl を使用し、Bing 検索結果にユーザーを送信します。Use webSearchUrl to send the user to the Bing search results. 独自の結果ページを提供する場合、searchLink を使用します。if you provide your own results page, use searchLink.

スロットル リクエスト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

まだ Bing Image Search API を試していない方は、クイック スタートをご覧ください。If you haven't tried the Bing Image Search API before, try a quickstart. さらに高度な内容をお求めの方は、単一ページの Web アプリの作成に関するチュートリアルをご覧ください。If you're looking for something more complex, try the tutorial to create a single-page web app.