Interfejs Query API udostępnia metody wyszukiwania i sugestii, które umożliwiają tworzenie interfejsu wyszukiwania lub umieszczanie wyników wyszukiwania w aplikacji.
W przypadku aplikacji internetowych o minimalnych wymaganiach rozważ użycie widżetu wyszukiwania. Więcej informacji znajdziesz w artykule Tworzenie interfejsu wyszukiwania za pomocą widżetu wyszukiwania.
Tworzenie interfejsu wyszukiwania
Utworzenie minimalnego interfejsu wyszukiwania wymaga kilku kroków:
- Konfigurowanie wyszukiwarki
- Generowanie danych logowania OAuth dla aplikacji
- Wysyłanie zapytań do indeksu
- Wyświetlanie wyników zapytania
Możesz dodatkowo ulepszyć interfejs wyszukiwania za pomocą funkcji takich jak stronicowanie, sortowanie, filtrowanie, aspekty i automatyczne sugestie.
Konfigurowanie wyszukiwarki
Musisz utworzyć co najmniej 1 wyszukiwarkę, aby powiązać ją z każdym utworzonym interfejsem wyszukiwania. Wyszukiwarka podaje domyślne parametry zapytania, na przykład uwzględnione źródła danych, kolejność sortowania, filtry i aspekty, o które prosisz. W razie potrzeby możesz zastąpić te parametry za pomocą interfejsu API zapytań.
Więcej informacji o aplikacjach do wyszukiwania znajdziesz w artykule Dostosowywanie wyszukiwania w Cloud Search.
Generowanie danych logowania OAuth dla aplikacji
Oprócz czynności opisanych w artykule Konfigurowanie dostępu do interfejsu Google Cloud Search API musisz też wygenerować dane logowania OAuth dla aplikacji internetowej. Rodzaj tworzonych danych logowania zależy od kontekstu, w którym używany jest interfejs API.
Użyj danych logowania, aby poprosić o autoryzację w imieniu użytkownika. Podczas wysyłania prośby o autoryzację używaj zakresu https://www.googleapis.com/auth/cloud_search.query.
Więcej informacji o opcjach OAuth i bibliotekach klienta znajdziesz na stronie [Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"}.
Wysyłanie zapytań do indeksu
Użyj metody search, aby wyszukiwać informacje w indeksie.
Każde żądanie musi zawierać 2 informacje: tekst query, na podstawie którego będą dopasowywane elementy, oraz searchApplicationId identyfikujący identyfikator aplikacji do wyszukiwania, która ma być używana.
Ten fragment kodu pokazuje zapytanie do źródła danych o filmach dotyczące filmu Titanic:
{
"query": "titanic",
"requestOptions": {
"searchApplicationId": "searchapplications/<search_app_id>"
},
}
Wyświetlanie wyników zapytania
Interfejsy wyszukiwania powinny co najmniej wyświetlać element title oraz link do oryginalnego elementu. Możesz dodatkowo ulepszyć wyświetlanie wyników wyszukiwania, korzystając z dodatkowych informacji w wynikach wyszukiwania, takich jak fragment i metadane.
Obsługa wyników dodatkowych
Domyślnie Cloud Search zwraca wyniki dodatkowe, gdy liczba wyników zapytania użytkownika jest niewystarczająca. Pole queryInterpretation w odpowiedzi wskazuje, kiedy zwracane są wyniki dodatkowe. Jeśli zwracane są tylko wyniki dodatkowe, wartość InterpretationType jest ustawiona na REPLACE. Jeśli wraz z wynikami dodatkowymi zwróconych zostanie kilka wyników dla pierwotnego zapytania, wartość InterpretationType zostanie ustawiona na BLEND. W każdym z tych przypadkówQueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.
Jeśli zwracane są wyniki uzupełniające, warto dodać tekst informujący o tym, że zostały one zwrócone. Na przykład w przypadku zapytania a
REPLACE możesz wyświetlić ciąg znaków „Wyszukiwanie oryginalnego zapytania nie zwróciło żadnych wyników. Wyświetlam wyniki podobnych zapytań”.
W przypadku BLEND możesz wyświetlić ciąg znaków „Wyszukiwanie oryginalnego zapytania nie dało wystarczającej liczby wyników. W tym wyniki podobnych zapytań”.
Obsługa wyników dotyczących osób
Cloud Search zwraca 2 rodzaje wyników dotyczących osób: dokumenty związane z osobą, której imię i nazwisko zostało użyte w zapytaniu, oraz informacje o pracowniku, którego imię i nazwisko zostało użyte w zapytaniu. Ten drugi typ wyniku jest funkcją wyszukiwania osób w Cloud Search, a wyniki takiego zapytania można znaleźć w polu structuredResults odpowiedzi interfejsu API zapytania:
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
Dopasowywanie bezpośrednich podwładnych
Dopasowywanie bezpośrednich podwładnych to funkcja wyszukiwania osób w Cloud Search, która umożliwia użytkownikom wyświetlanie bezpośrednich podwładnych danej osoby w organizacji.
Wynik jest dostępny w polu structuredResults.
W przypadku zapytań dotyczących menedżera lub bezpośrednich podwładnych danej osoby odpowiedź zawiera symbol assistCardProtoHolder w ramach structuredResults. assistCardProtoHolder ma pole o nazwie cardType, które będzie równe RELATED_PEOPLE_ANSWER_CARD. Element assistCardProtoHolder zawiera kartę o nazwie relatedPeopleAnswerCard, która zawiera rzeczywistą odpowiedź.
Zawiera subject (osobę, która została uwzględniona w zapytaniu) i relatedPeople, czyli zestaw osób powiązanych z tematem. Pole
relationType zwraca wartość MANAGER lub DIRECT_REPORTS.
Poniższy kod pokazuje przykładową odpowiedź na zapytanie dotyczące bezpośrednich podwładnych:
{
"results": [],
"structuredResults": [{
"assistCardProtoHolder": {
"extensions": {
"@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",
"cardMetadata": {
"cardCategory": "ANSWER"
},
"cardType": "RELATED_PEOPLE_ANSWER_CARD",
"relatedPeopleAnswerCard": {
"subject": {
"email": "AdamStanford@psincs-test01.newjnj.com",
"displayName": "Adam Stanford"
"manager": {
"email": "simonsais@psincs-test01.newjnj.com"
}
},
"relatedPeople": [{
"email": "EdgarMountainRamirez@psincs-test01.newjnj.com",
"displayName": "Edgar Mountain Ramirez"
}, {
"email": "FranciscoJoseMartinez@psincs-test01.newjnj.com",
"displayName": "Francisco Jose Martinez"
}],
"relationType": "DIRECT_REPORTS",
}
}
}
}]
}
Wyłączanie optymalizacji, w tym wyników dodatkowych
Domyślnie włączone są optymalizacje, takie jak wyniki dodatkowe. Możesz jednak wyłączyć wszystkie optymalizacje lub tylko wyniki dodatkowe na poziomie aplikacji do wyszukiwania i zapytania:
Aby wyłączyć wszystkie optymalizacje na poziomie wyszukiwarki, w tym wyniki dodatkowe, synonimy i korektę pisowni, ustaw
QueryInterpretationConfig.force_verbatim_modenatruew wyszukiwarkach.Aby wyłączyć wszystkie optymalizacje na poziomie zapytania, w tym wyniki dodatkowe, synonimy i korektę pisowni, ustaw wartość parametru
QueryInterpretationOptions.enableVerbatimModenatruew zapytaniu.Aby wyłączyć wyniki dodatkowe na poziomie aplikacji do wyszukiwania, w zapytaniu ustaw wartość
QueryInterpretationOptions.forceDisableSupplementalResultsnatrue.Aby wyłączyć wyniki dodatkowe na poziomie zapytania, ustaw
QueryInterpretationOptions.disableSupplementalResultsnatruew zapytaniu.
Wyróżnianie fragmentów
W przypadku zwróconych elementów zawierających indeksowany tekst lub treść HTML zwracany jest fragment treści. Te treści pomagają użytkownikom określić trafność zwróconego produktu.
Jeśli w fragmencie kodu znajdują się terminy zapytania, zwracane są też co najmniej 1 zakres dopasowania wskazujący lokalizację tych terminów.
Użyj znaku matchRanges, aby wyróżnić pasujący tekst podczas renderowania wyników. Poniższy przykład w JavaScript przekształca fragment kodu w kod HTML, w którym każdy pasujący zakres jest otoczony tagiem <span>.
function highlightSnippet(snippet) {
let text = snippet.snippet;
let formattedText = text;
if (snippet.matchRanges) {
let parts = [];
let index = 0;
for (let match of snippet.matchRanges) {
let start = match.start || 0; // Default to 0 if omitted
let end = match.end;
if (index < start) { // Include any leading text before/between ranges
parts.push(text.slice(index, start));
}
parts.push('<span class="highlight">');
parts.push(text.slice(start, end));
parts.push('</span>');
index = end;
}
parts.push(text.slice(index)); // Include any trailing text after last range
formattedText = parts.join('');
}
return formattedText;
}
Biorąc pod uwagę ten fragment kodu:
{
"snippet": "This is an example snippet...",
"matchRanges": [
{
"start": 11,
"end": 18
}
]
}
Powstały ciąg znaków HTML wygląda tak:
This is an <span class="highlight">example</span> snippet...
Wyświetlane metadane
Użyj pola metadata, aby wyświetlić dodatkowe informacje o zwróconym elemencie, które mogą być istotne dla użytkowników. Pole metadata zawiera createTime i updateTime produktu, a także wszelkie powiązane z nim uporządkowane dane, które można zwrócić.
Aby wyświetlić dane strukturalne, użyj pola displayOptions. Pole displayOptions zawiera etykietę wyświetlaną dla typu obiektu i zestaw metalines. Każda linia metadanych to tablica etykiet wyświetlanych i par wartości skonfigurowanych w schemacie.
Pobieranie dodatkowych wyników
Aby pobrać dodatkowe wyniki, ustaw w żądaniu pole start na żądane przesunięcie. Rozmiar każdej strony możesz dostosować w polu pageSize.
Aby wyświetlić liczbę zwróconych produktów lub elementy sterujące stronicowaniem, które umożliwiają przechodzenie między zwróconymi produktami, użyj pola resultCount. W zależności od rozmiaru zbioru wyników podawana jest rzeczywista lub szacunkowa wartość.
Sortuj wyniki
Użyj pola sortOptions, aby określić kolejność zwracanych elementów. Wartość sortOptions to obiekt z 2 polami:
operatorName– operator właściwości uporządkowanych danych, według której ma być sortowana lista. W przypadku usług z wieloma operatorami możesz sortować tylko za pomocą głównego operatora równości.sortOrder– kierunek sortowania,ASCENDINGlubDESCENDING.
Trafność jest też używana jako dodatkowy klucz sortowania. Jeśli w zapytaniu nie określono kolejności sortowania, wyniki są sortowane tylko według trafności.
"sortOptions": {
"operatorName": "priority",
"sortOrder": "DESCENDING"
}
Dodaj filtry
Oprócz wyrażeń zapytań możesz dodatkowo ograniczyć wyniki, stosując filtry. Filtry możesz określić zarówno w aplikacji do wyszukiwania, jak i w żądaniu wyszukiwania.
Aby dodać filtry w żądaniu lub aplikacji do wyszukiwania, dodaj filtr w polu
dataSourceRestrictions.filterOptions[].
Istnieją 2 główne sposoby dalszego filtrowania źródła danych:
- Filtry obiektów za pomocą właściwości
filterOptions[].objectType– ograniczają dopasowywanie produktów do określonego typu zdefiniowanego w schemacie niestandardowym. - Filtry wartości – ograniczają pasujące elementy na podstawie operatora zapytania i podanej wartości.
Filtry złożone umożliwiają łączenie wielu filtrów wartości w wyrażenia logiczne, co pozwala tworzyć bardziej złożone zapytania.
W przykładzie schematu filmu możesz zastosować ograniczenie wiekowe na podstawie bieżącego użytkownika i ograniczyć dostępne filmy na podstawie oceny MPAA.
{
"query": "adventure",
"requestOptions": {
"searchApplicationId": "<search_app_id>"
},
"dataSourceRestrictions": [
{
"source": {
"name": "datasources/<data_source_id>"
},
"filterOptions": [
{
"objectType": "movie",
"filter": {
"compositeFilter": {
"logicOperator": "AND"
"subFilters": [
{
"compositeFilter": {
"logicOperator": "OR"
"subFilters": [
{
"valueFilter": {
"operatorName": "rated",
"value": {
"stringValue": "G"
}
}
},
{
"valueFilter": {
"operatorName": "rated",
"value": {
"stringValue": "PG"
}
}
}
]
}
]
}
}
}
]
}
]
}
Zawężanie wyników za pomocą aspektów
Aspekty to zindeksowane właściwości, które reprezentują kategorie służące do zawężania wyników wyszukiwania. Używaj aspektów, aby umożliwić użytkownikom interaktywne doprecyzowywanie zapytań i szybsze znajdowanie odpowiednich produktów.
Fasety można zdefiniować w aplikacji do wyszukiwania i zastąpić ustawieniami w zapytaniu.
Gdy żądasz aspektów, Cloud Search oblicza najczęściej występujące wartości żądanych właściwości wśród pasujących elementów. Te wartości są zwracane w odpowiedzi. Użyj tych wartości do utworzenia filtrów, które zawężą wyniki w kolejnych zapytaniach.
Typowy wzorzec interakcji z aspektami to:
- Wyślij początkowe zapytanie, w którym określisz, które właściwości mają być uwzględnione w wynikach aspektu.
- Wyświetl wyniki wyszukiwania i aspektów.
- Użytkownik wybiera co najmniej 1 wartość aspektu, aby zawęzić wyniki.
- Powtórz zapytanie z filtrem opartym na wybranych wartościach.
Aby na przykład umożliwić zawężanie zapytań dotyczących filmów według roku i oceny MPAA, w zapytaniu uwzględnij właściwość facetOptions.
"facetOptions": [
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "year"
},
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "rated"
}
]
Wyniki aspektów z polami opartymi na liczbach całkowitych
Możesz też dzielić wyniki żądań na grupy według pól opartych na liczbach całkowitych. Możesz na przykład oznaczyć właściwość liczby całkowitej o nazwie book_pages jako podlegającą fasetowaniu, aby zawęzić wyniki wyszukiwania książek o liczbie stron „100–200”.
Podczas konfigurowania schematu pola usługi z liczbą całkowitą ustaw wartość
isFacetable
na true i dodaj odpowiednie opcje podziału na przedziały do
integerPropertyOptions.
Dzięki temu każda właściwość, która może być używana jako aspekt liczbowy, ma zdefiniowane domyślne opcje podziału na przedziały.
Podczas definiowania logiki opcji podziału na przedziały podaj tablicę wartości przyrostowych
oznaczających zakresy. Jeśli na przykład użytkownik określi zakresy jako 2, 5, 10, 100, obliczane są aspekty dla <2, [2-5), [5-10), [10-100), >=100.
Możesz zastąpić aspekty oparte na liczbach całkowitych, definiując te same opcje podziału na przedziały w facetOptions żądaniu. W razie potrzeby Cloud Search używa opcji podziału na grupy zdefiniowanych w schemacie, gdy ani aplikacja do wyszukiwania, ani żądanie zapytania nie mają zdefiniowanych opcji aspektów. Aspekty zdefiniowane w zapytaniu mają wyższy priorytet niż aspekty zdefiniowane w aplikacji do wyszukiwania, a aspekty zdefiniowane w aplikacji do wyszukiwania mają wyższy priorytet niż aspekty zdefiniowane w schemacie.
Filtrowanie wyników według rozmiaru lub daty dokumentu
Możesz użyć operatorów zarezerwowanych, aby zawęzić wyniki wyszukiwania według rozmiaru pliku dokumentu (w bajtach) lub daty utworzenia lub modyfikacji dokumentu. Nie musisz definiować schematu niestandardowego, ale musisz określić wartość operatorName w FacetOptions aplikacji do wyszukiwania.
- Aby zastosować podział na grupy według rozmiaru dokumentu, użyj parametru
itemsizei określ opcje podziału na grupy. - Aby zastosować fasetowanie według daty utworzenia dokumentu, użyj
createddatetimestamp. - Aby zastosować fasetowanie według daty modyfikacji dokumentu, użyj
lastmodified.
Interpretowanie zasobników aspektów
Właściwość facetResults w odpowiedzi na zapytanie wyszukiwania zawiera dokładne żądanie filtra użytkownika w polu filter dla każdego elementu bucket.
W przypadku aspektów, które nie są oparte na liczbach całkowitych, facetResults zawiera wpis dla każdej żądanej właściwości. Dla każdej właściwości podana jest lista wartości lub zakresów, zwana buckets. Wartości występujące najczęściej są wyświetlane jako pierwsze.
Gdy użytkownik wybierze co najmniej 1 wartość do filtrowania, utwórz nowe zapytanie z wybranymi filtrami i ponownie wyślij je do interfejsu API.
Dodawanie sugestii
Użyj interfejsu suggest API, aby udostępniać automatyczne uzupełnianie zapytań na podstawie osobistej historii zapytań użytkownika, a także kontaktów i ich korpusu dokumentów.
Na przykład to wywołanie podaje sugestie dla częściowego wyrażenia jo.
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
Następnie możesz wyświetlić uzyskane sugestie w sposób odpowiedni dla Twojej aplikacji.