Przeglądanie dokumentacji interfejsu API REST

Punkt końcowy:POST https://api.microsoft.ai/v3/browse

Przykładowe żądanie:

curl -X POST "https://api.microsoft.ai/v3/browse" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your key>" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
    "query": "How fast is Web IQ",
    "contentFormat": "passage",
    "maxLength": 3000,
    "liveCrawl": "fallback",
    "language": "en",
    "region": "US"
  }'

Fragmenty są zalecanym formatem uziemienia. Aplikacje z pełnym dostępem do dokumentów mogą zamiast tego żądać całej strony, ustawiając wartość contentFormat na text, htmllub markdown. Zobacz Fragmenty tekstu i formaty zawartości.

Parameters

Parameter Required Typ Default Description
url Yes ciąg - Adres URL strony internetowej do przeglądania.
kwerenda Wymagane dla passage ciąg - Zapytanie używane do wybierania fragmentów ze strony, maksymalnie 1000 znaków. Żądanie passage wymaga kwerendy, która nie jest pusta. W przypadku innych formatów query jest opcjonalne. Wartość dłuższa niż 1000 znaków zwraca wartość HTTP 400. Ten limit jest niezależny od maxLength.
maksymalna długość No liczba całkowita 3000 (10000 z pełnym dostępem do dokumentu) Maksymalna liczba znaków w contentliczbie od 1 do 500000. Wartość poza tym zakresem zwraca wartość HTTP 400. Bez pełnego dostępu do content dokumentu wynosi co najwyżej 3000 znaków, a większe wartości są ograniczone do 3000.
liveCrawl No ciąg "brak" Steruje zachowaniem przeszukiwania na żywo. Obsługiwane wartości: "none" (zwracana jest tylko zawartość indeksowana bez przeszukiwania na żywo) i "rezerwowa" (żądanie przeszukiwania na żywo, jeśli adres URL nie zostanie znaleziony w indeksie). W przypadku wartości "none", jeśli adres URL nie zostanie znaleziony w indeksie, interfejs API zwróci wartość 404 (nie znaleziono adresu URL).

Uwaga: Przeszukiwanie na żywo podlega ograniczeniom uprzejmości wydawcy i dostępności; "powrót" nie gwarantuje rzeczywistego przeszukiwania.
includeWebLinks No boolean false Dołącz hiperłącza wychodzące ze strony. Ignorowane dla zawartości fragmentu.
renderDynamicPages No boolean false Włącz renderowanie w języku JavaScript na potrzeby zrzutu ekranu zawartości dynamicznej. Działa tylko wtedy, gdy parametr liveCrawl ma wartość "fallback".
includeImageLinks No boolean false Dołącz adresy URL obrazów ze strony. Ignorowane dla zawartości fragmentu.
język No ciąg "en" Kod języka (2 litery ISO 639-1). Aby uzyskać pełną listę, zobacz Obsługiwane języki .
region No ciąg "US" Kod regionu (2-literowy kod kraju/regionu). Aby uzyskać pełną listę, zobacz Obsługiwane regiony .
contentFormat (format treści) No ciąg "fragment" ("html" z pełnym dostępem do dokumentu) Wyrażenie "fragment" zwraca części strony najbardziej istotne query (zalecane do uziemienia). "text", "html" i "markdown" zwracają pełny dokument i stosują się tylko do aplikacji z pełnym dostępem do dokumentu; bez niego zwracają http 403 (AuthContentFormatForbidden). Zobacz Fragmenty tekstu i formaty zawartości.

W przypadku żądań fragmentów ustaw contentFormat wartość "fragment" i wyślij element inny niż query. Jeśli wyjedziesz contentFormatwartość domyślną , "fragment" jest domyślny, chyba że aplikacja ma pełny dostęp do dokumentu, gdzie wartość domyślna to "html". Żądanie przejścia bez query zwraca protokołu HTTP 400 (HandlerInvalidInput).

Żądania fragmentu

Żądanie fragmentu podlega normalnej weryfikacji żądania oraz następujących elementów:

  • query musi zawierać tekst inny niż biały znak i zawierać maksymalnie 1000 znaków. W przeciwnym razie żądanie zwraca błąd HTTP 400 (HandlerInvalidInput).
  • liveCrawl musi mieć wartość "none" lub "fallback".

W przypadku protokołu MCP te błędy zwracają błąd HTTP 200 z błędem narzędzia (result.isError: true), który zawiera oryginalny identyfikator żądania. Fragment jest zwracany w istniejącym content polu. Odpowiedź ma taki sam kształt jak w przypadku innych formatów zawartości.

Zawartość fragmentu

Fragment to skoncentrowany na zapytaniu wyodrębnienie żądanej strony. Zamiast zwracać stronę od początku, usługa wybiera części strony najbardziej istotne query i zwraca je w content polu.

  • Wybór: strona jest podzielona na segmenty, które są klasyfikowane według istotności do query. Segmenty o najwyższej klasyfikacji są wybierane do momentu maxLength osiągnięcia budżetu.
  • Kolejność: wybrane segmenty są zwracane w oryginalnej kolejności stron, a nie w kolejności klasyfikacji. Segmenty nieprzyległe są oddzielone ....
  • Granice segmentów: segmenty są definiowane według długości, a nie według zdania lub akapitu, więc fragment może zaczynać lub kończyć zdanie środkowe. Wyświetl fragmenty jako fragmenty i użyj źródła url do przypisania.
  • Format: zawartość fragmentu to zwykły tekst. Znaczniki, hiperłącza i odwołania do obrazów nie są uwzględniane w elemencie content.
  • Długość:content nigdy nie przekracza maxLength znaków. Wartość domyślna maxLength to 3000 bez pełnego dostępu do dokumentu i 10000 z pełnym dostępem do dokumentów. Krótkie strony można zwrócić w całości.
  • Powrót: jeśli wybór istotności jest tymczasowo niedostępny dla żądania, usługa zwraca początek strony jako zwykły tekst, obcięty do maxLength.
  • Ograniczenia zawartości: zasady wydawcy i witryny, takie jak dyrektywy robotów i reguły paywall, są stosowane przed wyborem. Fragmenty są wybierane tylko z zawartości, którą można zwrócić dla strony.
  • Inne zachowanie: Rozpoznawanie adresów URL, przeszukiwanie na żywo z odpowiedziami "rezerwowymi", oczekującymi odpowiedziami przeszukiwania (HTTP 202), polami odpowiedzi, takimi jak title, crawledAti isAdulti , i odpowiedzi na błędy są takie same jak w przypadku innych formatów zawartości.

Nagłówki żądań

Pole Typ Description
gospodarz ciąg Host dla interfejsów API sztucznej inteligencji Microsoft: api.microsoft.ai.
x-apikey lub authorization ciąg Klucz interfejsu API lub token dostępu Entra ID na potrzeby uwierzytelniania.
typ zawartości ciąg Typ MIME treści żądania. Użyj application/json.

Odpowiedź

Pole Typ Description
url ciąg Adres URL strony internetowej lub adres URL, który ma być ponowiony, gdy przeszukiwanie oczekuje.
title ciąg Tytuł strony internetowej.
zawartość ciąg Wyodrębniona zawartość strony internetowej (czyli uziemienia). W przypadku żądania fragmentu fragmenty wybrane dla queryelementu .
lastUpdatedAt ciąg Data ostatniej aktualizacji strony internetowej jest zgodna z formatem ISO8601.
crawledAt ciąg Data ostatniego przeszukania strony internetowej jest zgodna z formatem ISO8601.
traceId ciąg Identyfikator śledzenia na potrzeby debugowania.
ponawianie ponawiania prób ciąg Najwcześniejszy czas ponawiania próby jako sygnatura czasowa ISO 8601 UTC (na przykład "2026-10-30T01:01:00Z"). Występuje, gdy przeszukiwanie na żądanie jest w toku (202) i w przypadku niektórych błędów.
isAdult boolean Wskazuje, czy strona internetowa zawiera zawartość dla dorosłych.

