Informations de référence sur l’API REST recherche web

Point de terminaison :POST https://api.microsoft.ai/v3/search/web

Exemple de demande :

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

Paramètre Required Type Default Description
query Yes string - Chaîne de requête de recherche. La longueur maximale est de 1 000 caractères. Prend en charge les opérateurs « site : » et « -site : » pour inclure ou exclure les résultats de sites spécifiques (par exemple, « interroger site:example.com »). Utilisez ces opérateurs uniquement si nécessaire, car ils réduisent intrinsèquement la pertinence des résultats.
maxResults Non integer 10 Nombre maximal de résultats à renvoyer. La valeur par défaut est 10 et la valeur maximale est 50.
langue Non string « en » Code de langue ISO 639-1 de 2 lettres pour la langue de l’interface dans les résultats de recherche. Consultez les langues prises en charge pour obtenir la liste complète.
region Non string "US" Code pays/région de 2 lettres pour lequel les résultats doivent provenir (par exemple, « US », « JP », « GB », etc.). Consultez les régions prises en charge pour obtenir la liste complète.
location Non string - Informations d’emplacement au format « lat :<float> ; long :<float> », par exemple « lat :40.753250 ; long :-74.003807". S’il n’est pas spécifié, l’emplacement de la requête est déduit.
contentFormat Non string « passage » (« html » avec accès complet aux documents) passage retourne les parties de chaque résultat le plus pertinent pour la requête (recommandé pour la mise au point). text, html et renvoyer le document complet et markdown s’appliquer uniquement aux applications disposant d’un accès complet aux documents ; consultez Passages et formats de contenu. Définissez-le sur chaque requête. Remarque : l’API web ne retourne pas de snippet champ.
longueur maximale Non integer 3000 (10000 avec accès complet aux documents) Nombre maximal de caractères par content résultat, 1 à 5 0000. Sans accès complet aux documents, content il y a au maximum 3 000 caractères. Consultez les valeurs par défaut et les limites. Définissez-le sur chaque requête.
safeSearch Non string « strict » Niveau de filtrage de recherche sécurisé. Valeurs : « off », « strict ». La valeur par défaut est « strict ».

Formats de contenu

Définissez contentFormat = passage pour obtenir les parties de chaque résultat le plus pertinent pour la requête, jusqu’à maxLength caractères (3000 est un bon point de départ). Il s’agit du format recommandé pour la mise à l’terre ; voir Qu’est-ce que c’est passageet pourquoi l’utiliser ? dans le FAQ. Les applications disposant d’un accès complet au document peuvent également demander le document complet en tant que text, html ou markdown; pour d’autres applications, ces formats retournent HTTP 403. Consultez passages et formats de contenu.

Filtre adulte

Les modes SafeSearch vous permettent de contrôler la quantité de contenu web sensible que l’API web filtre avant que les résultats ne soient retournés. Le contenu sensible comprend la violence, l’auto-préjudice et d’autres catégories. La valeur par défaut est strict.

Value Description Recommandé pour
strict Bloque le contenu lié aux sujets adultes, racés, violence, haine et auto-nuisibles. Déploiements enfants-safe, éducation, consommateur/conservateur.
off Bloque toujours le contenu illégal. Pour d’autres contenus potentiellement dangereux, déplace la responsabilité du filtrage final vers l’utilisateur. Recherche, analyse, opt-in enterprise, cas d’usage avancés 3P.

Note

Si vous utilisez l’opérateur site: de requête, la réponse peut contenir du contenu adulte, quelle que soit la safeSearch valeur. Utilisez site: uniquement si vous connaissez le contenu sur le site et que votre scénario prend en charge la possibilité de contenu pour adultes.

En-têtes de requête

Champ Type Description
host string Hôte pour Microsoft API IA : api.microsoft.ai.
x-apikey ou autorisation string Votre clé API ou votre jeton d’accès Entra ID pour l’authentification.
type de contenu string Type MIME du corps de la requête. Utilisez application/json.

Response

Réponse web

