Справочник по REST API поиска в Интернете

Конечная точка:POST https://api.microsoft.ai/v3/search/web

Пример запроса:

curl -X POST "https://api.microsoft.ai/v3/search/web" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "latest trends in LLM RAG",
    "maxResults": 10,
    "language": "en",
    "region": "US",
    "maxLength": 3000,
    "contentFormat": "passage"
  }'

Parameters

Parameter Required Type Default Description
query Yes string - Строка запроса поиска. Максимальная длина — 1000 символов. Поддерживает операторы "site:" и "-site:" для включения или исключения результатов из определенных сайтов (например, "запрос site:example.com"). Используйте эти операторы только при необходимости, так как они по сути снижают релевантность результатов.
максимальноеКоличествоРезультатов No integer 10 Максимальное количество возвращаемых результатов. Значение по умолчанию равно 10, а максимальное — 50.
language No string "en" 2-буквенный код ЯЗЫКА ISO 639-1 для языка интерфейса в результатах поиска. Полный список см. на поддерживаемых языках .
region No string "US" 2-буквенный код страны или региона, из которого должны поступать результаты (например, "US", "JP", "GB", и т. д.). Полный список см. в поддерживаемых регионах .
location No string - Сведения о расположении в формате "lat:<float>; long:float>, например "lat:<40.753250; long:-74.003807". Если это не указано, расположение в запросе будет выводиться.
contentFormat No string "проход" ("html" с полным доступом к документам) passage возвращает части каждого результата, наиболее релевантного к запросу (рекомендуется для приземления). textи html возвращает полный документ и markdown применяется только к приложениям с полным доступом к документам; см. раздел "Проходы и форматы содержимого". Задайте его для каждого запроса. Примечание. Веб-API не возвращает snippet поле.
максимальная длина No integer 3000 (10000 с полным доступом к документам) Максимальное число символов в content результатах — от 1 до 500000. Без полного доступа к документам не content более 3000 символов. См. значения по умолчанию и ограничения. Задайте его для каждого запроса.
safeSearch No string "строгий" Уровень безопасной фильтрации поиска. Значения: "off", "strict". Значение по умолчанию — "строго".

Форматы содержимого

Задайте contentFormat = passage для получения частей каждого результата, наиболее релевантного к запросу, до maxLength символов (3000 — это хорошая отправная точка). Рекомендуемый формат для приземления; См . раздел "Что такое passage" и почему он используется? В разделе часто задаваемых вопросов. Приложения с полным доступом к документам также могут запрашивать полный документ как texthtml или markdownдля других приложений, эти форматы возвращают HTTP 403. См. фрагменты и форматы содержимого.

Безопасный поиск

Режимы SafeSearch позволяют контролировать, сколько конфиденциального веб-содержимого веб-API фильтрует перед возвратом результатов. Конфиденциальное содержимое включает насилие, самоповредение и другие категории. Значение по умолчанию — strict.

Value Description Рекомендуется для
strict Блокирует содержимое, связанное с взрослыми, расхищением, насилием, ненавистью и самовредящими темами. Дочерние, образовательные, потребительские и консервативные развертывания.
off По-прежнему блокирует незаконное содержимое. Для другого потенциально вредного содержимого переместит ответственность за окончательную фильтрацию пользователю. Исследования, анализ, выбор предприятия, расширенные варианты использования 3P.

Note

При использовании оператора запроса ответ может содержать содержимое site: для взрослых независимо от safeSearch значения. Используйте site: только в том случае, если вы знаете содержимое на сайте и ваш сценарий поддерживает возможность содержимого для взрослых.

Заголовки запроса

Field Type Description
host string Узел для API Microsoft ИИ: api.microsoft.ai
x-apikey или authorization string Ключ API или маркер доступа Entra ID для проверки подлинности.
тип контента string Тип MIME текста запроса. Используйте application/json.

Response

Веб-ответ

