Referencia de la API REST de Web Search

Punto final:POST https://api.microsoft.ai/v3/search/web

Solicitud de ejemplo:

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

Parámetro Required Tipo Default Description
consulta Sí string - Cadena de consulta de búsqueda. La longitud máxima es de 1000 caracteres. Admite operadores "site:" y "-site:" para incluir o excluir resultados de sitios específicos (por ejemplo, "consulta site:example.com"). Use estos operadores solo cuando sea necesario, ya que reducen inherentemente la relevancia del resultado.
maxResults No integer 10 Número máximo de resultados que se van a devolver. El valor predeterminado es 10 y el valor máximo es 50.
idioma No string "en" Código de idioma ISO 639-1 de 2 letras para el idioma de la interfaz en los resultados de la búsqueda. Consulte Idiomas admitidos para obtener la lista completa.
region No string "US" Código de país o región de 2 letras para el que deben proceder los resultados (por ejemplo, "US", "JP", "GB", etc.). Consulte Regiones admitidas para obtener la lista completa.
location No string - Información de ubicación con el formato "lat:<float>; long:<float>", por ejemplo, "lat:40.753250; long:-74.003807". Si no se especifica, se deduciría la ubicación de la consulta.
contentFormat No string "passage" ("html" con acceso completo al documento) passage devuelve las partes de cada resultado más relevantes para la consulta (recomendado para la puesta a tierra). texty htmlmarkdown devuelven el documento completo y solo se aplican a las aplicaciones con acceso completo a documentos; vea Pasajes y formatos de contenido. Establézcalo en cada solicitud. Nota: la API web no devuelve un snippet campo.
longitud máxima No integer 3000 (10000 con acceso completo a documentos) Número máximo de caracteres por content resultado, de 1 a 500000. Sin acceso completo a documentos, content tiene como máximo 3000 caracteres. Consulte Valores predeterminados y límites. Establézcalo en cada solicitud.
safeSearch No string "strict" Nivel de filtrado de búsqueda segura. Valores: "off", "strict". El valor predeterminado es "strict".

Formatos de contenido

Establézcalo contentFormatpassage = para obtener las partes de cada resultado más relevantes para la consulta, hasta maxLength caracteres (3000 es un buen punto de partida). Es el formato recomendado para la puesta a tierra; consulte ¿Qué es passagey por qué usarlo? en las preguntas más frecuentes. Las aplicaciones con acceso completo a documentos también pueden solicitar el documento completo como text, html o markdown; para otras aplicaciones, esos formatos devuelven HTTP 403. Consulte Pasajes y formatos de contenido.

Búsqueda segura

Los modos SafeSearch permiten controlar la cantidad de contenido web confidencial que filtra la API web antes de que se devuelvan los resultados. El contenido confidencial incluye violencia, autolesión y otras categorías. El valor predeterminado es strict.

Value Description Recomendado para
strict Bloquea el contenido relacionado con temas para adultos, subido de tono, violencia, odio y autolesión. Implementaciones seguras para niños, educación, consumidor/conservador.
off Sigue bloqueando el contenido no válido. Para otro contenido potencialmente perjudicial, cambia la responsabilidad del filtrado final al usuario. Investigación, análisis, participación empresarial, casos de uso avanzados de 3P.

Note

Si usa el site: operador de consulta, la respuesta puede contener contenido para adultos independientemente del safeSearch valor. Use site: solo si conoce el contenido del sitio y su escenario admite la posibilidad de contenido para adultos.

Encabezados de solicitud

Field Tipo Description
host string Host para las API de IA de Microsoft: api.microsoft.ai.
x-apikey o Authorization string La clave de API o Entra ID token de acceso para la autenticación.
content-type (tipo de contenido) string Tipo MIME del cuerpo de la solicitud. Utilice application/json.

Respuesta

Respuesta web

