Web Search REST API-referencia

Végpont:POST https://api.microsoft.ai/v3/search/web

Mintakérés:

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éter Required Típus Default Description
lekérdezés Yes karakterlánc - Keresési lekérdezési sztring. A maximális hossz 1000 karakter. Támogatja a "site:" és a "-site:" operátorokat az adott webhelyek eredményeinek belefoglalásához vagy kizárásához (pl. "lekérdezési site:example.com"). Ezeket az operátorokat csak akkor használja, ha szükséges, mivel eleve csökkentik az eredmény relevanciáját.
maxResults No egész szám 10 A visszaadandó eredmények maximális száma. Az alapértelmezett érték 10, a maximális érték pedig 50.
nyelv No karakterlánc "en" Kétbetűs ISO 639-1 nyelvi kód a keresési eredmények felületi nyelvéhez. A teljes lista támogatott nyelvei című témakörben talál további információt.
régió No karakterlánc "US" Kétbetűs ország-/régiókód, amelyből az eredmények származnak (pl. "US", "JP", "GB", stb.). A teljes listát a Támogatott régiók című témakörben találja.
hely No karakterlánc - Helyinformációk "lat:<float>; long:<float>", pl. "lat:40.753250; long:-74.003807". Ha nincs megadva, a rendszer a lekérdezésben lévő helyet fogja kikövetkeztetni.
contentFormat No karakterlánc "passzázs" ("html" teljes dokumentumhozzáféréssel) passage az egyes eredményeknek a lekérdezés szempontjából legrelevánsabb részeit adja vissza (földeléshez ajánlott). text, html majd markdown adja vissza a teljes dokumentumot, és csak a teljes dokumentumhozzáféréssel rendelkező alkalmazásokra vonatkozzanak; lásd : Passzusok és tartalomformátumok. Állítsa be minden kérésre. Megjegyzés: a webes API nem ad vissza snippet mezőt.
maximális hosszúság No egész szám 3000 (10000 teljes dokumentumhozzáféréssel) Az eredményben szereplő content karakterek maximális száma 1–500000. Teljes dokumentumhozzáférés content nélkül legfeljebb 3000 karakter hosszúságú lehet. Lásd : Alapértelmezett értékek és korlátok. Állítsa be minden kérésre.
safeSearch No karakterlánc "szigorú" A biztonságos keresés szűrésének szintje. Értékek: "ki", "szigorú". Az alapértelmezett érték a "szigorú".

Tartalomformátumok

Állítsa be contentFormat = passage , hogy az egyes eredményeknek a lekérdezés szempontjából legrelevánsabb részeit adja meg, akár karakterekig maxLength (a 3000 jó kiindulópont). Ez a földelés ajánlott formátuma; lásd : Mi az, passageés miért használja? című témakört a gyakori kérdések között. A teljes dokumentumhozzáféréssel rendelkező alkalmazások a teljes dokumentumot is kérhetik, htmlmarkdownmás textalkalmazások esetén a formátumok HTTP 403-at adnak vissza. Lásd : Szakaszok és tartalomformátumok.

Biztonságos keresés

A SafeSearch módokkal szabályozhatja, hogy a webes API mennyi bizalmas webes tartalmat szűr ki az eredmények visszaadása előtt. A bizalmas tartalmak közé tartozik az erőszak, az önkárosítás és más kategóriák. Az alapértelmezett érték strict.

Value Description Ajánlott:
strict Letiltja a felnőttekkel, a ráfával, az erőszakkal, a gyűlölettel és az önkárosítással kapcsolatos tartalmakat. Gyermekbiztos, oktatási, fogyasztói/konzervatív környezetek.
off Továbbra is letiltja az illegális tartalmakat. Egyéb potenciálisan káros tartalmak esetén a végső szűrés felelősségét a felhasználóra hárítja. Kutatás, elemzés, vállalati jóváhagyás, fejlett 3P használati esetek.

Note

Ha a lekérdezési operátort site: használja, a válasz az értéktől függetlenül safeSearch tartalmazhat felnőtt tartalmat. Csak akkor használja site: , ha tisztában van a webhelyen található tartalommal, és a forgatókönyv támogatja a felnőtt tartalmak lehetőségét.

Kérelemfejlécek

Field Típus Description
állomás karakterlánc Gazdagép Microsoft AI API-khoz: api.microsoft.ai.
x-apikey vagy Engedélyezés karakterlánc Az API-kulcs vagy Entra ID hozzáférési jogkivonat hitelesítéshez.
tartalomtípus karakterlánc A kérelem törzsének MIME-típusa. Használja a application/json.

Response

Webes válasz

