Wyszukiwanie dokumentów (interfejs API REST usługi Azure AI Search)

Artykuł
02/07/2024

Żądanie zapytania dotyczy kolekcji dokumentów pojedynczego indeksu w usłudze wyszukiwania. Zawiera ona parametry definiujące kryteria dopasowania i parametry, które kształtują odpowiedź. Począwszy od wersji interfejsu API 2021-04-30-Preview, można również użyć aliasu indeksu , aby kierować określony indeks zamiast używać samej nazwy indeksu.

Możesz użyć polecenia GET lub POST. Parametry zapytania są określane w ciągu zapytania dla żądań GET i w treści żądania dla żądań 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 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]

Po wywołaniu polecenia GET długość adresu URL żądania nie może przekraczać 8 KB. Ta długość jest zwykle wystarczająca dla większości aplikacji. Jednak niektóre aplikacje generują duże zapytania, szczególnie w przypadku użycia wyrażeń filtru OData. W przypadku tych aplikacji usługa 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 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ę wartość na unikatową, zdefiniowaną przez użytkownika nazwę usługi wyszukiwania.
[nazwa indeksu]/docs	Wymagane. Określa kolekcję dokumentów nazwanego indeksu.
[parametry zapytania]	Parametry zapytania są określone w identyfikatorze URI dla żądań GET i w treści żądania dla żądań POST.
api-version	Wymagane. Bieżąca stabilna wersja to `api-version=2020-06-30`. Zobacz Wersje interfejsu API , aby uzyskać więcej wersji. W przypadku zapytań wersja interfejsu API jest zawsze określana jako parametr identyfikatora URI zarówno dla polecenia GET, jak i POST.

Zalecenia dotyczące kodowania adresów URL

Pamiętaj, aby kodować określone parametry zapytania w adresie URL podczas bezpośredniego wywoływania interfejsu API REST GET. W przypadku operacji wyszukiwania dokumentów 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 dla 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 polecenia GET. Kodowanie adresów URL nie jest konieczne w przypadku korzystania z funkcji POST lub 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 udostępniany w żądaniu, w przeciwnym razie wymagany jest klucz. Klucz api-key to unikatowy, generowany przez system ciąg, 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 do operacji tylko do odczytu w 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 udostępniany w żądaniu, w przeciwnym razie wymagany jest klucz. Klucz api-key to unikatowy, generowany przez system ciąg, 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 do operacji tylko do odczytu w 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 polecenia POST:

{  
     "count": true | false (default),  
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "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",  
     "queryType": "simple" (default) | "full",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "sessionId" : "session_id",
     "skip": # (default 0),  
     "top": #  
   }

Kontynuacja częściowych odpowiedzi wyszukiwania

Czasami usługa Azure AI Search nie może zwrócić wszystkich żądanych wyników w pojedynczej odpowiedzi wyszukiwania. Może się to zdarzyć z różnych powodów, takich jak wtedy, gdy zapytanie żąda zbyt wielu dokumentów, nie określając $top ani nie określając wartości, która $top 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 jeśli było to żądanie POST. Możesz użyć wartości tych adnotacji, aby sformułować inne żądanie wyszukiwania, aby uzyskać następną część odpowiedzi wyszukiwania. Jest to nazywane kontynuacją oryginalnego żądania wyszukiwania, a adnotacje są zwykle nazywane tokenami kontynuacji. Zobacz przykład w sekcji Odpowiedź poniżej, 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 powinni zawsze być gotowi do obsługi przypadków, w których zwracana jest mniejsza liczba dokumentów niż oczekiwano, a token kontynuacji jest dołączany do kontynuowania 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, wszelkie wysyłane żądania kontynuacji muszą również używać polecenia 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 i $top$skip razem. Jeśli na przykład chcesz, aby strony o rozmiarze 10, pierwsze żądanie powinno mieć $top=10 wartość i , drugie żądanie powinno mieć $top=10 wartość i $skip=0, trzecie żądanie powinno mieć $top=10 wartość i $skip=20$skip=10itd.

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 podczas wywoływania za pomocą funkcji POST. Składnia niektórych parametrów różni się nieco między instrukcjami GET i POST. Te różnice są zanotowane zgodnie z poniższymi wymaganiami.

Nazwa	Typ	Opis
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.
`$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. Jest to liczba wszystkich dokumentów pasujących do parametrów wyszukiwania i $filter, ignorowania `$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". W przypadku wywołania metody GET `facet` jest polem (`facet: field1`). W przypadku wywołania 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 do dostosowania tworzenia aspektów, wyrażone jako pary nazwa-wartość rozdzielane przecinkami. Prawidłowe parametry 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 dystrybuowania zapytań aspektowych między fragmentami. Możesz ustawić liczbę na zero lub wartość większą lub równą liczbie unikatowych wartości w polu aspektowym, aby uzyskać dokładną liczbę wszystkich fragmentów. Kompromis polega na zwiększonym opóźnieniu. Dla opcji "sort" można ustawić wartość "count", "-count", "value", "-value". Użyj funkcji count, aby sortować 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 parametru -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 o liczbę dokumentów z każdą nazwą miasta). Jeśli trzy najlepsze kategorie to Budżet, Motel i Luksus, a Budżet ma 5 trafień, Motel ma 6, a Luxury ma 4, to zasobniki są w kolejności Motel, Budget, Luxury. Dla parametru -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 klasyfikacje 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 20, a drugi dla 20 i wyższych). 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. "interval" to interwał liczby całkowitej większy niż 0 dla liczb, lub minuty, 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ą przedziały dla 0-100, 100-200, 200-300, 300-400, 400-500 i 500-600. Ciąg "facet=lastRenovationDate,interval:year" tworzy jeden zasobnik dla każdego roku, kiedy hotele zostały odnowione. Dla parametru "timeoffset" można ustawić wartość ([+-]hh:mm, [+-]hhmm lub [+-]hh). 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 do konta w ustawieniu granic czasu. Na przykład: "facet=lastRenovationDate,interval:day,timeoffset:-01:00" używa granicy dnia rozpoczynającej się o godzinie 01:00:00 UTC (północ w docelowej strefie czasowej). Liczby i sortowania 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 limitu czasu. Na przykład: dla "facet=lastRenovationDate,interval:day", granica dnia rozpoczyna się o 00:00:00 UTC.
$filter	ciąg	Opcjonalny. Wyrażenie wyszukiwania strukturalnego w standardowej składni OData. Filtrowalne pola mogą być używane tylko w filtrze. Podczas wywoływania przy użyciu funkcji POST ten parametr ma 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 5 wyróżnień na pole. Limit można skonfigurować dla każdego pola, dołączając ciąg "-<max #of highlights>" po nazwie pola. Na przykład wyrażenie "highlight=title-3,description-10" zwraca maksymalnie 3 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 elementem 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.
queryType	ciąg	Opcjonalny. Prawidłowe wartości to "proste" lub "pełne". Wartość domyślna to "simple". 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.
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 wywołana funkcja `"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 zwiększenie tagów, które mogą zawierać przecinki, możesz uciec od dowolnych takich wartości na liście przy użyciu pojedynczych cudzysłowów. Jeśli same wartości zawierają pojedyncze cudzysłowy, 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 będzie wtedy "&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 "lokalne" lub "globalne". Wartość domyślna to "local". Określ, czy należy obliczyć statystyki oceniania, takie jak częstotliwość dokumentów, globalnie (we wszystkich fragmentach) w celu uzyskania bardziej spójnego oceniania, czy lokalnie (na bieżącym fragmentacji) 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. 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żna rozdzielić 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 ``wartość . Zobacz Prosta składnia zapytań , aby uzyskać szczegółowe informacje na temat składni wyszukiwania. Czasami wyniki mogą być zaskakujące podczas wykonywania zapytań względem pól z możliwością wyszukiwania. Tokenizer 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 dla dużych liczb w języku angielskim. Z tego powodu zalecamy używanie białych znaków, a nie znaków interpunkcyjnych, 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 w celu zliczenia dokumentu jako dopasowania.
searchFields	ciąg	Opcjonalny. Lista nazw pól rozdzielanych przecinkami do wyszukania określonego tekstu. Pola docelowe muszą być oznaczone jako możliwe do wyszukiwania w schemacie indeksu.
$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 zostaną uwzględnione w projekcji. Po wywołaniu metody POST ten parametr ma nazwę select zamiast $select.
Sessionid	ciąg	Opcjonalny. Użycie identyfikatora sessionId pomaga poprawić spójność wyników 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 wykonuje najlepsze wysiłki w celu kierowania danego żądania do tej samej repliki dla tej sesji. Należy pamiętać, że ponowne użycie tych samych wartości identyfikatorów sesji wielokrotnie 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ść wyników.
$skip	liczba całkowita	Opcjonalny. Liczba wyników wyszukiwania do pominięcia. Po wywołaniu 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 jej używać `$skip` ze względu na to ograniczenie, rozważ użycie $orderby w polu zawierającym unikatowe wartości dla każdego dokumentu w indeksie (na przykład klucza dokumentu) i $filter z zapytaniem zakresu.
$top	liczba całkowita	Opcjonalny. Liczba wyników wyszukiwania do pobrania. Ta wartość domyślna to 50. Po wywołaniu metody POST ten parametr nosi nazwę top zamiast `$top`. Jeśli określisz wartość większą niż 1000 i będzie więcej niż 1000 wyników, zostanie zwróconych tylko pierwszych 1000 wyników wraz z linkiem do następnej strony wyników (zobacz @odata.nextLink w poniższym przykładzie). 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 dokumenty wyszukiwania zwracają co najwyżej 50 wyników, jeśli nie określisz `$top`wartości . Jeśli istnieje więcej niż 50 wyników, odpowiedź zawiera informacje dotyczące pobierania następnej strony 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 `$top` i istnieje więcej niż 1000 wyników, zwracane są tylko pierwsze 1000 wyników wraz z informacjami, aby pobrać następną stronę z maksymalnie 1000 wyników.

Reakcja

Kod stanu: 200 OK jest zwracana dla pomyślnej odpowiedzi.

  {
    "@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),
      "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 temacie Składnia wyrażeń OData dla usługi Azure AI Search.

Przeszukaj indeks posortowany malejąco według daty:

GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2020-06-30

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

W wyszukiwaniu aspektowym wyszukaj indeks i pobierz aspekty pod kątem kategorii, klasyfikacji, tagów i elementów z 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=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ]  
    }  
```
Zwróć uwagę, że ostatni aspekt znajduje się na polu podrzędnym. Aspekty zliczają dokument nadrzędny (Hotele) i nie pośrednie dokumenty podrzędne (Pokoje), więc odpowiedź określa liczbę hoteli, które mają jakiekolwiek pokoje w każdym zasobniku cen.

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=2020-06-30

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

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=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }  
```

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

GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2020-06-30

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

Wyszukaj 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=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }  
```
Indeks można wykonywać tylko w danym momencie. Nie twórz wielu indeksów dla każdego języka, chyba że planujesz wykonać zapytanie pojedynczo.