Note

Pola title, content, isAdult, lastUpdatedAti crawledAt są obecne tylko w odpowiedziach zakończonych powodzeniem (200). Są one pomijane z ponownych prób (202) odpowiedzi.

Przykład: żądanie fragmentu i odpowiedź

Żądanie w powyższym przykładzie zwraca odpowiedź podobną do poniższej. Usługa wybrała nieprzyległe segmenty strony i połączyła je z elementem ....

{
  "url": "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
  "title": "Why AI agents need external grounding | Microsoft Web IQ",
  "content": "Why AI agents need external grounding | Microsoft Web IQ Microsoft Community Hub Azure Microsoft Developer Community Blog nodeTitle minReadText Why AI Agents Need External Grounding bkingms Microsoft Oct 18, 2026 Earlier this year, we introduced Microsoft Web IQ, a suite of AI-native web search and grounding APIs that gives LLMs, AI agents, and applications access to current, relevant web information. This post explores why web grounding is becoming a foundational layer of AI, how it helps deliver answers customers can use and verify, and how we’re addressing the quality, speed, and efficiency developers need. -- When customers ask an AI agent or application for help, the answer may do more than inform them—it may shape a recommendation, trigger a workflow, or guide an action. If that answer relies on... ... an engineering approach that treats quality, speed, and token efficiency as a connected problem. You can read more on our engineering approach here. Highest grounding satisfaction. On a 3,000 query blind test sampled from production traffic, Web IQ scored 79.05 against 75.70 for the next best service and more than 14 points ahead of the lowest. It gets there by returning more complete, structured context drawn from web, news, images, and video. What your users see is answers that hold up: more accurate, more consistent, and properly attributed. In the domains where source quality, freshness, and attribution drive the decision, that is the difference between an agent people act on and one they quietly double check. 2.5x faster than today's best alternative. P95 latency measured 164 milliseconds across five datacenter regions, against 406 for the closest competitor and 2,090 for the slowest. Latency compounds in agent workloads, because a multi-step chain pays the retrieval cost at every hop. Cutting it at each step keeps workflows moving and keeps interactive agents feeling interactive instead of batch. Highest quality answers with the fewest tokens. Web IQ sits on a new Pareto curve of efficiency, reaching peak quality at around 40,000 tokens per query while competing services spend 60,000 to 100,000 to score lower. Prioritizing the most relevant passages and cutting unnecessary context reduces both token spend and reasoning time, and those savings compound across high volume production workloads. Most web search APIs force a tradeoff — fast or accurate, cost-efficient or complete. Web IQ is delivers across the board: industry-leading quality, fastest performance, and fewest tokens per query — all in an enterprise-ready solution. For teams evaluating Web IQ, those results provide a starting point. We recommend testing your own questions, sources, models, and end-to-end workflows to understand how retrieval quality and efficiency translate into customer outcomes. Grounding satisfaction is a benchmark score, not an accuracy percentage, and retrieval latency is only one part of the time required to complete a task. Within Microsoft IQ,...",
  "isAdult": false,
  "lastUpdatedAt": "2026-10-18T00:00:00",
  "crawledAt": "2026-10-29T07:44:00Z",
  "traceId": "6ae4fd995e3d425f847c07c2f0839e38"
}

Kody błędów

