Настройка и предложение запросов поиска изображений

Предупреждение

30 октября 2020 года API Поиска Bing переместились из Cognitive Services в службы Поиска Bing. Эта документация приводится только для справки. Обновленную информацию см. в документации по API Поиска Bing. Инструкции по созданию ресурсов Azure для Поиска MS Bing см. в статье о том, как создать ресурс для Поиска MS Bing с помощью Azure Marketplace.

Используйте эту статью, чтобы узнать, как настроить запросы и предложить условия поиска для отправки в API Bing для поиска изображений.

Автозаполнение поисковых запросов

Если в приложении предусмотрено поле для ввода условий поиска, то для упрощения работы можно использовать API автозаполнения Bing. Этот API может отображать предлагаемые поисковые запросы в режиме реального времени. API возвращает предложенные строки запроса на основе частичных условий поиска и службы Cognitive Services.

Сведение запросов

Если Bing может сегментировать исходный поисковый запрос, возвращаемый объект Images содержит поле pivotSuggestions. Сводка предложений может отображаться в виде необязательных поисковых запросов для пользователя. Например, если исходный запрос был Microsoft Surface, Bing может разделить запрос на Microsoft и Surface и предложить сведения для каждого из них. Эти предложения могут отображаться в виде необязательных поисковых запросов для пользователя.

В следующем примере показаны сводные предложения для 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 содержит список сегментов (сводок), на которые был разбит исходный запрос. Для каждой сводки ответ содержит список объектов Query, содержащих предлагаемые запросы. Поле text содержит предложенные поисковые запросы. Поле displayText содержит условие, заменяющее сводку в исходном запросе. Например, дата выпуска Surface.

Если строка сводного запроса является тем, что ищет пользователь, используйте поля text и thumbnail для отображения этих строк. Создайте эскиз и текст с помощью URL-адреса webSearchUrl или searchLink. Используйте поле webSearchUrl для отправки пользователю результаты поиска Bing. Если вы предоставляете собственную страницу результатов, используйте поле searchLink.

Расширение запроса

Если Bing может расширить запрос, чтобы сузить исходный поисковый запрос, объект Images будет содержать поле queryExpansions. Например, если запрос был Microsoft Surface, расширенные запросы могут иметь вид:

  • Microsoft Surface Pro 3.
  • Microsoft Surface RT.
  • Microsoft Surface Phone.
  • Microsoft Surface Hub.

В следующем примере показаны расширенные запросы для 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. Поле text содержит расширенный поисковый запрос. Поле displayText содержит термин, который расширяет запрос. Если строка расширенного запроса является тем, что ищет пользователь, используйте поля text и thumbnail для отображения этих строк. Создайте эскиз и текст с помощью URL-адреса webSearchUrl или searchLink. Используйте поле webSearchUrl для отправки пользователю результаты поиска Bing. Если вы предоставляете собственную страницу результатов, используйте поле searchLink.

Запросы на регулирование

Служба и тип подписки определяют число запросов, которые можно выполнить за секунду (QPS). Убедитесь, что приложение содержит логику, необходимую, чтобы оставаться в пределах вашей квоты. Если лимит частоты запросов достигнут или превышен, запрос возвращает ошибку с кодом состояния HTTP 429. Ответ включает заголовок Retry-After, который указывает, сколько необходимо ждать перед отправкой другого запроса.

Отказ в обслуживании и регулирование

Служба различает атаку типа "отказ в обслуживании" (DoS) и нарушение QPS. Если служба подозревает атаку типа "отказ в обслуживании", запрос возвращает код успешного выполнения (код состояния HTTP 200 OK). Однако тело ответа пустое.

Дальнейшие действия

Если вы еще ни разу не использовали API Bing для поиска изображений, ознакомьтесь со следующей статьей. Если вы ищете что-нибудь посложнее, ознакомьтесь с руководством по созданию одностраничного веб-приложения.