Sugestie (interfejs API REST usługi Azure AI Search)
Żądanie Sugestie to zapytanie typu wyszukiwania zgodnie z rzeczywistym typem, które wyszukuje pasujące wartości w polach obsługujących sugestie i zwraca dokumenty zawierające dopasowanie. Jeśli na przykład włączysz sugestie dotyczące pola miasta , wpisanie "sea" powoduje wygenerowanie dokumentów zawierających "Seattle", "Sea Tac" i "Seaside" (wszystkie rzeczywiste nazwy miast) dla tego pola.
Odpowiedź jest zawartością pasującego dokumentu oraz klucza dokumentu. W przeciwieństwie do autouzupełniania, który zwraca ukończony termin lub frazę używaną w zapytaniu pomocniczym, to żądanie zwraca informacje rozpoznawane jako rzeczywiste dokumenty. Jeśli pasujące terminy lub frazy są identyczne w dokumentach, zgodna zawartość jest powtarzana. Aby poprawić strukturę wyników, rozważ użycie filtru $select w celu zwrócenia dodatkowych pól, które zapewniają więcej różnic i kontekstu.
Protokół HTTPS jest wymagany w przypadku żądań obsługi. Żądanie Sugerowane można skonstruować przy użyciu metod GET lub POST.
GET https://[service name].search.windows.net/indexes/[index name]/docs/suggest?[query parameters]
Content-Type: application/json
api-key: [admin or query key]
POST https://[service name].search.windows.net/indexes/[index name]/docs/suggest?api-version=[api-version]
Content-Type: application/json
api-key: [admin or query key]
W przeciwieństwie do żądania dokumenty wyszukiwania można powiązać wywołanie Sugestie z danymi wejściowymi klawiatury, podczas gdy wywołanie wyszukiwania może być powiązane ze zdarzeniem kliknięcia.
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ą bardzo duże zapytania, szczególnie w przypadku użycia wyrażeń filtrów 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 bardzo 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. |
| 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 sugestii obejmuje to następujące elementy:
- search
- $filter
- 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. Podczas wywoływania sugestii przy użyciu funkcji POST nie jest konieczne kodowanie adresów URL lub podczas korzystania z biblioteki klienta usługi Azure AI Search platformy .NET jest obsługiwane kodowanie adresów URL.
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 . |
Treść żądania
W przypadku polecenia GET: Brak.
W przypadku polecenia POST:
{
"filter": "odata_filter_expression",
"fuzzy": true | false (default),
"highlightPreTag": "pre_tag",
"highlightPostTag": "post_tag",
"minimumCoverage": # (% of index that must be covered to declare query successful; default 80),
"orderby": "orderby_expression",
"search": "partial_search_input",
"searchFields": "field_name_1, field_name_2, ...",
"select": "field_name_1, field_name_2, ...",
"suggesterName": "suggester_name",
"top": # (default 5)
}
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 zapytania w adresie URL niezależnie od tego, czy wywołasz interfejs API za pomocą polecenia GET, czy POST. |
| $filter | ciąg | Opcjonalny. Wyrażenie, które filtruje dokumenty rozważane pod kątem sugestii. Filtrowalne pola można używać tylko w filtrze. Wyrażenia filtru "search.ismatch" i "search.ismatchscoring*" nie są obsługiwane w interfejsie API autouzupełniania. 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. |
| Rozmyte | boolean | Opcjonalny. Wartość domyślna to false. Po ustawieniu wartości true ten interfejs API znajdzie sugestie, nawet jeśli w tekście wyszukiwania znajduje się zastąpiony lub brakuje znaku. Odległość edycji wynosi 1 na ciąg zapytania. Jeśli ciąg zapytania ma wiele terminów, może istnieć tylko jeden brak, dodatkowy, zastąpiony lub transponowany znak w całym ciągu. Włączenie dopasowania rozmytego może być lepszym środowiskiem w niektórych scenariuszach, jest to koszt wydajności, ponieważ wyszukiwania sugestii rozmyte są wolniejsze i zużywają więcej zasobów. |
| highlightPostTag | ciąg | Opcjonalny. Domyślnie jest to pusty ciąg. 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 #). Podczas wywoływania przy użyciu polecenia GET zastrzeżone znaki w adresie URL muszą być zakodowane procentowo (na przykład %23 zamiast #). |
| highlightPreTag | ciąg | Opcjonalny. Domyślnie jest to pusty ciąg. Tag ciągu, który poprzedza wyróżniony termin. Należy ustawić element z wyróżnionym elementemPostTag. Podczas wywoływania przy użyciu polecenia GET zastrzeżone znaki w adresie URL muszą być zakodowane procentowo (na przykład %23 zamiast #). |
| $orderby | ciąg | Opcjonalny. Lista wyrażeń rozdzielanych przecinkami do sortowania wyników według. Każde wyrażenie może być nazwą pola lub wywołaniem geo.distance() funkcji. Każde wyrażenie może być zgodne z wyrażeniem "asc" (rosnąco) lub "desc" (malejąco). Wartość domyślna to kolejność rosnąca. Istnieje limit 32 klauzul dla $orderby. Po wywołaniu metody POST ten parametr ma nazwę order zamiast $orderby. |
| minimumCoverage | liczba całkowita | Opcjonalny. Wartość domyślna to 80. 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 go zgłosić jako sukces. Wartość domyślna odzwierciedla stronniczość w kierunku szybkości i wydajności w pełnym zasięgu. Zmniejszenie ograniczenia pokrycia ogranicza rozszerzanie zapytań, co pozwala na szybsze powrót wyników. Umożliwia to również pomyślne działanie zapytania w przypadku częściowej dostępności indeksu, nawet jeśli jeden fragment jest powolny, aby reagować lub niedostępny z powodu problemów z kondycją usługi lub konserwacji indeksu. Niezależnie od wartości minimumCoverage, ta wartość procentowa indeksu musi być dostępna lub sugestie zwracają kod stanu HTTP 503. Jeśli sugestie powiedzą się na poziomie minimumCoverage, zwraca wartość HTTP 200 i zawiera @search.coverage wartość w odpowiedzi wskazującą wartość procentową indeksu, który był dostępny podczas obsługi zapytania. Obniżenie tej wartości może być przydatne, jeśli wystąpią błędy 503. W przeciwnym razie możesz rozważyć podniesienie wartości, jeśli odpowiedź dostarcza niewystarczające dopasowania. |
| search | ciąg | Wymagane. Tekst wyszukiwania, który ma być używany do sugerowania zapytań. Musi mieć co najmniej 1 znak i nie więcej niż 100 znaków. Nie może zawierać operatorów, składni zapytań ani fraz cytowanych. |
| searchFields | ciąg | Opcjonalny. Lista nazw pól rozdzielanych przecinkami do wyszukania określonego tekstu wyszukiwania. Pola docelowe muszą być wymienione w definicji sugestorów w indeksie. |
| $select | ciąg | Opcjonalny. Lista pól rozdzielonych przecinkami do pobrania. Jeśli nie zostanie określona, zwracany jest tylko klucz dokumentu i tekst sugestii. Możesz jawnie zażądać wszystkich pól, ustawiając ten parametr na *wartość . Podczas wywoływania za pomocą funkcji POST ten parametr nosi nazwę select zamiast $select. |
| suggesterName | ciąg | Wymagane. Nazwa sugestora określona w kolekcji Sugerowane , która jest częścią definicji indeksu. Sugestor określa, które pola są skanowane pod kątem sugerowanych terminów zapytania. |
| $top | liczba całkowita | Opcjonalny. Wartość domyślna to 5). Liczba sugestii autouzupełniania do pobrania. Wartość musi być liczbą z zakresu od 1 do 100. Podczas wywoływania za pomocą funkcji POST ten parametr nosi nazwę top zamiast $top. |
Reakcja
Kod stanu: "200 OK" jest zwracany dla pomyślnej odpowiedzi.
{
"@search.coverage": # (if minimumCoverage was provided in the query),
"value": [
{
"@search.text": "...",
"<key field>": "..."
},
...
]
}
Jeśli opcja projekcji jest używana do pobierania pól, są one uwzględniane w każdym elemenie tablicy:
{
"value": [
{
"@search.text": "...",
"<key field>": "..."
<other projected data fields>
},
...
]
}
Przykłady
Pobierz 5 sugestii, w których częściowe dane wejściowe wyszukiwania to "lux":
GET /indexes/hotels/docs/suggest?search=lux&$top=5&suggesterName=sg&api-version=2020-06-30
POST /indexes/hotels/docs/suggest?api-version=2020-06-30
{
"search": "lux",
"top": 5,
"suggesterName": "sg"
}
Zwróć uwagę, że element suggesterName jest wymagany w operacji Sugestie.