Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Endpoint:POST https://api.microsoft.ai/v3/search/web
Richiesta di esempio:
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
| Parametro | Required | Type | Default | Description |
|---|---|---|---|---|
| query | Yes | string | - | Stringa di query di ricerca. La lunghezza massima è di 1000 caratteri. Supporta gli operatori "site:" e "-site:" per includere o escludere i risultati da siti specifici ,ad esempio "query site:example.com"). Usare questi operatori solo quando necessario, in quanto riducono intrinsecamente la pertinenza dei risultati. |
| maxResults | No | integer | 10 | Numero massimo di risultati da restituire. Il valore predefinito è 10 e il valore massimo è 50. |
| language | No | string | "en" | Codice di lingua ISO 639-1 di 2 lettere per la lingua dell'interfaccia nei risultati della ricerca. Per l'elenco completo, vedere Lingue supportate . |
| region | No | string | "US" | Codice paese/area geografica a 2 lettere da cui devono provenire i risultati (ad esempio "US", "JP", "GB" e così via). Per l'elenco completo, vedere Aree supportate . |
| ubicazione | No | string | - | Informazioni sulla posizione nel formato "lat:<float>; long:<float>", ad esempio "lat:40.753250; long:-74.003807". Se non specificato, verrà dedotto il percorso nella query. |
| contentFormat | No | string | "passaggio" ("html" con accesso completo al documento) |
passage restituisce le parti di ogni risultato più rilevante per la query (consigliata per il grounding).
texte htmlmarkdown restituiscono il documento completo e si applicano solo alle applicazioni con accesso completo al documento. Vedere Passaggi e formati di contenuto. Impostarlo su ogni richiesta. Nota: l'API Web non restituisce un snippet campo. |
| lunghezza massima | No | integer | 3000 (10000 con accesso completo al documento) | Numero massimo di caratteri per content risultato, da 1 a 500000. Senza accesso completo ai documenti, content è al massimo 3000 caratteri. Vedere Impostazioni predefinite e limiti. Impostarlo su ogni richiesta. |
| safeSearch | No | string | "strict" | Livello di filtro di ricerca sicuro. Valori: "off", "strict". Il valore predefinito è "strict". |
Formati di contenuto
Impostare contentFormat = passage per ottenere le parti di ogni risultato più rilevante per la query, fino a maxLength caratteri (3000 è un buon punto di partenza). È il formato consigliato per il grounding; vedere Che cos'è passagee perché usarlo? nelle domande frequenti. Le applicazioni con accesso completo ai documenti possono anche richiedere il documento completo come texto htmlmarkdown. per altre applicazioni, tali formati restituiscono HTTP 403. Vedi Passaggi e formati di contenuto.
Ricerca sicura
Le modalità SafeSearch consentono di controllare quanto contenuto Web sensibile filtra l'API Web prima che vengano restituiti i risultati. I contenuti sensibili includono violenza, autolesionismo e altre categorie. Il valore predefinito è strict.
| Value | Description | Consigliato per |
|---|---|---|
strict |
Blocca il contenuto correlato ad argomenti relativi a adulti, spinti, violenza, odio e autolesionismo. | Distribuzione sicura per bambini, istruzione, consumer/conservativa. |
off |
Blocca comunque il contenuto illegale. Per altri contenuti potenzialmente dannosi, sposta la responsabilità del filtro finale all'utente. | Ricerca, analisi, consenso esplicito aziendale, casi d'uso avanzati 3P. |
Note
Se si usa l'operatore site: di query, la risposta può contenere contenuto per adulti indipendentemente dal safeSearch valore . Usare site: solo se si è a conoscenza del contenuto nel sito e lo scenario supporta la possibilità di contenuto per adulti.
Intestazioni della richiesta
| Field | Type | Description |
|---|---|---|
| host | string | Host per le API di intelligenza artificiale Microsoft: api.microsoft.ai. |
| x-apikey o autorizzazione | string | La chiave API o Entra ID token di accesso per l'autenticazione. |
| tipo di contenuto | string | Tipo MIME del corpo della richiesta. Utilizzare il application/json. |
Risposta
Risposta Web
| Field | Type | Description |
|---|---|---|
| webResults | matrice di webResult | Elenco dei risultati della pagina Web. |
| querySignals | querySignals | Segnali di classificazione a livello di query per la query di ricerca. |
| riskLevel | string | Livello di rischio di sicurezza valutato per la query. Valori possibili: low, moderate, high, veryHigh. |
| instrumentationClickBase | string | URL di base per fare clic su richieste ping. Aggiungere un instrumentationSuffix valore da un elemento del risultato per formare l'URL ping completo. Presente solo per le applicazioni con il flag del profilo EnableInstrumentationPing. Nota: è anche possibile registrare i clic degli utenti usando il reindirizzamento URL. Quando il reindirizzamento è abilitato, non è necessaria alcuna azione per registrare i clic dell'utente e instrumentationClickBase non verrà inclusa nella risposta. Per istruzioni sull'installazione, vedere la guida alla strumentazione . |
| instrumentationCitationBase | string | URL di base per le richieste ping del log LLM. Aggiungere un payload DATA per formare l'URL ping completo. Presente solo per le applicazioni con il flag del profilo EnableInstrumentationPing. |
| traceId | string | ID traccia per il debug. |
querySignals
| Field | Type | Description |
|---|---|---|
| freshness | boolean | Indica se i documenti aggiornati devono essere classificati in ordine di priorità rispetto ad altri documenti per questa query. |
webResult
| Field | Type | Description |
|---|---|---|
| title | string | Titolo della pagina Web. |
| url | string | URL di origine della pagina Web. Per gli utenti della Cina con reindirizzamento URL abilitato, questo campo contiene invece lo stesso URL di reindirizzamento di clickUrl. |
| domain | string | Host di destinazione per il risultato. Restituito solo per gli utenti della Cina con reindirizzamento URL abilitato. |
| contenuto | string | Il contenuto dettagliato (noto anche come terra) della pagina Web. |
| ricerca per indicizzazioneAt | string | L'ultima data sottoposta a ricerca per indicizzazione della pagina Web segue ISO8601 formato. |
| ultimoAggiornatoAt | string | La data dell'ultimo aggiornamento della pagina Web segue ISO8601 formato. |
| language | string | La lingua della pagina Web usa il codice linguistico ISO 639-1. |
| isAdult | boolean | Indica se il risultato include contenuto per adulti. |
| clickUrl | string | URL di reindirizzamento che esegue il proxy del clic tramite Bing. Presente solo quando il clic di reindirizzamento è abilitato. |
| instrumentationSuffix | string | Suffisso da aggiungere alla base dell'URL ping di strumentazione per questo elemento del risultato. Usato come valore K sia per l'URL ping di strumentazione che per il clickUrl reindirizzamento. Presente quando è abilitato il ping di strumentazione. |
| contentTier | string | Livello di contenuto del risultato, che descrive le caratteristiche di accesso commerciale dell'origine contenuto. Valori possibili: standard (contenuto standard disponibile per tutti i clienti nell'offerta di servizio predefinita), entitled (contenuto disponibile tramite contratti di licenza dei clienti esistenti, incluso il contenuto BYOL (Bring Your Own License) concesso in licenza direttamente dagli editori e l'accesso tramite le proprie disposizioni contrattuali), premium (contenuto Premium che fornisce valore aggiuntivo oltre l'offerta standard ed è soggetto alla fatturazione). |
Note
I valori dei crawledAt campi e lastUpdatedAt sono facoltativi. Ovvero, la copertura non è 100%. È possibile che vengano visualizzati valori vuoti per questi campi.
Codici di errore
| Codice di stato | Categoria errore | Description | Cause comuni |
|---|---|---|---|
| 200 | Operazione completata | La richiesta è stata accolta. | - |
| 400 | Richiesta non valida | Parametri di richiesta non validi. | Campi obbligatori mancanti, valori di parametro non validi, JSON in formato non valido |
| 401 | Unauthorized | Autenticazione non riuscita o mancante. | Chiave API non valida, intestazione x-apikey mancante |
| 403 | Non consentito | Credenziali valide ma autorizzazioni insufficienti. | La chiave API non dispone delle autorizzazioni necessarie |
| 410 | Sparito | HTTPS obbligatorio. | Richiesta effettuata tramite HTTP invece di HTTPS |
| 415 | Tipo di supporto non supportato | Tipo di contenuto non supportato. | Intestazione di tipo contenuto mancante o non corretta |
| 429 | Troppe richieste | Limite di velocità superato. | Troppe richieste nell'intervallo di tempo |
| 500 | Errore interno del server | Errore server imprevisto. | Problema temporaneo del server |
| 503 | Servizio non disponibile | Servizio temporaneamente non disponibile. | Manutenzione o interruzione temporanea |
| 504 | Timeout gateway | Tempo di attesa della richiesta scaduto. | Timeout del servizio Upstream |
Per indicazioni dettagliate sulla gestione degli errori, vedere Gestione degli errori.
Vedere anche:Ricerca video | Sfoglia | immaginiricerca | notizie Ricerca | MCP