Champ Type Description
webResults tableau de webResult Liste des résultats de la page web.
querySignals querySignals Signaux de classement au niveau de la requête pour la requête de recherche.
riskLevel string Niveau de risque de sécurité évalué pour la requête. Valeurs possibles : low, moderate, high, veryHigh.
instrumentationClickBase string URL de base pour cliquer sur les requêtes ping. Ajoutez une instrumentationSuffix valeur à partir d’un élément de résultat pour former l’URL ping complète. Présente uniquement pour les applications avec l’indicateur de profil EnableInstrumentationPing. Remarque : les clics utilisateur peuvent également être enregistrés à l’aide de la redirection d’URL. Lorsque la redirection est activée, aucune action n’est nécessaire pour journaliser les clics utilisateur et instrumentationClickBase ne sera pas incluse dans la réponse. Consultez le guide d’instrumentation pour obtenir des instructions de configuration.
instrumentationCitationBase string URL de base pour les requêtes ping du journal LLM. Ajoutez une charge utile DATA pour former l’URL ping complète. Présente uniquement pour les applications avec l’indicateur de profil EnableInstrumentationPing.
traceId string ID de trace pour le débogage.

querySignals

Champ Type Description
freshness boolean Indique si les nouveaux documents doivent être hiérarchisés par rapport à d’autres documents pour cette requête.

webResult

Champ Type Description
title string Titre de la page web.
url string URL source de la page web. Pour les utilisateurs chinois avec la redirection d’URL activée, ce champ contient plutôt la même URL de redirection que clickUrl.
domain string Hôte de destination pour le résultat. Retourné uniquement pour les utilisateurs chinois avec redirection d’URL activée.
contenu string Contenu détaillé (par exemple, base) de la page web.
crawledAt string La dernière date analysée de la page web suit ISO8601 format.
lastUpdatedAt string La dernière date de mise à jour de la page web suit ISO8601 format.
langue string La langue de la page web utilise le code de langue ISO 639-1.
isAdult boolean Indique si le résultat inclut du contenu pour adultes.
clickUrl string URL de redirection qui proxie le clic via Bing. Présente uniquement lorsque la redirection en un clic est activée.
instrumentationSuffix string Suffixe à ajouter à la base d’URL ping d’instrumentation pour cet élément de résultat. Utilisé comme valeur K pour l’URL ping d’instrumentation et la clickUrl redirection. Présent lorsque le test ping d’instrumentation est activé.
contentTier string Niveau de contenu du résultat, décrivant les caractéristiques d’accès commercial de la source de contenu. Valeurs possibles : standard (contenu standard disponible pour tous les clients sous l’offre de service par défaut), entitled (contenu disponible via des contrats de licence client existants, y compris le contenu BYOL (Bring Your Own License) que les clients ont concédé directement sous licence à partir d’éditeurs et accès via leurs propres arrangements contractuels), premium (contenu premium qui fournit une valeur supplémentaire au-delà de l’offre standard et est soumis à la facturation).

Note

Les valeurs et crawledAtlastUpdatedAt champs sont facultatives. Autrement dit, leur couverture n’est pas 100%. Vous pouvez voir des valeurs vides pour ces champs.

Codes d’erreur

Code de statut Catégorie d’erreur Description Causes courantes
200 Success La demande a abouti. -
400 Demande incorrecte Paramètres de requête non valides. Champs obligatoires manquants, valeurs de paramètre non valides, JSON mal formé
401 Unauthorized Échec ou absence de l’authentification. Clé API non valide, en-tête x-apikey manquant
403 Interdit Informations d’identification valides, mais autorisations insuffisantes. La clé API ne dispose pas des autorisations requises
410 Non disponible (Gone) HTTPS requis. Requête effectuée sur HTTP au lieu de HTTPS
415 Type de média non pris en charge Type de contenu non pris en charge. En-tête de type de contenu manquant ou incorrect
429 Trop de demandes Limite de débit dépassée. Trop de requêtes dans la fenêtre de temps
500 Erreur interne du serveur Erreur de serveur inattendue. Problème de serveur temporaire
503 Service indisponible Service temporairement indisponible. Pannes de maintenance ou temporaires
504 Délai d’expiration de la passerelle La requête a expiré. Délai d’expiration du service en amont

Pour obtenir des instructions détaillées sur la gestion des erreurs, consultez Gestion des erreurs.

Voir aussi :Recherche de vidéos Parcourir les | imagesde recherche d’actualités Recherche | | d’images MCP |

  • Dernière mise à jour :