Dokumentacja interfejsu API REST wyszukiwania w Sieci Web

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

Przykładowe żądanie:

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 Default Description
kwerenda Yes ciąg - Ciąg zapytania wyszukiwania. Maksymalna długość to 1000 znaków. Obsługuje operatory "site:" i "-site:", aby uwzględnić lub wykluczyć wyniki z określonych witryn (np. "zapytanie site:example.com"). Używaj tych operatorów tylko wtedy, gdy jest to konieczne, ponieważ z natury zmniejszają znaczenie wyników.
maksWyniki No liczba całkowita 10 Maksymalna liczba wyników do zwrócenia. Wartość domyślna to 10, a wartość maksymalna to 50.
język No ciąg "en" Dwuliterowy kod języka ISO 639-1 dla języka interfejsu w wynikach wyszukiwania. Aby uzyskać pełną listę, zobacz Obsługiwane języki .
region No ciąg "US" Dwuliterowy kod kraju/regionu, z którego powinny pochodzić wyniki (np. "USA", "JP", "GB" itp.). Aby uzyskać pełną listę, zobacz Obsługiwane regiony .
lokalizacja No ciąg - Informacje o lokalizacji w formacie "lat:<float>; long:<float>", np. "lat:40.753250; long:-74.003807". Jeśli nie zostanie określony, lokalizacja w zapytaniu zostanie wywnioskowana.
contentFormat (format treści) No ciąg "fragment" ("html" z pełnym dostępem do dokumentu) passage Zwraca części każdego wyniku najbardziej istotne dla zapytania (zalecane do uziemienia). text html i markdown zwróć pełny dokument i zastosuj tylko do aplikacji z pełnym dostępem do dokumentu; zobacz Fragmenty i formaty zawartości. Ustaw je na każdym żądaniu. Uwaga: internetowy interfejs API nie zwraca snippet pola.
maksymalna długość No liczba całkowita 3000 (10000 z pełnym dostępem do dokumentu) Maksymalna liczba znaków na content wynik, od 1 do 500000. Bez pełnego dostępu do content dokumentu jest co najwyżej 3000 znaków. Zobacz Wartości domyślne i limity. Ustaw je na każdym żądaniu.
safeSearch No ciąg "strict" Poziom filtrowania bezpiecznego wyszukiwania. Wartości: "off", "strict". Wartość domyślna to "strict".

Formaty zawartości

Ustaw contentFormat = passage , aby uzyskać części każdego wyniku najbardziej istotne dla zapytania, maksymalnie do maxLength znaków (3000 jest dobrym punktem wyjścia). Jest to zalecany format do uziemienia; zobacz Co to jest passage, i dlaczego go używać? w często zadawanych pytaniach. Aplikacje z pełnym dostępem do dokumentów mogą również żądać pełnego dokumentu jako text, html lub markdown; w przypadku innych aplikacji te formaty zwracają http 403. Zobacz Fragmenty i formaty zawartości.

Bezpieczne wyszukiwanie

Tryby SafeSearch umożliwiają kontrolowanie, ile poufnej zawartości internetowej interfejs API sieci Web filtruje przed zwróceniem wyników. Poufne treści obejmują przemoc, samookaleczenia i inne kategorie. Wartość domyślna to strict.

Value Description Zalecane dla
strict Blokuje treści związane z dorosłymi, rasistami, przemocą, nienawiścią i tematami samookaleczenia. Bezpieczne dla dzieci, edukacja, wdrożenia konsumenckie/konserwatywne.
off Nadal blokuje nielegalną zawartość. W przypadku innego potencjalnie szkodliwej zawartości przenosi odpowiedzialność za końcowe filtrowanie do użytkownika. Badania, analiza, opt-in enterprise, zaawansowane przypadki użycia 3P.

Note

Jeśli używasz site: operatora zapytania, odpowiedź może zawierać zawartość dla dorosłych niezależnie od safeSearch wartości. Używaj site: tylko wtedy, gdy masz świadomość zawartości w witrynie i scenariusz obsługuje możliwość korzystania z treści dla dorosłych.

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ź

Odpowiedź internetowa

Pole Typ Description
webResults tablica webResult Lista wyników strony internetowej.
querySignals querySignals Sygnały klasyfikacji na poziomie zapytania dla zapytania wyszukiwania.
riskLevel ciąg Poziom ryzyka bezpieczeństwa oceniany dla zapytania. Możliwe wartości: low, , moderatehigh, veryHigh.
instrumentacjaClickBase ciąg Podstawowy adres URL kliknięcia żądań ping. instrumentationSuffix Dołącz wartość z elementu wyniku, aby utworzyć pełny adres URL ping. Tylko dla aplikacji z flagą profilu EnableInstrumentationPing. Uwaga: kliknięcia użytkownika można również rejestrować przy użyciu przekierowania adresu URL. Po włączeniu przekierowania nie jest wymagana żadna akcja rejestrowania kliknięć użytkownika i instrumentationClickBase nie zostanie uwzględniona w odpowiedzi. Aby uzyskać instrukcje dotyczące konfiguracji, zobacz Przewodnik instrumentacji .
instrumentacjaCitationBase ciąg Podstawowy adres URL dla żądań ping dziennika LLM. Dołącz ładunek DANYCH, aby utworzyć pełny adres URL polecenia ping. Tylko dla aplikacji z flagą profilu EnableInstrumentationPing.
traceId ciąg Identyfikator śledzenia na potrzeby debugowania.

querySignals

Pole Typ Description
freshness boolean Wskazuje, czy nowe dokumenty powinny być priorytetowe dla innych dokumentów dla tego zapytania.

webResult

Pole Typ Description
title ciąg Tytuł strony internetowej.
url ciąg Źródłowy adres URL strony internetowej. W przypadku użytkowników Chin z włączonym przekierowywaniem adresu URL to pole zawiera ten sam adres URL przekierowania co clickUrl.
domena ciąg Host docelowy dla wyniku. Zwracane tylko dla użytkowników z Chin z włączonym przekierowywaniem adresów URL.
zawartość ciąg Szczegółowa zawartość (czyli uziemienie) strony internetowej.
crawledAt ciąg Data ostatniego przeszukania strony internetowej jest zgodna z formatem ISO8601.
lastUpdatedAt ciąg Data ostatniej aktualizacji strony internetowej jest zgodna z formatem ISO8601.
język ciąg Język strony internetowej używa kodu języka ISO 639-1.
isAdult boolean Wskazuje, czy wynik zawiera zawartość dla dorosłych.
clickUrl ciąg Adres URL przekierowania, który serwer proxy klika za pośrednictwem usługi Bing. Występuje tylko po włączeniu przekierowania kliknięcia.
instrumentacjaSuffix ciąg Sufiks dołączany do bazy adresów URL ping instrumentacji dla tego elementu wyniku. Używana jako wartość K zarówno dla adresu URL polecenia ping instrumentacji, jak i przekierowania clickUrl . Występuje, gdy polecenie ping instrumentacji jest włączone.
contentTier ciąg Warstwa zawartości wyniku opisująca cechy dostępu komercyjnego źródła zawartości. Możliwe wartości: standard (standardowa zawartość dostępna dla wszystkich klientów w ramach oferty usługi domyślnej), entitled (zawartość dostępna za pośrednictwem istniejących umów licencyjnych klientów, w tym zawartość Bring Your Own License (BYOL ), którą klienci licencjonowali bezpośrednio od wydawców i dostępu za pośrednictwem własnych uzgodnień umownych), premium (zawartość Premium, która zapewnia dodatkową wartość poza standardową ofertę i podlega rozliczeniam).

Note

crawledAt Wartości pól i lastUpdatedAt są opcjonalne. Oznacza to, że ich zasięg nie wynosi 100%. W tych polach mogą być widoczne puste wartości.

Kody błędów

Kod stanu Kategoria błędów Description Typowe przyczyny
200 Powodzenie Żądanie zakończyło się pomyślnie. -
400 Nieprawidłowe żądanie Nieprawidłowe parametry żądania. Brak wymaganych pól, nieprawidłowe wartości parametrów, nieprawidłowo sformułowany kod JSON
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 niewystarczające uprawnienia. Klucz interfejsu API nie ma wymaganych uprawnień
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. Zbyt wiele żądań w przedziale czasu
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

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

Zobacz również:Wyszukiwanie wideo | Przeglądaj | obrazywyszukiwania wiadomości Search | | MCP

  • Ostatnia aktualizacja o