Referenční informace k rozhraní REST API pro vyhledávání na webu

Koncový bod:POST https://api.microsoft.ai/v3/search/web

Ukázkový požadavek:

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 Typ Výchozí Description
dotaz Ano řetězec - Řetězec vyhledávacího dotazu. Maximální délka je 1000 znaků. Podporuje operátory "site:" a "-site:", aby zahrnovaly nebo vyloučily výsledky z konkrétních webů (např. "dotaz site:example.com"). Tyto operátory používejte pouze v případě potřeby, protože ze své podstaty snižují relevanci výsledku.
maxResults No integer 10 Maximální počet výsledků, které se mají vrátit. Výchozí hodnota je 10 a maximální hodnota je 50.
jazyk No řetězec "en" Dvoumísmenný kód jazyka ISO 639-1 pro jazyk rozhraní ve výsledcích hledání. Úplný seznam najdete v části Podporované jazyky .
oblast No řetězec "US" 2písmenný kód země/oblasti, odkud mají výsledky pocházet (např. "US", "JP", "GB" atd.). Úplný seznam najdete v části Podporované oblasti .
poloha No řetězec - Informace o poloze ve formátu "lat:<float>; long:<float>", např. lat:40.753250; long:-74.003807". Pokud není zadáno, umístění v dotazu by bylo odvozeno.
Formát obsahu No řetězec "passage" ("html" s úplným přístupem k dokumentu) passage vrátí části každého výsledku, které jsou pro dotaz nejrelevantní (doporučeno pro uzemnění). text html a vrátit celý dokument a markdown použít pouze pro aplikace s úplným přístupem k dokumentu; viz Pasáže a formáty obsahu. Nastavte ho pro každý požadavek. Poznámka: Webové rozhraní API nevrací snippet pole.
maximální délka No integer 3000 (1 0000 s úplným přístupem k dokumentům) Maximální počet znaků na content výsledek, 1 až 5 00000. Bez úplného přístupu k content dokumentu je maximálně 3000 znaků. Viz Výchozí hodnoty a limity. Nastavte ho pro každý požadavek.
safeSearch No řetězec "striktní" Úroveň bezpečného filtrování hledání Hodnoty: "off", "strict". Výchozí hodnota je "striktní".

Formáty obsahu

Nastaví contentFormat = passage se pro získání částí každého výsledku, který je pro dotaz nejrelevavantnější, až maxLength znaky (3000 je dobrým výchozím bodem). Je to doporučený formát pro uzemnění; Podívejte se na článek Co je passagea proč ho používat? v nejčastějších dotazech. Aplikace s úplným přístupem k dokumentům mohou také požadovat celý dokument jako text, html nebo markdown; pro jiné aplikace, tyto formáty vrací HTTP 403. Viz pasáže a formáty obsahu.

Bezpečné hledání

Režimy bezpečného hledání umožňují určit, kolik citlivého webového obsahu webové rozhraní API filtruje před vrácením výsledků. Citlivý obsah zahrnuje násilí, sebepoškozování a další kategorie. Výchozí hodnota je strict.

Value Description Doporučeno pro
strict Blokuje obsah související s tématy pro dospělé,raci, násilí, nenávist a sebepoškozování. Dětská, vzdělávací, spotřebitelská/konzervativní nasazení.
off Pořád blokuje neplatný obsah. V případě jiného potenciálně škodlivého obsahu přemísní odpovědnost za konečné filtrování uživatele. Výzkum, analýza, opt-in enterprise, pokročilé 3P případy použití.

Note

Pokud použijete site: operátor dotazu, odpověď může obsahovat obsah pro dospělé bez safeSearch ohledu na hodnotu. Používejte site: pouze v případě, že znáte obsah na webu a váš scénář podporuje možnost obsahu pro dospělé.

Hlavičky požadavku

Field Typ Description
hostitel řetězec Hostitel pro rozhraní API Microsoft AI: api.microsoft.ai.
x-apikey nebo authorization řetězec Váš klíč rozhraní API nebo Entra ID přístupový token pro ověřování.
typ obsahu řetězec Typ MIME textu požadavku. Použijte application/json.

Response

Webová odpověď