Field Type Description
webResults массив webResult Список результатов веб-страницы.
querySignals querySignals Сигналы ранжирования на уровне запроса.
riskLevel string Уровень риска безопасности, оцененный для запроса. Возможные значения: low, , moderatehighveryHigh.
инструментированиеClickBase string Базовый URL-адрес для запросов на связь. instrumentationSuffix Добавьте значение из элемента результата, чтобы сформировать полный URL-адрес связи. Только для приложений с флагом профиля EnableInstrumentationPing. Примечание. Щелчки пользователей также могут быть зарегистрированы с помощью перенаправления URL-адресов. Если перенаправление включено, действие не требуется для регистрации щелчков пользователей и instrumentationClickBase не будет включено в ответ. Инструкции по настройке см. в руководстве по инструментированию .
инструментированиеCitationBase string Базовый URL-адрес для запросов ping журнала LLM. Добавьте полезные данные DATA, чтобы сформировать полный URL-адрес ping. Только для приложений с флагом профиля EnableInstrumentationPing.
traceId string Идентификатор трассировки для отладки.

querySignals

Field Type Description
freshness boolean Указывает, должны ли новые документы быть приоритетными по сравнению с другими документами для этого запроса.

webResult

Field Type Description
title string Заголовок веб-страницы.
url string Исходный URL-адрес веб-страницы. Для пользователей Китая с включенным перенаправлением URL-адресов это поле содержит тот же URL-адрес перенаправления, что clickUrlи .
domain string Узел назначения для результата. Возвращается только для пользователей Китая с включенным перенаправлением URL-адресов.
содержимое string Подробное содержимое (ака заземление) веб-страницы.
обход контента string Последняя дата обхода веб-страницы следует ISO8601 формате.
lastUpdatedAt string Последняя обновленная дата веб-страницы следует ISO8601 формате.
language string Язык веб-страницы использует код языка ISO 639-1.
isAdult boolean Указывает, включает ли результат содержимое для взрослых.
clickUrl string URL-адрес перенаправления, который прокси-сервер щелкает Bing. Присутствует только при включении перенаправления щелчка.
инструментированиеSuffix string Суффикс для добавления к базе URL-адреса проверки связи инструментирования для этого элемента результата. Используется как значение K для URL-адреса проверки ping инструментирования, так и перенаправления clickUrl . Присутствует при включении проверки пинга инструментирования.
contentTier string Уровень содержимого результата, описывающий характеристики коммерческого доступа источника контента. Возможные значения: standard (стандартное содержимое, доступное всем клиентам в рамках предложения услуг по умолчанию), entitled (содержимое, доступное с помощью существующих соглашений о лицензировании клиентов, включая содержимое byOL ), которое клиенты лицензировали непосредственно от издателей и доступа через собственные договорные соглашения), (содержимое класса Premium, premium которое обеспечивает дополнительную ценность за пределами стандартного предложения и подлежит выставлению счетов).

Note

crawledAt Значения и lastUpdatedAt поля являются необязательными. То есть их охват не составляет 100%. Для этих полей могут отображаться пустые значения.

Коды ошибок

Код состояния Категория ошибки Description Распространенные причины
200 Success Запрос был выполнен успешно. -
400 ошибка запроса Недопустимые параметры запроса. Отсутствующие обязательные поля, недопустимые значения параметров, некорректный JSON
401 Unauthorized Сбой проверки подлинности или отсутствие. Недопустимый ключ API, отсутствующий заголовок x-apikey
403 Forbidden Допустимые учетные данные, но недостаточно разрешений. Ключ API не имеет необходимых разрешений
410 Отсутствует (Gone) Требуется ПРОТОКОЛ HTTPS. Запрос, сделанный по протоколу HTTP вместо HTTPS
415 Неподдерживаемый тип носителя Тип контента не поддерживается. Отсутствует или неправильный заголовок типа контента
429 Слишком много запросов Превышено ограничение скорости. Слишком много запросов в период времени
500 Внутренняя ошибка сервера Непредвиденная ошибка сервера. Проблема с временным сервером
503 Служба недоступна Служба временно недоступна. Обслуживание или временный сбой
504 Тайм-аут шлюза Истекло время ожидания для запроса. Время ожидания вышестоящей службы

Подробные инструкции по обработке ошибок см. в разделе "Обработка ошибок".

См. также:Поиск видео | обзоры | изображенийпоиска | | новостейв MCP

  • Последнее обновление: