Autouzupełniania (interfejs API REST usługi Azure AI Search)
Interfejs API autouzupełniania kończy częściowo wpisane dane wejściowe zapytania przy użyciu istniejących terminów w indeksie wyszukiwania do użycia w zapytaniu pomocniczym. Jeśli na przykład dane wejściowe zapytania to "medic", interfejs API autouzupełniania zwraca "medicare"wartość , "medicaid"jeśli "medicine" te terminy znajdują się w indeksie. Wewnętrznie wyszukiwarka wyszukuje pasujące terminy w polach, które mają skonfigurowane sugestor .
Protokół HTTPS jest wymagany w przypadku żądań obsługi. Żądanie autouzupełniania można skonstruować przy użyciu metod GET lub POST.
GET https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?[query parameters]
Content-Type: application/json
api-key: [admin or query key]
POST https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?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ą 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. Zobacz Wersje interfejsu API , aby uzyskać listę obsługiwanych 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 autouzupełniania kodowanie adresów URL może być konieczne dla następujących parametrów zapytania:
- 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. 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. Żądania zapytań względem docs kolekcji mogą określać klucz administratora lub klucz-zapytania jako api-key. Klucz zapytania jest używany do operacji tylko do odczytu w kolekcji dokumentów indeksu. 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:
{
"autocompleteMode": "oneTerm" (default) | "twoTerms" | "oneTermWithContext",
"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),
"search": "partial_search_input",
"searchFields": "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 Przechowywanie wersji interfejsu API. W przypadku tej operacji wersja interfejsu API jest określana jako parametr identyfikatora URI niezależnie od tego, czy wywołasz funkcję Autouzupełniania za pomocą polecenia GET, czy POST. |
| Autocompletemode | ciąg | Opcjonalny. Wartość domyślna to oneTerm. Prawidłowe wartości to oneTerm, twoTerms, oneTermWithContext. element oneTerm zwraca pojedynczy termin. Jeśli zapytanie ma dwa terminy, zostanie ukończony tylko ostatni termin. Na przykład, biorąc pod uwagę "washington medic", odpowiedź może być dowolną z następujących pojedynczych terminów: "medicaid", , "medicare""medicine". Dwie terminy są zgodne z dwuokresowymi frazami w indeksie. Na przykład, biorąc pod uwagę "medic", odpowiedź może być "medicare coverage", lub "medical assistant". W wielu przypadkach pojedyncze terminy "medicare" lub "medical" nie zostaną zwrócone, ponieważ preferencje są podane do dwuokresowych fraz, które pasują.oneTermWithContext kończy ostatni termin w zapytaniu z co najmniej dwoma terminami, gdzie ostatnie dwa terminy są frazą, która istnieje w indeksie. Na przykład, na przykład "washington medic", odpowiedź może być "washington medicaid", "washington medical". |
| $filter | ciąg | Opcjonalny. Ustrukturyzowane wyrażenie wyszukiwania w standardowej składni OData, która filtruje dokumenty rozważane do tworzenia ukończonych sugestii terminów. Wyrażenia filtru "search.ismatch" i "search.ismatchscoring*" nie są obsługiwane w interfejsie API autouzupełniania. 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. |
| 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 (1) jest zastępowany lub brakuje znaku. Zapewnia to lepsze środowisko w niektórych scenariuszach, ale wiąże się to z kosztem wydajności, ponieważ wyszukiwania sugestii rozmytych 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 #). W przypadku wywoływania przy użyciu metody 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 elementem highlightPostTag. W przypadku wywoływania przy użyciu metody GET zastrzeżone znaki w adresie URL muszą być zakodowane procentowo (na przykład %23 zamiast #). |
| 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 je zgłosić jako powodzenie. Wartość domyślna odzwierciedla stronniczość w kierunku szybkości i wydajności w przypadku pełnego pokrycia. Zmniejszenie ograniczeń pokrycia ogranicza rozszerzanie zapytań, dzięki czemu wyniki mogą wrócić szybciej. Umożliwia również pomyślne działanie zapytania w przypadku częściowej dostępności indeksu, nawet jeśli jeden fragment działa wolno, aby reagować lub niedostępny z powodu problemów z kondycją usługi lub konserwacji indeksu. Niezależnie od wartości minimalnejCoverage, ta wartość procentowa indeksu musi być dostępna lub autouzupełnianie zwraca kod stanu HTTP 503. Jeśli autouzupełnianie powiedzie się na poziomie minimumCoverage, zwraca wartość HTTP 200 i uwzględnia @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ępują 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 do wyszukania. Tekst wyszukiwania do ukończenia. 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. |
| pola wyszukiwania | ciąg | Opcjonalny. Lista nazw pól rozdzielanych przecinkami do wyszukiwania określonego tekstu wyszukiwania. Pola docelowe muszą być wymienione w definicji sugestorów w indeksie. |
| suggesterName | ciąg | Wymagane. Nazwa sugestora określona w kolekcji sugestorów , 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 automatycznie wypełnionych sugestii do pobrania. Wartość musi być liczbą z zakresu od 1 do 100. W przypadku wywołania metody POST ten parametr ma nazwę top zamiast $top. |
(1) Ograniczenia rozmyte w autouzupełnianiu:
Najpierw odległość edycji jest ograniczona do tylko jednej różnicy znaków na token w przeciwieństwie do parametru rozmytego w wyszukiwaniu. Ograniczenie odległości edycji do jednego znaku oznacza, że nie wszystkie dopasowania kandydata zostaną znalezione, ale limit jest niezbędny do zapewnienia akceptowalnego poziomu wydajności.
Po drugie krok rozmyty następuje po częściowym rozszerzeniu tokenu, a tylko terminy z tego samego fragmentu indeksu są uznawane za dopasowania rozmyte. To ograniczenie zwiększa wydajność interfejsu API autouzupełniania, eliminując agregację dopasowań rozmytych we wszystkich fragmentach. To ograniczenie staje się mniej zauważalne, ponieważ do indeksu jest dodawanych więcej terminów, co powoduje podobny rozkład terminów dla każdego fragmentu. Ponieważ terminy są dystrybuowane równomiernie, rozmyte dopasowania w obrębie fragmentu są dobrym przybliżeniem rozmytych dopasowań w całym indeksie. Jednak wyniki mogą być gorsze, jeśli indeks ma mniej terminów, takich jak w indeksie testowym lub prototypowym, co skutkuje nierówną reprezentacją fragmentów. Aby uzyskać więcej informacji na temat dzielenia indeksów na fragmenty, zobacz kombinacje partycji i repliki.
Reakcja
Kod stanu: "200 OK" jest zwracany dla pomyślnej odpowiedzi.
Ładunek odpowiedzi ma dwie właściwości.
| Właściwość | Opis |
|---|---|
| "tekst" | Ukończony termin lub fraza |
| "queryPlusText" | Początkowe dane wejściowe zapytania oraz ukończony termin lub fraza |
{
"@search.coverage": # (if minimumCoverage was provided in the query),
"value": [
{
"text": "...",
"queryPlusText": "..."
},
...
]
}
Przykłady
Przykład 1: Pobierz trzy sugestie autouzupełniania, w których częściowe dane wejściowe wyszukiwania są 'washington medic' w trybie domyślnym (oneTerm):
GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&api-version=2020-06-30
POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{
"search": "washington medic",
"filter": "search.in(roleId, 'admin,manager')",
"top": 3,
"suggesterName": "sg"
}
Odpowiedź:
{
"value": [
{
"text": "medicaid",
"queryPlusText": "washington medicaid"
},
{
"text": "medicare",
"queryPlusText": "washington medicare"
},
{
"text": "medicine",
"queryPlusText": "washington medicine"
}
]
}
Przykład 2: Pobieranie trzech sugestii autouzupełniania, w których są częściowe dane wejściowe 'washington medic' wyszukiwania i autocompleteMode=twoTerms:
GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&autocompleteMode=twoTerms&api-version=2020-06-30
POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{
"search": "washington medic",
"autocompleteMode": "twoTerms",
"filter": "planDuration ge 1",
"top": 3,
"suggesterName": "sg"
}
Odpowiedź:
{
"value": [
{
"text": "medicaid insurance",
"queryPlusText": "washington medicaid insurance"
},
{
"text": "medicare plan",
"queryPlusText": "washington medicare plan"
},
{
"text": "medicine book",
"queryPlusText": "washington medicine book"
}
]
}
Zwróć uwagę, że element suggesterName jest wymagany w operacji autouzupełniania.