Field Typ Description
webResults array of webResult Seznam výsledků webové stránky
querySignals querySignals Signály řazení na úrovni dotazu pro vyhledávací dotaz
riskLevel řetězec Úroveň bezpečnostního rizika vyhodnocená pro dotaz. Možné hodnoty: low, moderate, high, veryHigh.
instrumentationClickBase řetězec Základní adresa URL pro kliknutí na požadavky ping instrumentationSuffix Připojte hodnotu z položky výsledku, která vytvoří úplnou adresu URL příkazu Ping. K dispozici pouze pro aplikace s příznakem profilu EnableInstrumentationPing. Poznámka: Kliknutím uživatele lze také protokolovat pomocí přesměrování adresy URL. Pokud je přesměrování povolené, nevyžaduje se žádná akce pro protokolování kliknutí uživatele a instrumentationClickBase nebude zahrnuta do odpovědi. Pokyny k nastavení najdete v průvodci instrumentací .
instrumentationCitationBase řetězec Základní adresa URL pro požadavky ping protokolu LLM Připojte datovou část k vytvoření úplné adresy URL příkazu Ping. K dispozici pouze pro aplikace s příznakem profilu EnableInstrumentationPing.
traceId řetězec ID trasování pro ladění

querySignals

Field Typ Description
freshness boolean Určuje, zda mají být u jiných dokumentů pro tento dotaz upřednostňovány nové dokumenty.

webResult

Field Typ Description
title řetězec Název webové stránky.
url řetězec Zdrojová adresa URL webové stránky. Pro uživatele v Číně s povoleným přesměrováním adresy URL místo toho toto pole obsahuje stejnou adresu URL přesměrování jako clickUrl.
doména řetězec Cílový hostitel výsledku. Vráceno pouze pro uživatele v Číně s povoleným přesměrováním adresy URL.
obsah řetězec Podrobný obsah webové stránky (neboli uzemnění).
crawledAt řetězec Datum posledního procházení webové stránky se řídí formátem ISO8601.
lastUpdatedAt řetězec Datum poslední aktualizace webové stránky se řídí formátem ISO8601.
jazyk řetězec Jazyk webové stránky používá kód jazyka ISO 639-1.
isAdult boolean Určuje, jestli výsledek obsahuje obsah pro dospělé.
clickUrl řetězec Přesměrujte adresu URL, která přesMěruje proxy přes Bing. Je k dispozici pouze v době, kdy je povoleno kliknutí na přesměrování.
instrumentationSuffix řetězec Přípona pro připojení k základu adresy URL příkazu ping instrumentace pro tuto položku výsledku. Používá se jako hodnota K pro adresu URL příkazu ping instrumentace i pro clickUrl přesměrování. Je k dispozici, když je povolený příkaz ping instrumentace.
contentTier řetězec Úroveň obsahu výsledku popisující charakteristiky komerčního přístupu zdroje obsahu. Možné hodnoty: standard (standardní obsah dostupný pro všechny zákazníky v rámci výchozí nabídky služeb), entitled (obsah dostupný prostřednictvím stávajících licenčních smluv se zákazníky, včetně obsahu ByOL (Bring Your Own License ), který mají zákazníci licencované přímo od vydavatelů a přístup prostřednictvím vlastních smluvních ujednání), premium (prémiový obsah, který poskytuje další hodnotu nad rámec standardní nabídky a podléhá fakturaci).

Note

crawledAt Hodnoty polí a lastUpdatedAt polí jsou volitelné. To znamená, že jejich pokrytí není 100%. U těchto polí se můžou zobrazit prázdné hodnoty.

Kódy chyb

Kód stavu Kategorie chyb Description Běžné příčiny
200 Success Žádost byla úspěšná. -
400 Nesprávná žádost Neplatné parametry požadavku. Chybí požadovaná pole, neplatné hodnoty parametrů, chybně formátovaný JSON.
401 Neautorizováno Ověřování se nezdařilo nebo chybí. Neplatný klíč rozhraní API, chybějící hlavička x-apikey
403 Zakázáno Platné přihlašovací údaje, ale nedostatečná oprávnění Klíč rozhraní API nemá požadovaná oprávnění
410 Pryč Vyžaduje se HTTPS. Požadavek provedený přes PROTOKOL HTTP místo HTTPS
415 Nepodporovaný typ média Typ obsahu není podporován. Chybějící nebo nesprávná hlavička typu obsahu
429 Příliš mnoho požadavků Byl překročen limit rychlosti. Příliš mnoho požadavků v časovém intervalu
500 Vnitřní chyba serveru Neočekávaná chyba serveru Dočasný problém se serverem
503 Služba není k dispozici Služba je dočasně nedostupná. Údržba nebo dočasný výpadek
504 Časový limit brány Vypršel časový limit požadavku. Upstreamový časový limit služby

Podrobné pokyny pro zpracování chyb najdete v tématu Zpracování chyb.

Viz také: Vyhledávání obrázkůvyhledávání | zprávpomocí | videí | | MCP

  • Poslední aktualizace v