Field Típus Description
webResults a webResult tömbje A weblap eredményeinek listája.
querySignals querySignals Lekérdezésszintű rangsorolási jelek a keresési lekérdezéshez.
riskLevel karakterlánc A lekérdezés biztonsági kockázati szintje. Lehetséges értékek: low, moderate, high. veryHigh
instrumentationClickBase karakterlánc A kattintási pingelési kérelmek alap URL-címe. Adjon hozzá egy instrumentationSuffix értéket egy eredményelemből a teljes ping URL-cím létrehozásához. Csak az EnableInstrumentationPing profiljelzővel rendelkező alkalmazások esetén jelenik meg. Megjegyzés: A felhasználói kattintások URL-átirányítással is naplózhatók. Ha az átirányítás engedélyezve van, nincs szükség műveletre a felhasználói kattintások naplózásához, és instrumentationClickBase nem lesz belefoglalva a válaszba. A beállítási utasításokért tekintse meg a Instrumentation útmutatót .
instrumentationCitationBase karakterlánc Az LLM-napló pingelési kérelmeinek alap URL-címe. Fűzze hozzá a DATA hasznos adatait a teljes ping URL-cím létrehozásához. Csak az EnableInstrumentationPing profiljelzővel rendelkező alkalmazások esetén jelenik meg.
traceId karakterlánc Nyomkövetési azonosító a hibakereséshez.

querySignals

Field Típus Description
freshness boolean Azt jelzi, hogy a friss dokumentumokat rangsorolja-e a lekérdezés más dokumentumainál.

webResult

Field Típus Description
title karakterlánc A weblap címe.
url karakterlánc A weblap forrás URL-címe. Az URL-átirányítást engedélyező kínai felhasználók esetében ez a mező ehelyett ugyanazt az átirányítási URL-címet tartalmazza, mint clickUrla .
tartomány karakterlánc Az eredmény cél állomása. Csak olyan kínai felhasználók esetében adja vissza, akiknél engedélyezve van az URL-átirányítás.
tartalom karakterlánc A weboldal részletes tartalma (más néven földelés).
crawledAt karakterlánc A weblap utolsó bejárt dátuma ISO8601 formátumot követi.
utolsóFrissítveAt karakterlánc A weblap utolsó frissített dátuma ISO8601 formátumot követi.
nyelv karakterlánc A weblap nyelve ISO 639-1 nyelvi kódot használ.
isAdult boolean Azt jelzi, hogy az eredmény tartalmaz-e felnőtt tartalmat.
clickUrl karakterlánc Átirányítási URL-cím, amely a Bingen keresztül irányítja át a kattintást. Csak akkor jelenik meg, ha a kattintás átirányítása engedélyezve van.
instrumentationSuffix karakterlánc Utótag az eredményelem rendszerállapot-ping URL-alapjához való hozzáfűzéshez. A rendszerállapot pingELÉSI URL-címéhez és az clickUrl átirányításhoz egyaránt K-értékként használatos. Akkor jelenik meg, ha a rendszerállapot-ping engedélyezve van.
contentTier karakterlánc Az eredmény tartalomszintje, amely a tartalomforrás kereskedelmi hozzáférési jellemzőit írja le. Lehetséges értékek: standard (az alapértelmezett szolgáltatásajánlatban minden ügyfél számára elérhető standard tartalom), entitled (meglévő ügyféllicenc-szerződéseken keresztül elérhető tartalom, beleértve a saját licenc (BYOL) tartalmakat is, amelyeket az ügyfelek közvetlenül a közzétevőktől licencelnek, és a saját szerződéses megállapodásaikon keresztül férnek hozzá) premium (prémium tartalom, amely a standard ajánlaton túl további értéket biztosít, és számlázás tárgyát képezi).

Note

crawledAt Az értékek és lastUpdatedAt mezők megadása nem kötelező. Vagyis a lefedettségük nem 100%. Ezeknél a mezőknél üres értékek jelenhetnek meg.

Hibakódok

Állapotkód Hibakategória Description Gyakori okok
200 Success A kérés sikeres volt. -
400 Hibás kérés Érvénytelen kérelemparaméterek. Hiányzó kötelező mezők, érvénytelen paraméterértékek, hibásan formázott JSON
401 Unauthorized A hitelesítés sikertelen vagy hiányzik. Érvénytelen API-kulcs, hiányzó x-apikey fejléc
403 Forbidden Érvényes hitelesítő adatok, de nem megfelelő engedélyek. Az API-kulcs nem rendelkezik szükséges engedélyekkel
410 Eltűnt HTTPS szükséges. HTTPS helyett HTTP-en keresztül küldött kérelem
415 Nem támogatott médiatípus A tartalomtípus nem támogatott. Hiányzó vagy helytelen tartalomtípusú fejléc
429 Túl sok kérés Túllépte a sebességkorlátot. Túl sok kérés az időablakban
500 Belső kiszolgálóhiba Váratlan kiszolgálóhiba. Ideiglenes kiszolgálóval kapcsolatos probléma
503 A szolgáltatás nem érhető el A szolgáltatás átmenetileg nem érhető el. Karbantartás vagy ideiglenes kimaradás
504 Átjáró időkorlát túllépve A kérés túllépte az időkorlátot. Upstream szolgáltatás időtúllépése

A hibakezeléssel kapcsolatos részletes útmutatásért tekintse meg a Hibakezelés című témakört.

Lásd még:Videók keresés tallózása | | Hírek keresése | Képek keresése | MCP

  • Utolsó frissítés időpontja: