Wyszukiwanie dokumentów (interfejs API REST w wersji zapoznawczej)

Artykuł
02/07/2024

Dotyczy: 2023-07-01-Preview, 2021-04-30-Preview, 2020-06-30-Preview

Ważne

2023-07-01-Preview dodaje:

Parametr zapytania "vectors" określający dowolne żądania zapytania wektorowego. Każdy obiekt powinien zawierać wektorowa reprezentacja zapytania, "k" liczby najbliższych sąsiadów, które mają zostać zwrócone w wynikach, oraz pól wektorów do użycia podczas wykonywania zapytania.

2021-04-30-Preview dodaje:

Funkcja "semanticConfiguration" obsługuje semantyczną klasyfikację określania zakresu dla określonych pól.
Wyrażenie "captions" zwraca frazy wyodrębnione z kluczowych fragmentów w najbardziej semantycznie sklasyfikowanych dokumentach.

2020-06-30-Preview dodaje:

Wyrażenie "queryType=semantic" obsługuje semantycznie korekcyjne i odpowiedzi.
Wyrażenie "searchFields" w zapytaniu semantycznym określa kolejność priorytetu pól używanych do formułowania podpisów i odpowiedzi. To podejście zostało zastąpione przez "semanticConfiguration" w 2021-04-30-Preview i jest teraz przestarzałe.
Funkcja "speller" umożliwia korektę pisowni w danych wejściowych zapytania.
"queryLanguage" jest wymagany zarówno dla "queryType=semantic" i "speller".
"featuresMode" rozpakuje wynik wyszukiwania, raportowanie częstotliwości terminów na pole, wynik podobieństwa poszczególnych pól i liczbę unikatowych dopasowań dla pola.

Żądanie zapytania dotyczy kolekcji dokumentów pojedynczego indeksu w usłudze wyszukiwania. Zawiera on parametry definiujące kryteria dopasowania i parametry kształtujące odpowiedź. Możesz również użyć aliasu indeksu , aby określić konkretny indeks zamiast używać samej nazwy indeksu.

W przypadku większości zapytań można użyć metody GET lub POST, ale należy użyć funkcji POST do wyszukiwania wektorowego, ponieważ parametry zapytania wektorowego nie mieszczą się w identyfikatorze URI. Parametry zapytania są określane w ciągu zapytania dla żądań GET i w treści żądania POST.

GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters] 
  Content-Type: application/json   
  api-key: [admin or query key]

Jeśli używasz funkcji POST, dodaj akcję "wyszukaj" jako parametr identyfikatora URI.

POST https://[service name].search.windows.net/indexes/[index name]/docs/search?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin or query key]

W przypadku wywołania metody GET długość adresu URL żądania nie może przekraczać 8 KB. Ta długość jest wystarczająca dla większości aplikacji. Jednak niektóre aplikacje generują duże zapytania, szczególnie gdy są używane wyrażenia filtru OData. W przypadku tych aplikacji protokół HTTP POST jest lepszym wyborem, ponieważ umożliwia większe filtry niż GET.

W przypadku funkcji POST liczba klauzul w filtrze jest czynnikiem ograniczającym, a nie rozmiarem nieprzetworzonego ciągu filtru, ponieważ limit rozmiaru żądania dla żądania POST wynosi około 16 MB. Mimo że limit rozmiaru żądania POST jest duży, wyrażenia filtru nie mogą być dowolnie złożone. Aby uzyskać więcej informacji na temat ograniczeń złożoności filtru, zobacz Składnia wyrażeń OData dla usługi Azure AI Search.

Parametry identyfikatora URI

Parametr	Opis
nazwa usługi	Wymagane. Ustaw tę nazwę na unikatową, zdefiniowaną przez użytkownika nazwę usługi wyszukiwania.
nazwa indeksu/dokumentacja	Wymagane. Określa kolekcję dokumentów nazwanego indeksu. Nazwa aliasu indeksu może być również używana zamiast nazwy indeksu.
parametry zapytania	Parametry zapytania są określane w identyfikatorze URI dla żądań GET i w treści żądania POST.
api-version	Wymagane. Bieżąca wersja to `2023-07-01-Preview`. Zobacz Wersje interfejsu API , aby uzyskać więcej wersji.

Zalecenia dotyczące kodowania adresów URL

Pamiętaj, aby kodować parametry zapytania specyficzne dla adresu URL podczas bezpośredniego wywoływania interfejsu API REST GET. W przypadku operacji search documents kodowanie adresów URL może być konieczne dla następujących parametrów zapytania:

search
$filter
facet
highlightPreTag
highlightPostTag

Kodowanie adresów URL jest zalecane tylko w przypadku poszczególnych parametrów. Jeśli przypadkowo zakodujesz cały ciąg zapytania (wszystko po elemecie ?), żądania zostaną przerwane.

Ponadto kodowanie adresów URL jest konieczne tylko w przypadku bezpośredniego wywoływania interfejsu API REST przy użyciu metody GET. Kodowanie adresów URL nie jest konieczne w przypadku korzystania z funkcji POST lub w przypadku korzystania z biblioteki klienta usługi Azure AI Search platformy .NET, która obsługuje kodowanie.

Nagłówki żądań

W poniższej tabeli opisano wymagane i opcjonalne nagłówki żądań.

Pola	Opis
Content-Type	Wymagane. Ustaw tę wartość na "application/json"
api-key	Opcjonalnie, jeśli używasz ról platformy Azure , a token elementu nośnego jest dostarczany w żądaniu, w przeciwnym razie wymagany jest klucz. Api-key to unikatowy ciąg generowany przez system, który uwierzytelnia żądanie w usłudze wyszukiwania. Żądania zapytań względem kolekcji dokumentów mogą określać klucz administratora lub klucz-zapytania jako klucz interfejsu API. Klucz zapytania jest używany na potrzeby operacji tylko do odczytu względem kolekcji dokumentów. Aby uzyskać szczegółowe informacje, zobacz Nawiązywanie połączenia z usługą Azure AI Search przy użyciu uwierzytelniania klucza .

Pola

Opis

Content-Type

Wymagane. Ustaw tę wartość na "application/json"

api-key

Opcjonalnie, jeśli używasz ról platformy Azure , a token elementu nośnego jest dostarczany w żądaniu, w przeciwnym razie wymagany jest klucz. Api-key to unikatowy ciąg generowany przez system, który uwierzytelnia żądanie w usłudze wyszukiwania. Żądania zapytań względem kolekcji dokumentów mogą określać klucz administratora lub klucz-zapytania jako klucz interfejsu API. Klucz zapytania jest używany na potrzeby operacji tylko do odczytu względem kolekcji dokumentów. Aby uzyskać szczegółowe informacje, zobacz Nawiązywanie połączenia z usługą Azure AI Search przy użyciu uwierzytelniania klucza .

Treść żądania

W przypadku polecenia GET: Brak.

W przypadku żądania POST:

{  
     "answers": "none" (default) | "extractive", 
     "count": true | false (default),
     "captions": "none" (default) | "extractive",
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "featuresMode" : "disabled" (default) | "enabled",
     "filter": "odata_filter_expression",  
     "highlight": "highlight_field_1, highlight_field_2, ...",  
     "highlightPreTag": "pre_tag",  
     "highlightPostTag": "post_tag",  
     "minimumCoverage": # (% of index that must be covered to declare query successful; default 100),  
     "orderby": "orderby_expression",
     "queryLanguage": "en-us" (default) | (a supported language code), 
     "queryType": "simple" (default) | "full" | "semantic",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" (default) | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "semanticConfiguration": "semantic_configuration_name",
     "sessionId" : "session_id",
     "skip": # (default 0), 
     "speller": "none" (default) | "lexicon",  
     "top": #,
     "vectors": [
      {
        "value": "a vector representation of the query",
        "k": an integer (number of nearest neighbors to return as top results),
        "fields": "a comma-delimited list of vector fields to use in the query"
      }
     ]
   }

Kontynuacja częściowych odpowiedzi wyszukiwania

Czasami usługa Azure AI Search nie może zwrócić wszystkich żądanych wyników w jednej odpowiedzi wyszukiwania. Częściowa odpowiedź może wystąpić z różnych powodów, takich jak wtedy, gdy zapytanie zwraca zbyt wiele dokumentów, nie określając $top lub określając wartość $top, która jest zbyt duża. W takich przypadkach usługa Azure AI Search zawiera adnotację @odata.nextLink w treści odpowiedzi, a także @search.nextPageParameters informację o żądaniu POST. Możesz użyć wartości tych adnotacji, aby sformułować kolejne żądanie wyszukiwania, aby uzyskać następną część odpowiedzi wyszukiwania. To zachowanie jest nazywane kontynuacją oryginalnego żądania wyszukiwania, a adnotacje są nazywane tokenami kontynuacji. Zobacz przykład w sekcji Odpowiedź, aby uzyskać szczegółowe informacje na temat składni tych adnotacji i miejsca ich wyświetlania w treści odpowiedzi.

Przyczyny, dla których usługa Azure AI Search może zwracać tokeny kontynuacji, są specyficzne dla implementacji i mogą ulec zmianie. Niezawodni klienci zawsze powinni być gotowi do obsługi przypadków, w których zwracana jest mniej dokumentów niż oczekiwano, a token kontynuacji jest dołączany do dalszego pobierania dokumentów. Należy również pamiętać, że aby kontynuować, należy użyć tej samej metody HTTP co oryginalne żądanie. Jeśli na przykład wysłano żądanie GET, wszystkie wysyłane żądania kontynuacji muszą również używać żądania GET (i podobnie dla żądania POST).

Uwaga

@odata.nextLink Celem i @search.nextPageParameters jest ochrona usługi przed zapytaniami, które żądają zbyt wielu wyników, a nie zapewnienie ogólnego mechanizmu stronicowania. Jeśli chcesz stronicować wyniki, użyj $top i $skip razem. Jeśli na przykład chcesz, aby strony miały rozmiar 10, pierwsze żądanie powinno mieć $top=10 i $skip=0, drugie żądanie powinno mieć $top=10, a $skip =10, trzecie żądanie powinno mieć $top=10 i $skip=20 itd.

Parametry zapytania

Zapytanie akceptuje kilka parametrów w adresie URL po wywołaniu za pomocą polecenia GET i jako właściwości JSON w treści żądania po wywołaniu za pomocą polecenia POST. Składnia niektórych parametrów różni się nieco między instrukcjami GET i POST. Te różnice zostały zanotowane w poniższej tabeli.

Nazwa	Typ	Opis
answers (wersja zapoznawcza)	ciąg	Opcjonalny. Prawidłowe wartości to "none" i "extractive". Wartość domyślna to "none". Ten parametr jest prawidłowy tylko wtedy, gdy typ zapytania jest "semantyczny". Po ustawieniu wartości "extractive" zapytanie formułuje i zwraca odpowiedzi z kluczowych fragmentów w najbardziej semantycznie sklasyfikowanych dokumentach. Wartość domyślna to jedna odpowiedź, ale można określić maksymalnie 10, dodając liczbę. Na przykład wyrażenie "answers": "extractive\|count-3" zwraca trzy odpowiedzi. Aby odpowiedzieć na odpowiedź, w polu docelowym musi znajdować się zawartość dosłowna, która wygląda jak odpowiedź. Modele językowe używane na potrzeby odpowiedzi są trenowane w celu rozpoznawania odpowiedzi, a nie generowania ich. Ponadto samo zapytanie musi wyglądać jak pytanie.
api-version	ciąg	Wymagane. Wersja interfejsu API REST używanego dla żądania. Aby uzyskać listę obsługiwanych wersji, zobacz Wersje interfejsu API. W przypadku tej operacji wersja interfejsu API jest określana jako parametr URI niezależnie od tego, czy wywołujesz funkcję Search Documents za pomocą polecenia GET, czy POST.
captions (wersja zapoznawcza)	ciąg	Opcjonalny. Prawidłowe wartości to "none" i "extractive". Wartość domyślna to "none". Ten parametr jest prawidłowy tylko wtedy, gdy typ zapytania jest "semantyczny". Po ustawieniu wartości "extractive" zapytanie zwraca podpisy wyodrębnione z kluczowych fragmentów w najbardziej sklasyfikowanych dokumentach. Gdy podpisy są ustawione na "wyodrębniające", wyróżnianie jest domyślnie włączone i można je skonfigurować, dołączając znak potoku "\|", a następnie opcję "highlight-true</false>", taką jak "extractive\|highlight-true".
$count	boolean	Opcjonalny. Prawidłowe wartości to "true" lub "false". Wartość domyślna to "false". Po wywołaniu metody POST ten parametr ma nazwę count zamiast $count. Określa, czy pobrać łączną liczbę wyników. Ta wartość to liczba wszystkich dokumentów pasujących do parametrów wyszukiwania i $filter, ignorując $top i $skip. Ustawienie tej wartości na wartość "true" może obniżyć wydajność. Liczba jest dokładna, jeśli indeks jest stabilny, ale będzie zawierać lub zgłaszać wszystkie dokumenty, które są aktywnie dodawane, aktualizowane lub usuwane. Jeśli chcesz uzyskać tylko liczbę bez żadnych dokumentów, możesz użyć $top=0.
aspekty lub aspekty	ciąg	Opcjonalny. Pole do aspektu według, gdzie pole jest przypisywane jako "facetable". Po wywołaniu polecenia GET `facet` jest polem (`facet: field1`). Po wywołaniu metody POST ten parametr ma nazwę `facets` zamiast `facet` i jest określony jako tablica (`facets: [field1, field2, field3]`). Ciąg może zawierać parametry, aby dostosować aspekty, wyrażone jako pary nazwa-wartość rozdzielona przecinkami. Prawidłowe wartości to "count", "sort", "values", "interval" i "timeoffset". "count" jest maksymalną liczbą terminów aspektowych; wartość domyślna to 10. Nie ma górnego limitu liczby terminów, ale wyższe wartości obniżają wydajność, zwłaszcza jeśli pole aspektowe zawiera dużą liczbę unikatowych terminów. Na przykład "facet=category,count:5" pobiera pięć pierwszych kategorii w wynikach aspektów. Jeśli parametr count jest mniejszy niż liczba unikatowych terminów, wyniki mogą nie być dokładne. Jest to spowodowane sposobem dystrybucji zapytań aspektowych między fragmentami. Aby uzyskać dokładną liczbę wszystkich fragmentów, możesz ustawić wartość zliczaną na zero lub wartość większą lub równą liczbie unikatowych wartości w polu aspektowalnym. Kompromis jest zwiększony opóźnienia. "sort" można ustawić na "count", "-count", "value", "-value". Użyj liczby, aby posortować malejąco według liczby. Użyj -count, aby posortować rosnąco według liczby. Użyj wartości, aby sortować rosnąco według wartości. Użyj -value, aby sortować malejąco według wartości (na przykład "facet=category,count:3,sort:count" pobiera trzy pierwsze kategorie w wynikach aspektu w kolejności malejącej według liczby dokumentów o każdej nazwie miasta). Jeśli trzy najlepsze kategorie to Budget, Motel i Luxury, a Budget ma pięć trafień, Motel ma sześć, a Luksus ma cztery, to wiadra są w kolejności Motel, Budget, Luxury. Dla -value, "facet=rating,sort:-value" tworzy zasobniki dla wszystkich możliwych klasyfikacji, w kolejności malejącej według wartości (na przykład jeśli oceny są z zakresu od 1 do 5, zasobniki są uporządkowane 5, 4, 3, 2, 1, niezależnie od liczby dokumentów pasujących do każdej klasyfikacji). Wartość "values" może być ustawiona na wartości liczbowe rozdzielane potokiem lub Edm.DateTimeOffset, określając dynamiczny zestaw wartości wpisu aspektu (na przykład "facet=baseRate,values:10 \| 20" produkuje trzy zasobniki: jeden dla stawki bazowej 0 do 10, jeden dla 10 do 10, ale nie łącznie z 20, a jeden dla 20 i nowszych). Ciąg "facet=lastRenovationDate,values:2010-02-01T00:00:00Z" tworzy dwa zasobniki: jeden dla hoteli odnowionych przed lutym 2010 r., a drugi dla hoteli odnowionych 1 lutego 2010 r. lub nowszych. Wartości muszą być wymienione w kolejności sekwencyjnej, rosnącej, aby uzyskać oczekiwane wyniki. "interwał" to interwał liczby całkowitej większy niż 0 dla liczb lub minut, godziny, dnia, tygodnia, miesiąca, kwartału, roku dla wartości daty i godziny. Na przykład "facet=baseRate,interval:100" tworzy zasobniki na podstawie zakresów szybkości bazowej o rozmiarze 100. Jeśli stawki bazowe wynoszą od 60 DO 600 USD, będą zasobniki dla 0-100, 100-200, 200-300, 300-400, 400-500 i 500-600. Ciąg "facet=lastRenovationDate,interval:year" tworzy jeden wiadro dla każdego roku, kiedy hotele zostały odnowione. "timeoffset" można ustawić na ([+-]hh:mm, [+-]hhmm lub [+-]hhh). Jeśli jest używany, parametr timeoffset musi być połączony z opcją interwału i tylko wtedy, gdy jest stosowany do pola typu Edm.DateTimeOffset. Wartość określa przesunięcie czasu UTC na konto w ustawianiu granic czasu. Na przykład: "facet=lastRenovationDate,interval:day,timeoffset:-01:00" używa granicy dnia, która rozpoczyna się o godzinie 01:00:00 UTC (północ w docelowej strefie czasowej). liczba i sortowanie można łączyć w tej samej specyfikacji aspektu, ale nie można ich łączyć z interwałami ani wartościami, a interwały i wartości nie mogą być łączone razem. Aspekty interwałów w godzinie daty są obliczane na podstawie godziny UTC, jeśli nie określono przesunięcia czasu. Na przykład: dla "facet=lastRenovationDate,interval:day", granica dnia rozpoczyna się o 00:00:00 UTC.
featuresMode (wersja zapoznawcza)	boolean	Opcjonalny. Prawidłowe wartości to "włączone" i "wyłączone". Wartość domyślna to "wyłączone". Wartość określająca, czy wyniki powinny zawierać funkcje wyników zapytania, używane do obliczania wyniku istotności dokumentu w odniesieniu do zapytania, takiego jak podobieństwo pola. Użyj opcji "enabled", aby uwidocznić więcej funkcji wyników zapytania: na wynik podobieństwa pola, częstotliwość terminów pola i liczbę unikatowych tokenów dopasowanych. Aby uzyskać więcej informacji, zobacz Podobieństwo i ocenianie.
$filter	ciąg	Opcjonalny. Wyrażenie wyszukiwania strukturalnego w standardowej składni OData. Filtrowalne pola można używać tylko w filtrze. Po wywołaniu metody POST ten parametr nosi nazwę filter zamiast $filter. Zobacz Składnia wyrażeń OData dla usługi Azure AI Search , aby uzyskać szczegółowe informacje na temat podzestawu gramatyki wyrażeń OData obsługiwanej przez usługę Azure AI Search.
Wyróżnij	ciąg	Opcjonalny. Zestaw nazw pól rozdzielanych przecinkami używanych do wyróżniania trafień. Do wyróżniania trafień można używać tylko pól z możliwością wyszukiwania. Domyślnie usługa Azure AI Search zwraca maksymalnie pięć wyróżnień na pole. Limit można skonfigurować dla każdego pola, dołączając ciąg "-<max # wyróżnień>" po nazwie pola. Na przykład wyrażenie "highlight=title-3,description-10" zwraca maksymalnie trzy wyróżnione trafienia z pola tytułu i maksymalnie 10 trafień z pola opisu. Maksymalna liczba wyróżnień musi być liczbą całkowitą z zakresu od 1 do 1000 włącznie.
highlightPostTag	ciąg	Opcjonalny. Wartość domyślna to `"</em>"`. Tag ciągu dołączany do wyróżnionego terminu. Należy ustawić element z funkcją highlightPreTag. Zastrzeżone znaki w adresie URL muszą być zakodowane procentowo (na przykład %23 zamiast #).
highlightPreTag	ciąg	Opcjonalny. Wartość domyślna to `"</em>"`. Tag ciągu, który poprzedza wyróżniony termin. Należy ustawić element z elementem highlightPostTag. Zastrzeżone znaki w adresie URL muszą być zakodowane procentowo (na przykład %23 zamiast #).
minimumCoverage	liczba całkowita	Opcjonalny. Prawidłowe wartości to liczba z zakresu od 0 do 100 wskazująca procent indeksu, który musi być dostępny do obsługi zapytania, zanim będzie można je zgłosić jako powodzenie. Wartość domyślna to "100". Zasięg o sto procent oznacza, że wszystkie fragmenty odpowiedziały na żądanie (ani problemy z kondycją usługi, ani działania konserwacyjne nie zmniejszyły pokrycia). W obszarze domyślnego ustawienia mniejsze niż pełne pokrycie zwraca kod stanu HTTP 503. Obniżenie minimumCoverage może być przydatne, jeśli występują błędy 503 i chcesz zwiększyć prawdopodobieństwo powodzenia zapytania, zwłaszcza w przypadku usług skonfigurowanych dla jednej repliki. Jeśli ustawisz minimalną wartośćCoverage i wyszukiwanie zakończy się powodzeniem, zwraca wartość HTTP 200 i uwzględnij @search.coverage wartość w odpowiedzi wskazującą wartość procentową indeksu uwzględnionego w zapytaniu. W tym scenariuszu nie wszystkie pasujące dokumenty mają gwarancję obecności w wynikach wyszukiwania, ale jeśli dostępność wyszukiwania jest ważniejsza niż kompletność, ograniczenie pokrycia może być opłacalną strategią ograniczania ryzyka.
$orderby	ciąg	Opcjonalny. Lista wyrażeń rozdzielanych przecinkami do sortowania wyników według. W przypadku wywołania metody POST ten parametr ma nazwę orderby zamiast $orderby. Każde wyrażenie może być nazwą pola lub wywołaniem funkcji geo.distance(). Po każdym wyrażeniu może występować wyrażenie "asc", aby wskazać rosnąco, i "desc", aby wskazać malejąco. Jeśli w polu sortowania znajdują się wartości null, wartości null są wyświetlane jako pierwsze w kolejności rosnącej i ostatnio w kolejności malejącej. Wartość domyślna to kolejność rosnąca. Więzi zostaną przerwane przez wyniki dopasowań dokumentów. Jeśli nie określono $orderby, domyślna kolejność sortowania jest malejąco według wyniku dopasowania dokumentu. Istnieje limit 32 klauzul dla $orderby.
queryLanguage (wersja zapoznawcza)	ciąg	Opcjonalny. Prawidłowe wartości są obsługiwanym językiem. Wartość domyślna to "en-us". Ten parametr musi być ustawiony, jeśli używasz speller=lexicon lub queryType=semantic. Język określony w queryLanguage jest używany zarówno do sprawdzania pisowni, jak i przez semantyczne modele, które ponownie korektować wyniki i wyodrębniać podpis lub odpowiedź. Biblioteki używane na potrzeby queryLanguage są niezależne od innych atrybutów pól opartych na ustawieniach regionalnych, takich jak analizatory języka używane do indeksowania i wyszukiwania pełnotekstowego.
queryType	ciąg	Opcjonalny. Prawidłowe wartości to "simple", "full" lub "semantic" (wersja zapoznawcza). Wartość domyślna to "simple". Ta wartość jest ignorowana w przypadku wyszukiwania wektorowego, ale dotyczy wyszukiwania tekstu w scenariuszach hybrydowych. Wyrażenie "simple" interpretuje ciągi zapytań przy użyciu prostej składni zapytania , która umożliwia używanie symboli, takich jak `+`, ``i `""`. Zapytania są domyślnie oceniane we wszystkich polach z możliwością wyszukiwania (lub polach wskazanych w polach wyszukiwania) w każdym dokumencie. Wyrażenie "full" interpretuje ciągi zapytań przy użyciu pełnej składni zapytania Lucene , która umożliwia wyszukiwanie specyficzne dla pola i ważone. Wyszukiwanie zakresu w języku zapytań Lucene nie jest obsługiwane na rzecz $filter, która oferuje podobne funkcje. semantyka" zwiększa precyzję wyników wyszukiwania przez ponowne rozsyłanie 50 pierwszych dopasowań przy użyciu modelu klasyfikacji wytrenowanego na korpusie Bing dla zapytań wyrażonych w języku naturalnym, a nie słów kluczowych. Jeśli ustawisz typ zapytania na semantyczny, musisz również ustawić właściwość queryLanguage i semanticConfiguration. Opcjonalnie możesz ustawić odpowiedzi, jeśli chcesz również zwrócić 3 odpowiedzi, jeśli dane wejściowe zapytania zostały sformułowane w języku naturalnym ("co to jest ...*), i opcjonalnie możesz ustawić podpisy, aby wyodrębnić kluczowe fragmenty z dokumentów o najwyższej klasyfikacji.
scoringParameter	ciąg	Opcjonalny. Wskazuje wartości dla każdego parametru zdefiniowanego w funkcji oceniania (na przykład referencePointParameter) przy użyciu formatu "name-value1,value2,..." W przypadku wywołania metody POST ten parametr ma nazwę scoringParameters zamiast ocenianiaParameter. Ponadto należy określić ją jako tablicę ciągów w formacie JSON, w której każdy ciąg jest oddzielną parą name-values. W przypadku profilów oceniania, które zawierają funkcję, oddziel funkcję od listy danych wejściowych znakiem `-` . Na przykład funkcja o nazwie `"mylocation"` to "&scoringParameter=mylocation--122.2,44.8". Pierwsza kreska oddziela nazwę funkcji od listy wartości, a druga kreska jest częścią pierwszej wartości (długość geograficzna w tym przykładzie). W przypadku parametrów oceniania, takich jak pod kątem zwiększania tagów, które mogą zawierać przecinki, można użyć dowolnych takich wartości na liście przy użyciu pojedynczych cudzysłowów. Jeśli same wartości zawierają apostrofy, możesz je uniknąć, podwajając. Załóżmy, że masz parametr zwiększający tag o nazwie `"mytag"` i chcesz zwiększyć wartości tagów "Hello, O'Brien" i "Smith", opcja ciągu zapytania to "&scoringParameter=mytag-'Hello, O''Brien',Smith". Cudzysłowy są wymagane tylko dla wartości zawierających przecinki.
scoringProfile	ciąg	Opcjonalny. Nazwa profilu oceniania w celu oceny wyników dopasowania pasujących dokumentów w celu sortowania wyników.
scoringStatistics	ciąg	Opcjonalny. Prawidłowe wartości to "local" lub "global". Wartość domyślna to "local". Określ, czy mają być obliczane statystyki oceniania, takie jak częstotliwość dokumentu, globalnie (we wszystkich fragmentach) w celu uzyskania bardziej spójnego oceniania lub lokalnie (na bieżącym fragmentze) w celu uzyskania mniejszego opóźnienia. Zobacz Statystyki oceniania w usłudze Azure AI Search. Statystyki oceniania będą zawsze obliczane lokalnie dla terminów korzystających z wyszukiwania rozmytego ('~').
search	ciąg	Opcjonalny. Tekst do wyszukania. Ta wartość jest ignorowana w przypadku wyszukiwania wektorowego, ale dotyczy wyszukiwania tekstu w scenariuszach hybrydowych. W interfejsach API REST wszystkie pola z możliwością wyszukiwania są domyślnie przeszukiwane, chyba że określono pola wyszukiwania. W indeksie tekst w polu z możliwością wyszukiwania jest tokenizowany, więc wiele terminów może być rozdzielonych białym znakiem (na przykład : "search=hello world"). Aby dopasować dowolny termin, użyj ( `` może to być przydatne w przypadku zapytań filtru logicznego). Pominięcie tego parametru ma taki sam efekt jak ustawienie go na ``. Zobacz Prosta składnia zapytań , aby uzyskać szczegółowe informacje na temat składni wyszukiwania. Wyniki mogą czasami być zaskakujące podczas wykonywania zapytań dotyczących pól z możliwością wyszukiwania. Tokenizator zawiera logikę do obsługi przypadków typowych dla tekstu w języku angielskim, takich jak apostrofy, przecinki w liczbach itd. Na przykład wyrażenie "search=123,456" będzie zgodne z pojedynczym terminem "123 456", a nie pojedynczymi terminami "123" i "456", ponieważ przecinki są używane jako separatory tysięcy w przypadku dużych liczb w języku angielskim. Z tego powodu zalecamy używanie białych znaków, a nie interpunkcji, aby oddzielić terminy w parametrze wyszukiwania.
searchMode	ciąg	Opcjonalny. Prawidłowe wartości to "any" lub "all" Defaults to "any". Określa, czy dowolne lub wszystkie terminy wyszukiwania muszą być zgodne, aby zliczyć dokument jako dopasowanie.
pola wyszukiwania	ciąg	Opcjonalny. Lista nazw pól rozdzielanych przecinkami do wyszukiwania określonego tekstu. Pola docelowe muszą być oznaczone jako możliwe do wyszukiwania w schemacie indeksu i muszą mieć typ `Edm.String`, `Edm.ComplexType`lub `Collection(Edm.String)`.
$select	ciąg	Opcjonalny. Lista pól rozdzielanych przecinkami do uwzględnienia w zestawie wyników. W tej klauzuli można uwzględnić tylko pola oznaczone jako możliwe do pobrania. Jeśli nieokreślone lub ustawione na `*`wartość , wszystkie pola oznaczone jako możliwe do pobrania w schemacie są uwzględniane w projekcji. W przypadku wywołania metody POST ten parametr ma nazwę select zamiast $select.
semanticConfiguration (wersja zapoznawcza)	ciąg	Opcjonalny. Wymagane, jeśli queryType="semantic". Nazwa konfiguracji semantycznej, która zawiera listę pól, które powinny być używane do semantycznego klasyfikowania, podpisów, wyróżniania i odpowiedzi. Aby uzyskać więcej informacji, zobacz Tworzenie zapytania semantycznego.
Sessionid	ciąg	Opcjonalny. Użycie identyfikatora sessionId pomaga zwiększyć spójność oceny istotności dla usług wyszukiwania z wieloma replikami. W konfiguracjach z wieloma replikami mogą występować niewielkie różnice między ocenami istotności poszczególnych dokumentów dla tego samego zapytania. Po podaniu identyfikatora sesji usługa dokłada wszelkich starań, aby skierować dane żądanie do tej samej repliki dla tej sesji. Należy uważać, że wielokrotne użycie tych samych wartości identyfikatora sesji może zakłócać równoważenie obciążenia żądań między replikami i niekorzystnie wpływać na wydajność usługi wyszukiwania. Wartość używana jako sessionId nie może rozpoczynać się od znaku "_". Jeśli usługa nie ma żadnych replik, ten parametr nie ma wpływu na wydajność ani spójność oceny.
$skip	liczba całkowita	Opcjonalny. Liczba wyników wyszukiwania do pominięcia. W przypadku wywołania metody POST ten parametr ma nazwę skip zamiast $skip. Ta wartość nie może być większa niż 100 000. Jeśli musisz skanować dokumenty w sekwencji, ale nie można użyć $skip z powodu tego ograniczenia, rozważ użycie $orderby w polu, które ma unikatowe wartości dla każdego dokumentu w indeksie (na przykład klucza dokumentu) i $filter z zapytaniem zakresu.
speller (wersja zapoznawcza)	String	Opcjonalny. Prawidłowe wartości to "none" i "lexicon". Wartość domyślna to "none". Popraw kompletność przez poprawianie pisowni poszczególnych terminów zapytania wyszukiwania. Można go używać w prostych, pełnych i semantycznych typach zapytań. Jeśli jest używany, parametr sprawdzania pisowni wymaga elementu queryLanguage. Aby uzyskać więcej informacji i przykłady, zobacz Dodawanie sprawdzania pisowni do zapytań.
$top	liczba całkowita	Opcjonalny. Liczba wyników wyszukiwania do pobrania. Ta wartość domyślna to 50. W przypadku wywołania metody POST ten parametr ma nazwę top zamiast $top. Jeśli określisz wartość większą niż 1000 i istnieje więcej niż 1000 wyników, w poniższym przykładzie zostanie zwróconych tylko pierwszych 1000 wyników wraz z linkiem do następnej strony wyników (zobacz "@odata.nextLink". Usługa Azure AI Search używa stronicowania po stronie serwera , aby zapobiec pobieraniu zbyt wielu dokumentów jednocześnie przez zapytania. Domyślny rozmiar strony to 50, a maksymalny rozmiar strony to 1000. Oznacza to, że domyślnie wyszukiwanie dokumentów zwraca co najwyżej 50 wyników, jeśli nie określisz $top. Jeśli istnieje więcej niż 50 wyników, odpowiedź zawiera informacje, aby pobrać następną stronę z maksymalnie 50 wyników (zobacz "@odata.nextLink" i "@search.nextPageParameters" w poniższych przykładach . Podobnie, jeśli określisz wartość większą niż 1000 dla $top i istnieje więcej niż 1000 wyników, zwracanych jest tylko pierwszych 1000 wyników wraz z informacjami umożliwiającymi pobranie następnej strony maksymalnie 1000 wyników.
wektory (wersja zapoznawcza)	array	Opcjonalny. Typ obiektu w tablicy jest zapytaniem wektorowym. Parametry zapytania dla zapytań wektorowych. "value" to wektorowa reprezentacja zapytania wyszukiwania. Ta reprezentacja musi zostać utworzona zewnętrznie. Usługa Azure AI Search nie tworzy osadzeń. "k" to liczba całkowita określająca liczbę najbliższych sąsiadów, które mają być zwracane jako pierwsze trafienia. Domyślna wartość wynosi 50. Wartość minimalna to 1, a wartość maksymalna to 10 000. "fields" to rozdzielane przecinkami nazwy pól listy zawierające dane wektorowe. Na liście "pola" można uwzględnić tylko pola typu `Collection(Edm.Single)` .

Reakcja

Kod stanu: 200 OK jest zwracany dla pomyślnej odpowiedzi. W tym artykule znajdują się dwie przykładowe odpowiedzi— po jednym dla semantycznego wyszukiwania i funkcjiMode.

Przykładowa odpowiedź dla zapytania semantycznego

W pierwszym przykładzie przedstawiono pełną odpowiedź dla najwyższego wyniku zapytania semantycznego "jak utworzyć chmury".

Wyrażenie "@search.answers" pojawia się po określeniu parametru odpowiedzi, a gdy zapytanie i pola docelowe w indeksie zawierają zawartość, którą można rozpoznać jako odpowiedź. Tablica @search.answers zawierająca klucz, tekst i wyróżnienia. Wynik jest wskaźnikiem siły odpowiedzi.
"value" to treść odpowiedzi. Element @search.rerankerScore jest przypisywany przez algorytm klasyfikacji semantycznej i służy do klasyfikowania wyników (@search.score pochodzi z algorytmu podobieństwa BM25 używanego podczas oceniania początkowych wyników). Podpisy zawierają zwykły tekst i wyróżnione wersje. Ten przykład został utworzony przy użyciu umiejętności rozpoznawania OCR i rozpoznawania jednostek. Pola wyodrębnionej i scalonej zawartości są uwzględniane w odpowiedzi.

{
    "@search.answers": [
        {
            "key": "aHR0cHM6Ly9oZWlkaXN0YmxvYnN0b3JhZ2UuYmxvYi5jb3JlLndpbmRvd3MubmV0L25hc2EtZWJvb2stMS01MC9wYWdlLTQ1LnBkZg2",
            "text": "Sunlight heats the land all day, warming that moist air and causing it to rise high into the atmosphere until it cools and condenses into water droplets. Clouds generally form where air is ascending (over land in this case),   but not where it is descending (over the river).",
            "highlights": "Sunlight heats the land all day, warming that moist air and causing it to rise high into the   atmosphere until it cools and condenses into water droplets. Clouds generally form<em> where air is ascending</em> (over land in this case),   but not where it is<em> descending</em> (over the river).",
            "score": 0.94639826
        }
    ],
    "value": [
        {
            "@search.score": 0.5479723,
            "@search.rerankerScore": 1.0321671911515296,
            "@search.captions": [
                {
                    "text": "Like all clouds, it forms when the air reaches its dew point—the temperature at which an air mass is cool enough for its water vapor to condense into liquid droplets. This false-color image shows valley fog, which is common in the Pacific Northwest of North America.",
                    "highlights": "Like all<em> clouds</em>, it<em> forms</em> when the air reaches its dew point—the temperature at    which an air mass is cool enough for its water vapor to condense into liquid droplets. This false-color image shows valley<em> fog</em>, which is common in the Pacific Northwest of North America."
                }
            ],
            "content": "\nA\nT\n\nM\nO\n\nS\nP\n\nH\nE\n\nR\nE\n\nE\nA\n\nR\nT\n\nH\n\n34\n\nValley Fog\nCanada\n\nFog is essentially a cloud lying on the ground. Like all clouds, it forms when the air reaches its dew point—the temperature at  \n\nwhich an air mass is cool enough for its water vapor to condense into liquid droplets.\n\nThis false-color image shows valley fog, which is common in the Pacific Northwest of North America. On clear winter nights, the \n\nground and overlying air cool off rapidly, especially at high elevations. Cold air is denser than warm air, and it sinks down into the \n\nvalleys. The moist air in the valleys gets chilled to its dew point, and fog forms. If undisturbed by winds, such fog may persist for \n\ndays. The Terra satellite captured this image of foggy valleys northeast of Vancouver in February 2010.\n\n\n",
            "metadata_storage_path": "aHR0cHM6Ly9oZWlkaXN0YmxvYnN0b3JhZ2UuYmxvYi5jb3JlLndpbmRvd3MubmV0L25hc2EtZWJvb2stMS01MC9wYWdlLTQxLnBkZg2",
            "people": [],
            "locations": [
                "Pacific Northwest",
                "North America",
                "Vancouver"
            ],
            "merged_content": "\nA\nT\n\nM\nO\n\nS\nP\n\nH\nE\n\nR\nE\n\nE\nA\n\nR\nT\n\nH\n\n34\n\nValley Fog\nCanada\n\nFog is essentially a cloud lying on the ground. Like all clouds, it forms when the air reaches its dew point—the temperature at  \n\nwhich an air mass is cool enough for its water vapor to condense into liquid droplets.\n\nThis false-color image shows valley fog, which is common in the Pacific Northwest of North America. On clear winter nights, the \n\nground and overlying air cool off rapidly, especially at high elevations. Cold air is denser than warm air, and it sinks down into the \n\nvalleys. The moist air in the valleys gets chilled to its dew point, and fog forms. If undisturbed by winds, such fog may persist for \n\ndays. The Terra satellite captured this image of foggy valleys northeast of Vancouver in February 2010.\n\n\n",
            "text": [],
            "layoutText": []
        }
    ]
}

Przykładowa odpowiedź dla funkcjiMode

W tym przykładzie przedstawiono dane wyjściowe "@search.features" z zapytania zawierającego funkcjęMode.

  {
    "@odata.count": # (if $count=true was provided in the query),
    "@search.coverage": # (if minimumCoverage was provided in the query),
    "@search.facets": { (if faceting was specified in the query)
      "facet_field": [
        {
          "value": facet_entry_value (for non-range facets),
          "from": facet_entry_value (for range facets),
          "to": facet_entry_value (for range facets),
          "count": number_of_documents
        }
      ],
      ...
    },
    "@search.nextPageParameters": { (request body to fetch the next page of results if not all results could be returned in this response and Search was called with POST)
      "count": ... (value from request body if present),
      "facets": ... (value from request body if present),
      "featuresMode" : ... (value from request body if present),
      "filter": ... (value from request body if present),
      "highlight": ... (value from request body if present),
      "highlightPreTag": ... (value from request body if present),
      "highlightPostTag": ... (value from request body if present),
      "minimumCoverage": ... (value from request body if present),
      "orderby": ... (value from request body if present),
      "scoringParameters": ... (value from request body if present),
      "scoringProfile": ... (value from request body if present),
      "scoringStatistics": ... (value from request body if present),
      "search": ... (value from request body if present),
      "searchFields": ... (value from request body if present),
      "searchMode": ... (value from request body if present),
      "select": ... (value from request body if present),
      "sessionId" : ... (value from request body if present),
      "skip": ... (page size plus value from request body if present),
      "top": ... (value from request body if present minus page size),
    },
    "value": [
      {
        "@search.score": document_score (if a text query was provided),
        "@search.highlights": {
          field_name: [ subset of text, ... ],
          ...
        },
        "@search.features": {
          "field_name": {
            "uniqueTokenMatches": feature_score,
            "similarityScore": feature_score,
            "termFrequency": feature_score,
          },
          ...
        },
        key_field_name: document_key,
        field_name: field_value (retrievable fields or specified projection),
        ...
      },
      ...
    ],
    "@odata.nextLink": (URL to fetch the next page of results if not all results could be returned in this response; Applies to both GET and POST)
  }

Przykłady

Więcej przykładów można znaleźć w artykule OData Expression Syntax for Azure AI Search (Składnia wyrażeń OData dla usługi Azure AI Search).

Przykład: proste wyszukiwanie

Znajdowanie dokumentów w indeksie przy użyciu prostej składni zapytań. To zapytanie zwraca hotele, w których pola z możliwością wyszukiwania zawierają terminy "comfort" i "location", ale nie "motel":

Get /indexes/hotels/docs?search=comfort +location –motel&searchMode=all&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "comfort +location -motel",  
      "searchMode": "all"  
    }

Porada

Użycie searchMode=all przesłonięć wartość domyślną searchMode=any, zapewniając, że -motel oznacza to "AND NOT" zamiast "OR NOT". Bez searchMode=allpolecenia uzyskujesz wartość "OR NOT", która rozszerza się, a nie ogranicza wyników wyszukiwania, i może to być sprzeczne z intuicyjną dla niektórych użytkowników.

Przykład: pełne wyszukiwanie Lucene

Znajdowanie dokumentów w indeksie przy użyciu składni zapytań Lucene (zobacz Składnia zapytań Lucene w usłudze Azure AI Search). To zapytanie zwraca hotele, w których pole kategorii zawiera termin "budget" i wszystkie pola z możliwością wyszukiwania zawierające frazę "ostatnio odnowiony". Dokumenty zawierające frazę "ostatnio odnowiony" są klasyfikowane wyżej w wyniku terminu zwiększenie wartości (3)

GET /indexes/hotels/docs?search=Category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2021-04-30-Preview&querytype=full`

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}

Przykład: wyszukiwanie semantyczne

Wywołaj semantyczny model klasyfikacji z odpowiedziami, napisami i wyróżnioną zawartością. Odpowiedź na to zapytanie można znaleźć w poprzedniej sekcji.

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
{
  "search": "how do clouds form",
  "queryType": "semantic",
  "semanticConfiguration": "my-semantic-config",
  "queryLanguage": "en-us",
  "answers": "extractive",
  "captions": "extractive",
  "count": "true"
}

Przykład: wyszukiwanie wektorowe

W przypadku indeksu, który ma pola typu Collection(Edm.Single) i konfigurację wektora, można określić parametry zapytania wektorowego. Parametry zapytania wektorowego obejmują pola wektorowe, które są w zakresie zapytania, liczba "k" pierwszych trafień do zwrócenia i wektorowa reprezentacja danych wejściowych zapytania.

Dodanie parametru "select" jest przydatne, jeśli indeks zawiera pola tekstowe. Dopasowywanie i istotność są oparte na wektorach, ale pola zawierające zawartość czytelną dla człowieka są bardziej przydatne dla kogoś czytającego wyniki. Alternatywnie możesz napisać kod, który konwertuje dane wektorowe w wynikach wyszukiwania na tekst.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version={{api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "search": (this parameter is ignored in vector search),
    "vectors": [{
        "value": [
            -0.009154141,
            0.018708462,
            . . . 
            -0.02178128,
            -0.00086512347
        ],
        "fields": "contentVector",
        "k": 5
    }],
    "select": "title, content, category"
}

Przykład: orderby

Przeszukaj indeks i zwróć wyniki posortowane według daty w kolejności malejącej.

GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "*",  
      "orderby": "LastRenovationDate desc"
    }

Przykład: filtrowanie przy użyciu wyrażenia OData

Pobieranie dokumentów pasujących do określonego wyrażenia filtru:

GET /indexes/hotels/docs?$filter=(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "filter": "(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'"  
    }

Przykład: wyszukiwanie aspektowe

W wyszukiwaniu aspektowym wyszukaj indeks i pobierz aspekty pod kątem kategorii, klasyfikacji, tagów, a także elementów o wartości baseRate w określonych zakresach.

GET /indexes/hotels/docs?search=*&facet=Category&facet=Rating&facet=Tags&facet=Rooms/BaseRate,values:80|150|220&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "test",  
      "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ]  
    }

Zwróć uwagę, że ostatni aspekt znajduje się w polu podrzędnym. Aspekty zliczają dokument nadrzędny (Hotele) i nie pośrednie dokumenty podrzędne (Pokoje), więc odpowiedź określi liczbę hoteli, które mają jakiekolwiek pokoje w każdym zasobniku cen.

Przykład: Zawężanie zapytania aspektowego

Używając filtru, zawęź poprzedni wynik zapytania aspektowego po wybraniu przez użytkownika pozycji Ocena 3 i kategorii "Motel".

GET /indexes/hotels/docs?search=*&facet=tags&facet=Rooms/BaseRate,values:80|150|220&$filter=Rating eq 3 and Category eq 'Motel'&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview 
    {  
      "search": "test",  
      "facets": [ "tags", "Rooms/BaseRate,values:80|150|220" ],  
      "filter": "Rating eq 3 and Category eq 'Motel'"  
    }

Przykład: wyszukiwanie aspektowe z limitami w każdej kategorii

W wyszukiwaniu aspektowym ustaw górny limit unikatowych terminów zwracanych w zapytaniu. Wartość domyślna to 10, ale można zwiększyć lub zmniejszyć tę wartość przy użyciu parametru count atrybutu facet. Ten przykład zwraca aspekty dla miasta, ograniczone do 5.

GET /indexes/hotels/docs?search=*&facet=Address/City,count:5&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }

Przykład: wyszukiwanie w polu

Wyszukaj indeks w określonych polach (na przykład pole języka)

GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hôtel",  
      "searchFields": "Description_fr"
    }

Przeszukaj indeks w wielu polach. Można na przykład przechowywać pola z możliwością wyszukiwania i wykonywać zapytania w wielu językach, a wszystko to w tym samym indeksie. Jeśli opisy angielskie i francuskie współistnieją w tym samym dokumencie, możesz zwrócić dowolne lub wszystkie w wynikach zapytania:

GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }

Jednocześnie można wykonywać zapytania tylko o jeden indeks. Nie twórz wielu indeksów dla każdego języka, chyba że planujesz wykonać zapytanie pojedynczo.

Przykład: stronicowanie wyników

Pobierz pierwszą stronę elementów (rozmiar strony to 10):

GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "*",  
      "skip": 0,  
      "top": 10  
    }

Pobierz drugą stronę elementów (rozmiar strony to 10):

GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "*",  
      "skip": 10,  
      "top": 10  
    }

Przykład: ograniczanie pól w zestawie wyników

Pobieranie określonego zestawu pól:

GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "*",  
      "select": "HotelName, Description"
    }

Przykład: wyróżnianie trafień w wynikach

Przeszukaj indeks i zwróć fragmenty z wyróżnionymi trafieniami:

GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "something",  
      "highlight": "Description"  
    }

Przykład: Wyszukiwanie geoprzestrzenne

Przeszukaj indeks i zwróć dokumenty posortowane od bliżej do dalszej lokalizacji referencyjnej:

GET /indexes/hotels/docs?search=something&$orderby=geo.distance(Location, geography'POINT(-122.12315 47.88121)')&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "something",  
      "orderby": "geo.distance(Location, geography'POINT(-122.12315 47.88121)')"
    }

Przykład: "znajdź według mnie" (zwiększ znaczenie pobliskich lokalizacji)

Przeszukaj indeks przy założeniu, że istnieje profil oceniania o nazwie "geo" z dwiema funkcjami oceniania odległości, jeden definiujący parametr o nazwie "currentLocation" i jeden definiujący parametr o nazwie "lastLocation". W poniższym przykładzie element "currentLocation" ma ogranicznik pojedynczej kreski (-). Następuje po niej współrzędne długości geograficznej i szerokości geograficznej, gdzie długość geograficzna jest wartością ujemną.

GET /indexes/hotels/docs?search=something&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&scoringParameter=lastLocation--121.499,44.2113&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "something",  
      "scoringProfile": "geo",  
      "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
    }

Przykład: wykonywanie zapytań względem pełnego indeksu zamiast fragmentów

Znajdź dokumenty w indeksie, a jednocześnie faworyzuje spójne ocenianie w przypadku mniejszych opóźnień. To zapytanie oblicza częstotliwości dokumentów w całym indeksie i dokłada wszelkich starań, aby kierowania tej samej repliki dla wszystkich zapytań w ramach tej samej "sesji", co pomaga wygenerować stabilny i powtarzalny ranking.

GET /indexes/hotels/docs?search=hotel&sessionId=mySessionId&scoringStatistics=global&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }

Przykład: statystyka oceniania (featuresMode)

Znajdź dokumenty w indeksie i zwróć listę funkcji pobierania informacji dla każdego wyniku opisującego ocenianie między dopasowanym dokumentem a zapytaniem. Zapytanie oblicza również częstotliwości dokumentów w całym indeksie, aby wygenerować bardziej spójne ocenianie.

GET /indexes/hotels/docs?search=hotel&featuresMode=enabled&scoringStatistics=global&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hotel",  
      "featuresMode": "enabled",
      "scoringStatistics" :"global"
    }

Przykład odpowiedzi, która zawiera search.features , wygląda podobnie do następującej:

    "@search.score": 0.91875637,
    "@search.features": {
        "Description": {
            "uniqueTokenMatches": 1,
            "similarityScore": 0.2917966,
            "termFrequency": 2
        },
        "HotelName": {
            "uniqueTokenMatches": 1,
            "similarityScore": 0.44458693,
            "termFrequency": 1
        }
      . . .

Definicje

Ta sekcja zawiera szczegółowe informacje o parametrach, które są zbyt złożone do omówienia w tabeli głównej.

Link	Opis
queryLanguage	Lista obsługiwanych języków sprawdzania pisowni i wyszukiwania semantycznego.

queryLanguage

Prawidłowe wartości parametru queryLanguage są podane w poniższej tabeli w kolumnie "queryLanguage" i nie są uwzględniane wielkości liter. Wartością domyślną parametru jako całości jest "en-us". W każdym języku istnieje domyślny wariant dla każdego dwuznakowego kodu języka. Jeśli na przykład określisz wartość "es", domyślnie jest używana wartość "es-us". Parametr queryLanguage jest wymagany dla żądania zapytania zawierającego ciąg "queryType=semantic" lub "speller=lexicon". Istnieje tylko jedna wartość queryLanguage dla całego żądania i ta wartość będzie używana do klasyfikacji semantycznej, podpisów, odpowiedzi i pisowni (nie ma zastąpienia dla poszczególnych funkcji).

Obecnie obsługa języka różni się w zależności od funkcji. Tylko angielski, hiszpański, francuski i niemiecki są obsługiwane dla pełnego zestawu funkcji, ale zwróć uwagę, że sprawdzanie pisowni implementuje mniej wariantów.

Jeśli określisz kod języka, który nie jest obsługiwany przez daną funkcję, taką jak EN-GB z pisownią, usługa zwraca protokół HTTP 400.

Aby uzyskać więcej informacji na temat korzystania z każdej funkcji, zobacz Włączanie semantycznego klasyfikowania i podpisów, Zwracanie semantycznej odpowiedzi i Dodawanie sprawdzania pisowni do zapytań.

Oznaczenie "(wersja zapoznawcza)" wskazuje, że testowanie poprawności we wszystkich funkcjach (semantyczne klasyfikacje, podpisy, odpowiedzi i sprawdzanie pisowni) jest trwające lub oczekujące. Zachęcamy do użycia wszystkich wariantów językowych w poniższej tabeli, ale zalecamy więcej testów języków w wersji zapoznawczej, aby upewnić się, że wyniki są prawidłowe dla Twojej zawartości. Języki z znacznikiem wyboru i bez oznaczenia podglądu zostały zweryfikowane przy użyciu równoważnych zestawów danych, z wymiernym wzrostem istotności.

Język	queryLanguage	Semantyczny ranger i podpisy	Semantyczna odpowiedź	Speller
Angielski [`en`]	`en, en-US`(wartość domyślna), `en-GB`, `en-IN`, , `en-CAen-AU`	✔️	✔️	✔️ (`en, en-US`)
Francuski [`fr`]	`fr`, `fr-FR` (wartość domyślna), `fr-CA`	✔️	✔️	✔️ (`fr, fr-FR`)
Niemiecki [`de`]	`de, de-DE` (domyślne)	✔️	✔️	✔️ (`de, de-DE`)
Hiszpański [`es`]	`es, es-ES` (wartość domyślna), `es-MX`	✔️	✔️	✔️ (`es, es-ES`)
Włoski [`it`]	`it, it-IT` (domyślne)	✔️	✔️
Japoński [`ja`]	`ja, ja-JP` (domyślne)	✔️	✔️ (wersja zapoznawcza)
Chiński [`zh`]	`zh, zh-CN` (wartość domyślna), `zh-TW`	✔️	✔️ (wersja zapoznawcza)
Portugalski [`pt`]	`pt, pt-BR` (wartość domyślna), `pt-PT`	✔️	✔️ (wersja zapoznawcza)
Holenderski [`nl`]	`nl, nl-BE, nl-NL` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)	✔️ (`nl, nl-NL`)
Arabski [`ar`]	`ar, ar-SA` (ustawienie domyślne), `ar-EG, ar-MA, ar-KW, ar-JO`	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Armeński	`hy-AM` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Bangla	`bn-IN` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Baskijski	`eu-ES` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Bułgarski [`bg`]	`bg, bg-BG` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Kataloński [`ca`]	`ca, ca-ES` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Chorwacki [`hr`]	`hr, hr-HR` (ustawienie domyślne), hr-BA	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Czeski [`cs`]	`cs, cs-CZ` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Duński [`da`]	`da, da-DK` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Estończyk [`et`]	`et, et-EE` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Fiński [`fi`]	`fi, fi-FI` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Galicyjski	`gl-ES` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Grecki [`el`]	`el, el-GR` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Gudżarati	`gu-IN` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Hebrajski	`he-IL` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Hindi [`hi`]	`hi, hi-IN` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Węgierski [`hu`]	`hu, hu-HU` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Islandzki [`is`]	`is, is-IS` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Indonezyjski [`id`]	`id, id-ID` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Irlandzki	`ga-IE` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Kannada	`kn-IN` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Koreański [`ko`]	`ko, ko-KR` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Łotewski [`lv`]	`lv, lv-LV` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Litewski [`lt`]	`lt, lt-LT` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Malayalam	`ml-IN` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Malezyjski [`ms`]	`ms, ms-MY` (wartość domyślna), `ms-BN`	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Marathi	`mr-IN` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Norweski [`no`]	nie, no-NO (wartość domyślna), nb-NO	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Perski	`fa-AE` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Polski [`pl`]	`pl, pl-PL` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Pendżabski	`pa-IN` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Rumuński [`ro`]	`ro, ro-RO` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Rosyjski [`ru`]	`ru, ru-RU` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Serbski [`sr`] (cyrylica lub łacińska)	`sr, sr-BA` (wartość domyślna), `sr-ME, sr-RS`	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Słowacki [`sk`]	`sk, sk-SK` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Słowenia [`sl`]	`sl, sl-SL` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Tamil [`ta`]	`ta, ta-IN` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Szwedzki [`sv`]	`sv, sv-SE` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Telugu	`te-IN` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Tajski [`th`]	`th, th-TH` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Turecki [`tr`]	`tr, tr-TR` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Ukraiński [`uk`]	`uk, uk-UA` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Urdu	`ur-PK` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)
Wietnamski [`va`]	`va, vi-VN` (domyślne)	✔️ (wersja zapoznawcza)	✔️ (wersja zapoznawcza)