Field Tipo Description
webResults matriz de webResult Lista de resultados de la página web.
querySignals querySignals Señales de clasificación de nivel de consulta para la consulta de búsqueda.
riskLevel string Nivel de riesgo de seguridad evaluado para la consulta. Valores posibles: low, moderate, high, veryHigh.
instrumentationClickBase string Dirección URL base para hacer clic en solicitudes de ping. Anexe un instrumentationSuffix valor de un elemento de resultado para formar la dirección URL de ping completa. Solo está presente para las aplicaciones con la marca de perfil EnableInstrumentationPing. Nota: Los clics de usuario también se pueden registrar mediante el redireccionamiento de direcciones URL. Cuando la redirección está habilitada, no se requiere ninguna acción para registrar los clics del usuario y instrumentationClickBase no se incluirá en la respuesta. Consulte la guía de instrumentación para obtener instrucciones de configuración.
instrumentationCitationBase string Dirección URL base para las solicitudes de ping de registro de LLM. Anexe una carga DE DATOS para formar la dirección URL de ping completa. Solo está presente para las aplicaciones con la marca de perfil EnableInstrumentationPing.
traceId string Identificador de seguimiento para la depuración.

querySignals

Field Tipo Description
freshness booleano Indica si se deben priorizar los documentos nuevos sobre otros documentos para esta consulta.

webResult

Field Tipo Description
title string El título de la página web.
url string Dirección URL de origen de la página web. Para los usuarios de China con redirección de direcciones URL habilitadas, este campo contiene la misma dirección URL de redireccionamiento que clickUrl.
domain string Host de destino para el resultado. Solo se devuelve para los usuarios de China con el redireccionamiento de direcciones URL habilitado.
contenido string El contenido detallado (también conocido como base) de la página web.
crawledAt string La última fecha rastreada de la página web sigue ISO8601 formato.
lastUpdatedAt string La última fecha actualizada de la página web sigue ISO8601 formato.
idioma string El idioma de la página web usa el código de idioma ISO 639-1.
isAdult booleano Indica si el resultado incluye contenido para adultos.
clickUrl string Url de redirección que proxie el clic a través de Bing. Solo está presente cuando el redireccionamiento de clics está habilitado.
instrumentationSuffix string Sufijo que se va a anexar a la base de dirección URL de ping de instrumentación para este elemento de resultado. Se usa como valor K para la dirección URL de ping de instrumentación y el clickUrl redireccionamiento. Presente cuando el ping de instrumentación está habilitado.
contentTier string Nivel de contenido del resultado, que describe las características de acceso comercial del origen de contenido. Valores posibles: standard (contenido estándar disponible para todos los clientes en la oferta de servicio predeterminada), entitled (contenido disponible a través de los contratos de licencias de clientes existentes, incluido el contenido traiga su propia licencia (BYOL) que los clientes han autorizado directamente desde editores y acceso a través de sus propios acuerdos contractuales), premium (contenido premium que proporciona valor adicional más allá de la oferta estándar y está sujeto a facturación).

Note

Los valores de crawledAt y lastUpdatedAt los campos son opcionales. Es decir, su cobertura no es 100%. Es posible que vea valores vacíos para estos campos.

Códigos de error

Código de estado Categoría de error Description Causas comunes
200 Success La solicitud tuvo éxito. -
400 Solicitud incorrecta Parámetros de solicitud no válidos. Faltan campos obligatorios, valores de parámetro no válidos, JSON con formato incorrecto
401 Unauthorized Error de autenticación o falta. Clave de API no válida, falta el encabezado x-apikey
403 Prohibida Credenciales válidas pero permisos insuficientes. La clave de API carece de permisos necesarios
410 Pasado (Gone) SE requiere HTTPS. Solicitud realizada a través de HTTP en lugar de HTTPS
415 Tipo de medio no admitido No se admite el tipo de contenido. Falta o falta un encabezado de tipo de contenido incorrecto
429 Demasiadas solicitudes Se superó el límite de velocidad. Demasiadas solicitudes en el período de tiempo
500 Error interno del servidor Error inesperado del servidor. Problema de servidor temporal
503 Servicio no disponible El servicio no está disponible temporalmente. Interrupción temporal o mantenimiento
504 Tiempo de espera de puerta de enlace Se ha agotado el tiempo de espera para la solicitud. Tiempo de espera del servicio ascendente

Para obtener instrucciones detalladas sobre el control de errores, consulte Control de errores.

Vea también:Videos Search Browse | | News Search | Images Search | MCP

  • Se actualizó por última vez el