Query API udostępnia metody wyszukiwania i sugerowania do tworzenia interfejsu wyszukiwania lub umieszczania 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.
Utwórz interfejs wyszukiwania
Stworzenie minimalnego interfejsu wyszukiwania wymaga kilku etapów:
- Konfigurowanie wyszukiwarki
- Wygeneruj dane logowania OAuth dla aplikacji
- Tworzenie zapytania dotyczącego indeksu
- Wyświetl wyniki zapytania
Możesz 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 utworzonym interfejsem wyszukiwania. Wyszukiwarka udostępnia parametry domyślne zapytania, np. źródła danych, które mają zostać użyte, kolejność sortowania, filtry i aspekty. W razie potrzeby możesz zastąpić te parametry za pomocą interfejsu Query API.
Więcej informacji o wyszukiwarkach znajdziesz w artykule na temat dostosowywania wyszukiwania w Cloud Search.
Wygeneruj dane logowania OAuth dla aplikacji
Oprócz czynności opisanych w sekcji 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 jakim jest używany interfejs API.
Użyj danych logowania, aby poprosić o autoryzację w imieniu użytkownika. Podczas wysyłania prośby o autoryzację 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"}.
Tworzenie zapytania dotyczącego indeksu
Za pomocą metody search
możesz przeprowadzać wyszukiwania w indeksie.
Każde żądanie musi zawierać 2 informacje: tekst query
służący do dopasowywania elementów oraz identyfikator searchApplicationId
identyfikujący identyfikator wyszukiwarki, który ma zostać użyty.
Ten fragment kodu zawiera zapytanie do źródła danych o filmie „Titanic”:
{
"query": "titanic",
"requestOptions": {
"searchApplicationId": "searchapplications/<search_app_id>"
},
}
Wyświetl wyniki zapytania
Interfejsy wyszukiwania powinny wyświetlać co najmniej element title
oraz link do oryginalnego elementu. Możesz jeszcze bardziej poprawić wyświetlanie wyników wyszukiwania, wykorzystując dodatkowe informacje obecne w wynikach wyszukiwania, takie jak fragment kodu i metadane.
Obsługa wyników uzupełniających
Domyślnie Cloud Search zwraca wyniki uzupełniające, gdy liczba wyników jest niewystarczająca 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, InterpretationType
ma wartość REPLACE
. Jeśli zostanie zwróconych kilka wyników pierwotnego zapytania wraz z wynikami uzupełniającymi, InterpretationType
ma wartość BLEND
. W obu przypadkach QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY
.
W przypadku zwrócenia wyników uzupełniających możesz podać tekst informujący o ich zwróceniu. W przypadku REPLACE
możesz na przykład wyświetlić ciąg „Pierwotne zapytanie nie zwróciło żadnych wyników. Wyświetlam wyniki podobnych zapytań”.
W przypadku BLEND
możesz wyświetlić tekst „Pierwotne zapytanie nie zwróciło wystarczającej liczby wyników. Obejmuje to wyniki podobnych zapytań”.
Obsługa wyników wyszukiwania osób
Cloud Search zwraca 2 rodzaje „wyników wyszukiwania osób”: dokumenty związane z osobą, której imię i nazwisko zostało użyte w zapytaniu, oraz informacje o pracowniku w przypadku osoby, której imię i nazwisko jest użyte w zapytaniu. Drugi typ wyniku jest funkcją wyszukiwarki osób w Cloud Search, a wyniki takiego zapytania można znaleźć w polu structuredResults
odpowiedzi interfejsu Query API:
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
Dopasowywanie bezpośrednich raportów
Bezpośrednie dopasowywanie raportów to funkcja wyszukiwarki osób w Cloud Search, która umożliwia użytkownikom przeglądanie bezpośrednich podwładnych osób w ich organizacji.
Wynik jest dostępny w polu structuredResults
.
Odpowiedź na pytanie o menedżera lub bezpośrednich podwładnych danej osoby zawiera w polu structuredResults
kolumnę assistCardProtoHolder
. assistCardProtoHolder
zawiera pole o nazwie cardType
, które ma wartość RELATED_PEOPLE_ANSWER_CARD
. assistCardProtoHolder
zawiera kartę relatedPeopleAnswerCard
, która zawiera faktyczną odpowiedź.
Zawiera on subject
(osobę uwzględniony w zapytaniu) i relatedPeople
, czyli zbiór osób powiązanych z danym tematem. Pole relationType
zwraca wartość MANAGER
lub DIRECT_REPORTS
.
Poniższy kod pokazuje przykładową odpowiedź na żądanie bezpośredniego raportu pasującego do zapytania:
{
"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 włączone są optymalizacje, takie jak wyniki uzupełniające. Możesz jednak wyłączyć wszystkie optymalizacje lub tylko wyniki uzupełniające na poziomie wyszukiwarki i zapytania:
Aby wyłączyć wszystkie optymalizacje na poziomie wyszukiwarki, w tym wyniki uzupełniające, synonimy i poprawki pisowni, ustaw w wyszukiwarce parametr
QueryInterpretationConfig.force_verbatim_mode
natrue
.Aby wyłączyć wszystkie optymalizacje na poziomie zapytania, w tym wyniki dodatkowe, synonimy i poprawki pisowni, wpisz w zapytaniu parametr
QueryInterpretationOptions.enableVerbatimMode
natrue
.Aby wyłączyć wyniki uzupełniające na poziomie wyszukiwarki, wpisz wartość
QueryInterpretationOptions.forceDisableSupplementalResults
w zapytaniu natrue
.Aby wyłączyć wyniki uzupełniające na poziomie zapytania, wpisz wartość
QueryInterpretationOptions.disableSupplementalResults
natrue
w zapytaniu.
Fragmenty z najciekawszymi momentami
W przypadku zwróconych elementów zawierających indeksowany tekst lub treść HTML zwracany jest fragment treści. Pomagają one użytkownikom określić trafność zwróconego elementu.
Jeśli fragment kodu zawiera wyszukiwane hasła, zwracany jest również co najmniej jeden zakres dopasowania określający ich lokalizację.
Użyj matchRanges
, aby wyróżnić pasujący tekst podczas renderowania wyników. Ten przykład kodu w języku JavaScript przekształca fragment kodu w znaczniki HTML, a każdy pasujący zakres znajduje się 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ę ten fragment:
{
"snippet": "This is an example snippet...",
"matchRanges": [
{
"start": 11,
"end": 18
}
]
}
Powstały ciąg HTML wygląda tak:
This is an <span class="highlight">example</span> snippet...
Wyświetl metadane
W polu metadata
możesz wyświetlać dodatkowe informacje o zwracanym elemencie, które mogą być istotne dla użytkowników. Pole metadata
zawiera wartości createTime
i updateTime
elementu, a także wszelkie 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 metawiersz jest tablicą etykiet wyświetlanych i par wartości skonfigurowane w schemacie.
Pobieranie dodatkowych wyników
Aby pobrać dodatkowe wyniki, ustaw żądane przesunięcie w polu start
w żądaniu. Za pomocą pola pageSize
możesz dostosować rozmiar każdej strony.
Aby wyświetlić liczbę zwróconych elementów lub wyświetlić opcje stronicowania na zwróconych elementach, użyj pola resultCount
. W zależności od rozmiaru zestawu wyników dostarczana jest wartość rzeczywista lub szacunkowa.
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 usług z wieloma operatorami możesz sortować tylko za pomocą głównego operatora równości.sortOrder
– kierunek sortowania:ASCENDING
lubDESCENDING
.
Trafność jest również używana 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 dodatkowo ograniczyć wyniki, stosując filtry. Filtry można określić zarówno w wyszukiwarce, jak i w żądaniu wyszukiwania.
Aby dodać filtry w żądaniu lub wyszukiwarce, dodaj filtr w polu dataSourceRestrictions.filterOptions[]
.
Są 2 główne sposoby dalszego filtrowania źródła danych:
- Filtry obiektów za pomocą właściwości
filterOptions[].objectType
– ogranicza dopasowanie elementów do określonego typu określonego w niestandardowym schemacie. - Filtry wartości – ogranicza 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 przeznaczone do 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ęź wyniki za pomocą aspektów
Aspekty to właściwości indeksowane, które reprezentują kategorie w celu zawężenia wyników wyszukiwania. Używaj aspektów, aby pomóc użytkownikom w interaktywnym doprecyzowaniu zapytań i szybciej znajdować odpowiednie produkty.
Aspekty można definiować w aplikacji wyszukiwarki i zastępować ustawienia w zapytaniu.
Podczas wysyłania żądania aspektów Cloud Search oblicza najczęstsze wartości dla żądanych właściwości spośród pasujących elementów. Wartości te są zwracane w odpowiedzi. Wartości te mogą posłużyć do utworzenia filtrów, które zawężają wyniki kolejnych zapytań.
Typowy wzorzec interakcji z aspektami to:
- Utwórz wstępne zapytanie określające, które właściwości mają być uwzględnione w wynikach aspektu.
- Renderuj wyniki wyszukiwania i aspektu.
- Użytkownik wybiera co najmniej jedną wartość aspektu, aby zawęzić wyniki.
- Powtórz zapytanie z użyciem filtra na podstawie wybranych wartości.
Aby np. umożliwić zawężenie zapytań o filmy według roku i oceny MPAA, uwzględnij w zapytaniu 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ż podawać wyniki żądań aspektów za pomocą pól opartych na liczbach całkowitych. Możesz na przykład oznaczyć właściwość liczby całkowitej o nazwie book_pages
jako możliwość aspektu, aby zawęzić wyniki wyszukiwania książek o liczbie stron „100–200”.
Po skonfigurowaniu schematu pola właściwości liczby całkowitej ustaw isFacetable
na true
i dodaj odpowiednie opcje zasobnika do integerPropertyOptions
.
Dzięki temu każda właściwość liczby całkowitej ma zdefiniowane domyślne opcje podziału na segmenty.
Definiując logikę opcji podziału na segmenty, podaj tablicę wartości przyrostowych określających zakresy. Jeśli na przykład użytkownik określi zakresy jako 2, 5, 10, 100
, obliczane są aspekty <2
, [2-5)
, [5-10)
, [10-100)
i >=100
.
Aby zastąpić aspekty oparte na liczbach całkowitych, możesz zdefiniować te same opcje podziału na segmenty w żądaniu facetOptions
. W razie potrzeby Cloud Search używa opcji zasobnika zdefiniowanych w schemacie, gdy ani aplikacja wyszukiwania, ani żądanie zapytania nie mają zdefiniowanych opcji 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 aspektów według rozmiaru dokumentu lub daty
Możesz używać zarezerwowanych operatorów, aby zawężać wyniki wyszukiwania według rozmiaru pliku dokumentu (mierzonego w bajtach) lub daty utworzenia lub modyfikacji dokumentu. Nie musisz określać schematu niestandardowego, ale musisz określić wartość operatorName
w regule FacetOptions
w wyszukiwarce.
- Do określania aspektów według rozmiaru dokumentu użyj funkcji
itemsize
i określ opcje podziału na segmenty. - Aby określić aspekty według daty utworzenia dokumentu, użyj
createddatetimestamp
. - Do określania aspektów według daty modyfikacji dokumentu użyj
lastmodified
.
Interpretowanie zasobników aspektów
Właściwość facetResults
w odpowiedzi na zapytanie zawiera dokładne żądanie filtra przesłane przez użytkownika w polu filter
w poszczególnych 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 o nazwie buckets
. Wartości, które występują najczęściej, pojawiają się jako pierwsze.
Gdy użytkownik wybierze co najmniej 1 wartość do filtrowania, utwórz nowe zapytanie z wykorzystaniem wybranych filtrów i ponownie wyślij zapytanie do interfejsu API.
Dodaj sugestie
Używaj interfejsu API suggest, aby włączać autouzupełnianie w przypadku zapytań na podstawie osobistej historii zapytań użytkownika oraz kontaktów i zbioru dokumentów.
Na przykład to wywołanie zawiera sugestie dotyczące częściowego wyrażenia jo.
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
Uzyskane sugestie możesz potem wyświetlić w zależności od aplikacji.