Kod stanu Kategoria błędów Description Typowe przyczyny
200 Powodzenie Żądanie zakończyło się pomyślnie. -
202 Zaakceptowano Żądanie zaakceptowane do przetwarzania (przeszukiwanie na żywo). Przeszukiwanie na żądanie jest w toku
400 Nieprawidłowe żądanie Nieprawidłowe parametry żądania. Brak wymaganych pól, nieprawidłowe wartości parametrów, nieprawidłowo sformułowany kod JSON, brakujące lub puste query dla żądania fragmentu
401 Brak autoryzacji Uwierzytelnianie nie powiodło się lub nie powiodło się. Nieprawidłowy klucz interfejsu API, brak nagłówka x-apikey
403 Dostęp zabroniony Prawidłowe poświadczenia, ale nie można spełnić żądania. Klucz interfejsu API nie ma wymaganych uprawnień, adres URL zablokowany przez zasady, filtrowaną zawartość, texthtmllub markdown żądaną bez pełnego dostępu do dokumentu
404 Nie znaleziono Nie można odnaleźć dokumentu. Nieprawidłowy lub niedostępny adres URL
410 Zniknęło Wymagany protokół HTTPS. Żądanie wykonane za pośrednictwem protokołu HTTP zamiast HTTPS
415 Nieobsługiwany typ nośnika Typ zawartości nie jest obsługiwany. Brak lub niepoprawny nagłówek typu zawartości
429 Zbyt wiele żądań Przekroczono limit szybkości lub przeszukiwania na żądanie. Zbyt wiele żądań w przedziale czasu lub nadmierne żądania przeszukiwania na żywo
430 Zbyt wiele przeszukiwań na żądanie Zbyt wiele przeszukiwań na żądanie (starsze kody błędów). Nadmierne żądania przeszukiwania na żywo
500 Wewnętrzny błąd serwera Nieoczekiwany błąd serwera. Tymczasowy problem z serwerem
503 Usługa niedostępna Usługa jest tymczasowo niedostępna. Konserwacja lub tymczasowa awaria
504 Przekroczono limit czasu bramy Upłynął limit czasu żądania. Limit czasu usługi nadrzędnej
520 Przetwarzanie zawartości nie powiodło się Strona została pobrana, ale nie można utworzyć zawartości użytecznej. Przetwarzanie dokumentów nie powiodło się lub upłynął limit czasu lub upłynął limit czasu renderowania dynamicznego
523 Przeszukiwanie anulowane Przeszukiwanie nie wygenerowało zawartości z powodu ograniczonego limitu przydziału przeszukiwania witryny. Ograniczony limit przydziału przeszukiwania dla hosta źródłowego
524 Limit czasu przeszukiwania Przeszukiwanie nie wygenerowało zawartości, ponieważ upłynął limit czasu. Przekroczono limit czasu hosta zdalnego

Błędy żądania fragmentu

Te błędy dotyczą żądań fragmentów. Są one również stosowane, gdy "fragment" jest formatem domyślnym.

Warunek Status HTTP Kod błędu
query brakuje znaków, jest ona pusta lub dłuższa niż 1000 znaków 400 HandlerInvalidInput
Aplikacja bez pełnych żądań textdostępu do dokumentów , htmllub markdown 403 AuthContentFormatForbidden

Szczegółowe kody błędów

Szczegółowe kody błędów są domyślnie włączone dla opcji Przeglądaj. Identyfikują one konkretny powód, dla którego nie można zwrócić strony, na przykład filtrowanie zawartości, brakujący dokument lub błąd przeszukiwania, i zawierają wskazówki dotyczące ponawiania, jeśli ma to zastosowanie. Nie jest wymagane żadne wyrażenie zgody ani żądanie pomocy technicznej.

Aby uzyskać pełną listę kodów i zalecanych akcji, zobacz Przeglądanie błędów specyficznych dla interfejsu API.

Aby uzyskać szczegółowe wskazówki dotyczące obsługi błędów, zobacz Obsługa błędów.

Zobacz również: Wyszukiwaniewideo wyszukiwania wiadomości | w Sieci Web | Wyszukiwanieobrazów wyszukiwania | w internecieMCP |

  • Ostatnia aktualizacja o