Interfejs Query API udostępnia metody wyszukiwania i sugerowania, 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 o tworzeniu interfejsu wyszukiwania za pomocą widżetu wyszukiwania.
Tworzenie interfejsu wyszukiwania
Stworzenie minimalnego interfejsu wyszukiwania wymaga kilku kroków:
- Konfigurowanie wyszukiwarki
- Wygeneruj dane logowania OAuth dla aplikacji
- Wykonywanie zapytania dotyczącego indeksu
- Wyświetl wyniki zapytania
Możesz jeszcze bardziej ulepszyć interfejs wyszukiwania za pomocą takich funkcji jak stronicowanie, sortowanie, filtrowanie, aspekty i automatyczne sugestie.
Konfigurowanie wyszukiwarki
Musisz utworzyć co najmniej jedną wyszukiwarkę, która będzie powiązana z każdym tworzonym interfejsem wyszukiwania. Wyszukiwarka udostępnia domyślne parametry zapytania, takie jak używane źródła danych, kolejność sortowania, filtry i aspekty, których ma dotyczyć żądanie. W razie potrzeby możesz zastąpić te parametry za pomocą interfejsu Query API.
Więcej informacji o wyszukiwarkach znajdziesz w artykule Dostosowywanie działania wyszukiwania w Cloud Search.
Wygeneruj dane logowania OAuth dla aplikacji
Oprócz wykonania czynności opisanych w artykule Konfigurowanie dostępu do interfejsu Google Cloud Search API musisz też wygenerować dane logowania OAuth dla aplikacji internetowej. Typ tworzonych danych logowania zależy od kontekstu, w którym są używane dane logowania.
Użyj tych danych logowania, aby poprosić o autoryzację w imieniu użytkownika. Przy żądaniu autoryzacji użyj zakresu https://www.googleapis.com/auth/cloud_search.query
.
Więcej informacji o opcjach protokołu OAuth i bibliotekach klienta znajdziesz na stronie [Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"}).
Wykonywanie zapytania dotyczącego indeksu
Do wyszukiwania z użyciem indeksu użyj metody search
.
Każde żądanie musi zawierać 2 informacje: tekst query
, który ma dopasować elementy, oraz searchApplicationId
identyfikujący identyfikator, której ma użyć wyszukiwarka.
Ten fragment kodu zawiera zapytanie do źródła danych filmu Titanic:
{
"query": "titanic",
"requestOptions": {
"searchApplicationId": "searchapplications/<search_app_id>"
},
}
Wyświetl wyniki zapytania
Jako minimum interfejs wyszukiwania powinien wyświetlać element title
oraz link do elementu pierwotnego. Możesz jeszcze bardziej ulepszyć wyświetlanie wyników wyszukiwania, wykorzystując dodatkowe informacje w wynikach wyszukiwania, takie jak fragment i metadane.
Obsługa wyników dodatkowych
Domyślnie Cloud Search zwraca wyniki uzupełniające, gdy nie ma wystarczającej liczby wyników dla zapytania użytkownika. Pole queryInterpretation
w odpowiedzi wskazuje, kiedy zwracane są wyniki uzupełniające. Jeśli zwracane są tylko wyniki uzupełniające, pole InterpretationType
ma wartość REPLACE
. Jeśli zwracanych jest kilka wyników pierwotnego zapytania wraz z wynikami uzupełniającymi, pole InterpretationType
ma wartość BLEND
. W obu przypadkach QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY
.
Gdy zwracane są niektóre wyniki uzupełniające, podaj tekst, który wskazuje, że zostały one zwrócone. W przypadku zapytania REPLACE
możesz na przykład wyświetlić tekst „Twoje wyszukiwanie pierwotnego zapytania nie zwróciło żadnych wyników. Wyświetlam wyniki dla podobnych zapytań”.
W przypadku BLEND
może wyświetlić się tekst „Twoje pierwotne zapytanie nie zwróciło wystarczającej liczby wyników. Obejmuje to wyniki dla podobnych
zapytań”.
Zarządzaj wynikami dotyczącymi osób
Cloud Search zwraca 2 typy „wyników dotyczących osób”: dokumenty związane z osobą, której imię i nazwisko jest użyte w zapytaniu, oraz informacje o pracowniku w przypadku osoby, której imię i nazwisko zostało użyte w zapytaniu. Ten drugi typ wyników jest funkcją wyszukiwarki osób w Cloud Search. Wyniki takiego zapytania można znaleźć w polu structuredResults
odpowiedzi interfejsu API zapytania:
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
Dopasowywanie bezpośrednich raportów
Dopasowywanie raportów bezpośrednich to dostępna w Cloud Search funkcja Wyszukiwarki osób, która umożliwia użytkownikom wyświetlanie bezpośrednich podwładnych osób w organizacji.
Wynik jest dostępny w polu structuredResults
.
W przypadku zapytań o menedżera lub bezpośrednich podwładnych odpowiedź zawiera assistCardProtoHolder
w elemencie structuredResults
. assistCardProtoHolder
zawiera pole o nazwie cardType
, które ma wartość równą RELATED_PEOPLE_ANSWER_CARD
. assistCardProtoHolder
zawiera kartę o nazwie relatedPeopleAnswerCard
, która zawiera rzeczywistą odpowiedź.
Zawiera on subject
(osobę uwzględnioną w zapytaniu) i relatedPeople
, czyli zbiór osób związanych z danym tematem. Pole relationType
zwraca wartość MANAGER
lub DIRECT_REPORTS
.
Ten kod zawiera przykładową odpowiedź na zapytanie pasujące do bezpośredniego raportu:
{
"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łącz optymalizacje, w tym wyniki uzupełniające
Domyślnie optymalizacje, takie jak wyniki uzupełniające, są włączone. Można jednak wyłączyć wszystkie optymalizacje lub tylko wyniki uzupełniające zarówno na poziomie wyszukiwarki, jak i zapytania:
Aby wyłączyć wszystkie optymalizacje na poziomie wyszukiwarki, w tym wyniki uzupełniające, synonimy i poprawki pisowni, ustaw w wyszukiwarkach opcję
QueryInterpretationConfig.force_verbatim_mode
natrue
.Aby wyłączyć wszystkie optymalizacje na poziomie zapytania, w tym wyniki uzupełniające, synonimy i poprawki pisowni, ustaw w zapytaniu parametr
QueryInterpretationOptions.enableVerbatimMode
natrue
.Aby wyłączyć wyniki uzupełniające na poziomie wyszukiwarki, ustaw w zapytaniu parametr
QueryInterpretationOptions.forceDisableSupplementalResults
natrue
.Aby wyłączyć wyniki uzupełniające na poziomie zapytania, ustaw w zapytaniu parametr
QueryInterpretationOptions.disableSupplementalResults
natrue
.
Fragmenty z najciekawszymi momentami
W przypadku zwróconych elementów zawierających indeksowany tekst lub zawartość HTML zwracany jest fragment treści. Pomagają one użytkownikom określić trafność zwracanego produktu.
Jeśli fragment kodu zawiera wyszukiwane hasła, zwracany jest co najmniej 1 zakres dopasowania identyfikujący lokalizację hasła.
Użyj przycisku matchRanges
, aby wyróżnić pasujący tekst podczas renderowania wyników. Poniższy przykładowy kod JavaScript konwertuje fragment kodu na znaczniki HTML z każdym pasującym zakresem umieszczonym w tagu <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ę fragment kodu:
{
"snippet": "This is an example snippet...",
"matchRanges": [
{
"start": 11,
"end": 18
}
]
}
Powstały ciąg znaków HTML to:
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 atrybuty createTime
i updateTime
elementu, a także wszystkie powiązane z nim uporządkowane dane, które można zwrócić.
Aby wyświetlić uporządkowane dane, użyj pola displayOptions
. Pole displayOptions
zawiera etykietę wyświetlaną typu obiektu i zbiór metalines
. Każda metalina jest tablicą etykiet wyświetlanych i par wartości skonfigurowanych w schemacie.
Pobierz dodatkowe wyniki
Aby uzyskać dodatkowe wyniki, ustaw w polu start
w żądaniu określone przesunięcie. Rozmiar każdej strony możesz dostosować za pomocą pola pageSize
.
Aby wyświetlić liczbę zwróconych elementów lub wyświetlić elementy sterujące stronicowaniem na poszczególnych zwróconych elementach, użyj pola resultCount
. W zależności od rozmiaru zbioru wyników podajesz wartość rzeczywistą lub szacowaną.
Sortuj wyniki
W polu sortOptions
możesz 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órego odbywa się sortowanie. W przypadku właściwości z wieloma operatorami możesz sortować dane tylko za pomocą głównego operatora równości.sortOrder
– kierunek sortowania:ASCENDING
lubDESCENDING
.
Trafność służy też jako dodatkowy klucz sortowania. Jeśli w zapytaniu nie określono kolejności sortowania, wyniki są pozycjonowane tylko według trafności.
"sortOptions": {
"operatorName": "priority",
"sortOrder": "DESCENDING"
}
Dodawanie filtrów
Oprócz wyrażeń zapytań możesz jeszcze bardziej ograniczać wyniki za pomocą filtrów. Filtry możesz określić zarówno w wyszukiwarce, jak i w żądaniu wyszukiwania.
Aby dodać filtry w żądaniu lub wyszukiwarce, 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ą pasujące elementy do określonego typu określonego w schemacie niestandardowym. - Filtry wartości – ograniczają dopasowanie elementów na podstawie operatora zapytania i podanej wartości.
Filtry złożone umożliwiają łączenie wielu filtrów wartości w wyrażenia logiczne w przypadku bardziej złożonych zapytań.
W przykładowym schemacie 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 właściwości zindeksowane, które reprezentują kategorie do zawężania wyników wyszukiwania. Dzięki aspektom użytkownicy mogą interaktywnie zawężać zapytania i szybciej znajdować odpowiednie elementy.
Aspekty można definiować w wyszukiwarce i zastępować ustawieniami w zapytaniu.
Gdy żądasz aspektów, Cloud Search oblicza najczęstsze wartości żądanych właściwości wśród pasujących elementów. Te wartości są zwracane w odpowiedzi. Na podstawie tych wartości możesz tworzyć filtry, które zawężają wyniki w kolejnych zapytaniach.
Typowy wzorzec interakcji z aspektami to:
- Wykonaj wstępne zapytanie określające, które właściwości mają być uwzględnione w wynikach aspektu.
- Renderuj wyniki wyszukiwania i aspektów.
- Użytkownik wybiera co najmniej 1 wartość aspektu, aby zawęzić wyniki.
- Powtórz zapytanie z użyciem filtra opartego na wybranych wartościach.
Aby np. zawęzić zapytania dotyczące filmów według roku i oceny MPAA, dodaj do zapytania właściwość facetOptions
.
"facetOptions": [
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "year"
},
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "rated"
}
]
Wyniki aspektu z polami zawierającymi liczby całkowite
Możesz też ustalać aspekty żądań za pomocą pól zawierających liczby całkowite. Możesz na przykład oznaczyć właściwość liczby całkowitej o nazwie book_pages
jako dostępną do aspektu, aby zawęzić wyniki wyszukiwania książek ze stronami o wartości od 100 do 200 znaków.
Po skonfigurowaniu schematu pola usługi z liczbą całkowitą ustaw isFacetable
na true
i dodaj odpowiednie opcje zasobnika w integerPropertyOptions
.
Dzięki temu każda właściwość z możliwością przedstawiania liczb całkowitych ma zdefiniowane domyślne opcje grupowania.
Definiując logikę opcji zasobnika, podaj tablicę przyrostowych wartości określających zakresy. Jeśli na przykład użytkownik określi zakresy jako 2, 5, 10, 100
, obliczone zostaną aspekty dla <2
, [2-5)
, [5-10)
, [10-100)
i >=100
.
Możesz zastąpić aspekty w liczbach całkowitych, definiując te same opcje grupowania w żądaniu facetOptions
. W razie potrzeby Cloud Search używa opcji grupowania zdefiniowanych w schemacie, gdy ani w wyszukiwarce, ani w żądaniu zapytania nie są zdefiniowane opcje aspektu. Aspekty zdefiniowane w zapytaniu mają pierwszeństwo przed aspektami zdefiniowanymi w wyszukiwarce, a aspekty zdefiniowane w wyszukiwarce mają pierwszeństwo przed aspektami zdefiniowanymi w schemacie.
Wyniki aspektu według rozmiaru lub daty dokumentu
Korzystając z operatorów zarezerwowanych, możesz zawężać wyniki wyszukiwania według rozmiaru pliku dokumentu, wyrażonego w bajtach lub według daty utworzenia bądź zmodyfikowania dokumentu. Nie musisz definiować schematu niestandardowego, ale musisz określić wartość operatorName
w FacetOptions
wyszukiwarki.
- Aby ustawić podział na aspekty według rozmiaru dokumentu, użyj właściwości
itemsize
i zdefiniuj opcje grupowania. - Do określania aspektów według daty utworzenia dokumentu użyj
createddatetimestamp
. - Do określania aspektów według daty modyfikacji dokumentu użyj wartości
lastmodified
.
Interpretowanie zasobników aspektów
Właściwość facetResults
w odpowiedzi na zapytanie zawiera dokładne żądanie filtra użytkownika w polu filter
dla każdego obiektu 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. Każda właściwość zawiera listę wartości lub zakresów o nazwie buckets
. Wartości, które pojawiają się najczęściej, są podawane jako pierwsze.
Gdy użytkownik wybierze co najmniej 1 wartość filtra, utwórz nowe zapytanie z wybranymi filtrami i ponownie prześlij zapytanie do interfejsu API.
Dodaj sugestie
Interfejs API suggest umożliwia autouzupełnianie w przypadku zapytań na podstawie osobistej historii zapytań użytkownika, a także kontaktów i ich korpusu dokumentów.
Na przykład to wywołanie zawiera sugestie częściowego wyrażenia jo.
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
Otrzymane sugestie możesz następnie wyświetlać odpowiednio do swojej aplikacji.