Stronicowanie — pobierz pierwszą stronę elementów (rozmiar strony to 10):

GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2020-06-30

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

Stronicowanie — pobierz drugą stronę elementów (rozmiar strony to 10):

GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2020-06-30

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

Pobieranie określonego zestawu pól:

GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2020-06-30

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

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=2020-06-30

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

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

GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2020-06-30

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

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=2020-06-30

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

Przeszukaj indeks przy założeniu, że istnieje profil oceniania o nazwie "geo" z dwoma funkcjami oceniania odległości, jeden definiujący parametr o nazwie "currentLocation" i definiujący parametr o nazwie "lastLocation". W poniższym przykładzie parametr "currentLocation" ma ogranicznik pojedynczej kreski (-). Następuje po nim współrzędne geograficzne i współrzędne geograficzne, 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=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "scoringProfile": "geo",  
      "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
    }  
```
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=22020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "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.
Znajdowanie dokumentów w indeksie przy użyciu składni zapytań Lucene). 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=2020-06-30&querytype=full` 
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
     "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}  
```
Znajdowanie dokumentów w indeksie przy jednoczesnym faworyzowaniu spójnego oceniania w przypadku mniejszych opóźnień. To zapytanie oblicza częstotliwości dokumentów w całym indeksie i dokłada wszelkich starań, aby kierować tę samą replikę do 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=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }  
```