Tworzenie interfejsu wyszukiwania za pomocą interfejsu Query API

Interfejs Query API udostępnia metody wyszukiwania i proponowania, które umożliwiają tworzenie interfejsu wyszukiwania lub umieszczanie wyników wyszukiwania w aplikacji.

W przypadku aplikacji internetowych z minimalnymi wymaganiami rozważ użycie widżetu wyszukiwarki. Więcej informacji znajdziesz w artykule Tworzenie interfejsu wyszukiwania za pomocą widżetu wyszukiwania.

Tworzenie interfejsu wyszukiwania

Aby utworzyć minimalny interfejs wyszukiwania, musisz wykonać kilka czynności:

  1. Konfigurowanie wyszukiwarki
  2. Generowanie danych logowania OAuth dla aplikacji
  3. Wysyłanie zapytań do indeksu
  4. Wyświetlanie wyników zapytania

Interfejs wyszukiwania możesz dodatkowo ulepszać, korzystając z takich funkcji jak przewijanie, sortowanie, filtrowanie, aspekty i autouzupełnianie.

Konfigurowanie wyszukiwarki

Musisz utworzyć co najmniej 1 wyszukiwarkę, aby powiązać ją z każdym utworzonym przez siebie interfejsem wyszukiwania. Wyszukiwarka podaje domyślne parametry zapytania, na przykład ź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 Query API.

Więcej informacji o aplikacji wyszukiwarki znajdziesz w artykule Dostosowywanie wyszukiwania w Cloud Search.

Generowanie danych 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 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 żądania autoryzacji użyj 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

Do wyszukiwania w indeksie używaj metody search.

Każde żądanie musi zawierać 2 informacje: tekst query, do którego mają być dopasowywane elementy, oraz identyfikator searchApplicationId, który identyfikuje aplikację wyszukiwania, której ma być użyty.

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 wyszukiwarek powinny wyświetlać co najmniej element title, a także link do pierwotnego elementu. Wyświetlanie wyników wyszukiwania możesz dodatkowo udoskonalić, wykorzystując dodatkowe informacje, takie jak fragment kodu i metadane.

Obsługa wyników uzupełniających

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ą dodatkowe wyniki. Jeśli zwracane są tylko wyniki uzupełniające, opcja InterpretationType ma wartość REPLACE. Jeśli oprócz wyników uzupełniających zwrócono kilka wyników pierwotnego zapytania, parametr InterpretationType zostanie ustawiony na BLEND. W obu przypadkachQueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.

Gdy zwrócone zostaną jakieś wyniki uzupełniające, rozważ dodanie tekstu, który wskaże, że zwrócono wyniki uzupełniające. Na przykład w przypadku REPLACE możesz wyświetlić ciąg znaków „Twoje wyszukiwanie oryginalnego zapytania nie pasuje do żadnych wyników. Wyświetlam wyniki podobnych zapytań”.

W przypadku BLEND możesz wyświetlić ciąg znaków „Twoje wyszukiwanie oryginalnego zapytania nie pasuje do wystarczającej liczby wyników. W tym wyniki dotyczące podobnych zapytań”.

Obsługa wyników dotyczących osób

Cloud Search zwraca 2 typy „wyników dotyczących osób”: dokumenty związane z osobą, której nazwisko występuje w zapytaniu, oraz informacje o pracowniku, którego nazwisko występuje w zapytaniu. Ten drugi typ wyników jest funkcją funkcji wyszukiwania osób w Cloud Search, a wyniki takiego zapytania można znaleźć w polu structuredResults odpowiedzi interfejsu API:

{
  "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 osoby w ich organizacji. Wynik jest dostępny w polu structuredResults.

W przypadku zapytań dotyczących menedżera lub bezpośrednich podwładnych osoby odpowiedź zawiera assistCardProtoHolder w structuredResults. W rekordzie assistCardProtoHolder jest pole o nazwie cardType, które będzie równe RELATED_PEOPLE_ANSWER_CARD. assistCardProtoHolder zawiera kartę o nazwie relatedPeopleAnswerCard, która zawiera właściwą odpowiedź. Zawiera on subject (osobę, która została uwzględniona w zapytaniu) oraz relatedPeople, czyli zbiór osób powiązanych z tematem. Pole relationType zwraca wartość MANAGER lub DIRECT_REPORTS.

Poniższy kod pokazuje przykładową odpowiedź na zapytanie dopasowujące bezpośrednie raporty:

{
  "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 optymalizacje, takie jak wyniki uzupełniające, są włączone. Możesz jednak wyłączyć wszystkie optymalizacje lub tylko wyniki uzupełniające zarówno na poziomie aplikacji wyszukiwania, jak i na poziomie zapytania:

Wyróżnione fragmenty

W przypadku zwróconych elementów zawierających indeksowany tekst lub zawartość HTML zwracany jest fragment treści. Te treści pomagają użytkownikom określić trafność zwracanego produktu.

Jeśli w fragmentie znajdują się elementy zapytania, zwracane są też co najmniej 1 zakres dopasowania określający ich lokalizację.

Użyj matchRanges, aby wyróżnić tekst pasujący podczas renderowania wyników. Ten przykład kodu JavaScript zamienia fragment kodu w znaczniki HTML, a każdy zakres dopasowania jest ujęty w tag <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
    }
  ]
}

Wygenerowany ciąg znaków HTML:

This is an <span class="highlight">example</span> snippet...

Wyświetlane metadane

Użyj pola metadata, aby wyświetlić dodatkowe informacje o zwróconym produkcie, które mogą być przydatne dla użytkowników. Pole metadata zawiera identyfikatory createTime i updateTime produktu, a także wszystkie uporządkowane dane powiązane z tym produktem.

Aby wyświetlić dane strukturalne, użyj pola displayOptions. Pole displayOptions zawiera etykietę wyświetlania typu obiektu oraz zestaw metalines. Każda metalinia to tablica par etykiet wyświetlania i wartości zgodnie z konfiguracją w schemacie.

Pobieranie dodatkowych wyników

Aby pobrać dodatkowe wyniki, ustaw pole start w żądanym przesunięciu. Rozmiar każdej strony możesz dostosować za pomocą pola pageSize.

Aby wyświetlić liczbę zwróconych elementów lub elementy sterujące stroną, które umożliwiają przewijanie zwróconych elementów, użyj pola resultCount. W zależności od rozmiaru zbioru wyników podawana jest wartość rzeczywista lub oszacowana.

Sortuj wyniki

Aby określić kolejność zwracanych elementów, użyj pola sortOptions. Wartość sortOptions to obiekt z 2 polami:

  • operatorName – operator właściwości uporządkowanych danych, według której chcesz sortować. W przypadku właściwości z wieloma operatorami możesz sortować tylko za pomocą głównego operatora równości.
  • sortOrder – kierunek sortowania: ASCENDING lub DESCENDING.

Trafność jest też używana jako klucz sortowania dodatkowego. Jeśli w zapytaniu nie jest określony żaden porządek sortowania, wyniki są sortowane tylko według trafności.

"sortOptions": {
  "operatorName": "priority",
  "sortOrder": "DESCENDING"
}

Dodaj filtry

Oprócz wyrażeń zapytań możesz dodatkowo ograniczać wyniki, stosując filtry. Filtry możesz określić zarówno w aplikacji wyszukiwania, jak i w prośbie o wyszukiwanie.

Aby dodać filtry w prośbie lub aplikacji 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 elementów do określonego typu zgodnie z definicją 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 celu tworzenia bardziej złożonych zapytań.

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ężenie wyników za pomocą filtrów

Aspekty to zindeksowane właściwości, które reprezentują kategorie służące do doprecyzowania wyników wyszukiwania. Użyj filtrów, aby ułatwić użytkownikom interaktywne doprecyzowanie zapytań i szybsze znajdowanie odpowiednich produktów.

Kategorie można definiować w aplikacji wyszukiwania i zastępować ustawieniami w zapytaniu.

Podczas żądania 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 tworzenia filtrów, które zawężą wyniki w kolejnych zapytaniach.

Typowy wzór interakcji z aspektami:

  1. Wykonaj wstępne zapytanie, w którym określisz, które właściwości mają być uwzględnione w wynikach.
  2. Wyświetlanie wyników wyszukiwania i aspektów.
  3. Użytkownik wybiera co najmniej 1 wartość aspektu, aby zawęzić wyniki.
  4. Powtórz zapytanie z filtrem na podstawie wybranych wartości.

Aby na przykład umożliwić doprecyzowanie 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 typu liczba całkowita

Możesz też wysyłać żądania z wynikami z polami oparte na liczbach całkowitych. Możesz na przykład oznaczyć jako facetable właściwość typu integer o nazwie book_pages, aby zawęzić wyniki wyszukiwania dotyczące książek o „100–200” stron.

Podczas konfigurowania schematu pola właściwości liczbowej ustaw parametr isFacetable na true i dodaj do niego odpowiednie opcje grupowania integerPropertyOptions. Dzięki temu każda właściwość typu liczba całkowita ma zdefiniowane domyślne opcje grupowania.

Podczas definiowania logiki opcji grupowania podaj tablicę wartości przyrostowych oznaczających zakresy. Jeśli na przykład użytkownik końcowy poda zakresy takie jak 2, 5, 10, 100, obliczane są aspekty <2, [2-5), [5-10), [10-100) i >=100.

Możesz zastąpić atrybuty oparte na liczbach całkowitych, definiując w żądaniu te same opcje grupowania, co w przypadku atrybutów opartych na liczbach całkowitych: facetOptions. W razie potrzeby Cloud Search używa opcji grupowania zdefiniowanych w schemacie, gdy ani aplikacja wyszukiwania, ani żądanie zapytania nie mają zdefiniowanych opcji aspektów. Aspekty zdefiniowane w zapytaniu mają pierwszeństwo przed aspektami zdefiniowanymi w aplikacji wyszukiwania, a aspekty zdefiniowane w aplikacji wyszukiwania mają pierwszeństwo przed aspektami zdefiniowanymi w schemacie.

Wyświetlaj wyniki według rozmiaru lub daty dokumentu.

Możesz użyć operatorów zarezerwowanych, aby doprecyzować wyniki wyszukiwania według rozmiaru pliku mierzone w bajtach lub według daty utworzenia lub modyfikacji dokumentu. Nie musisz definiować schematu niestandardowego, ale musisz podać wartość operatorName w FacetOptions aplikacji wyszukiwania.

  • Aby utworzyć filtrowanie według rozmiaru dokumentu, użyj elementu itemsize i zdefiniuj opcje zbiorów.
  • Aby utworzyć filtrowanie według daty utworzenia dokumentu, użyj elementu createddatetimestamp.
  • Aby utworzyć filtrowanie według daty modyfikacji dokumentu, użyj lastmodified.

Interpretowanie zbiorów aspektów

Właściwość facetResults w odpowiedzi na zapytanie o informacje o wyszukiwaniu zawiera dokładne żądanie filtra użytkownika w polu filter dla każdego elementu w 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. W przypadku każdej właściwości podana jest lista wartości lub zakresów o nazwie buckets. Najczęściej występujące wartości pojawiają się jako pierwsze.

Gdy użytkownik wybierze co najmniej 1 wartość do filtrowania, utwórz nowe zapytanie z wybranymi filtrami i ponownie prześlij je do interfejsu API.

Dodawanie sugestii

Użyj interfejsu suggest API, aby zapewnić automatyczne uzupełnianie zapytań na podstawie historii zapytań użytkownika, a także kontaktów i korpusu dokumentów.

Na przykład wywołanie podaje sugestie dla częściowej frazy jo.

{
  "query": "jo",
  "requestOptions": {
    "searchApplicationId": "<search_app_id>",
    "peoplePhotoOptions": {
      "peoplePhotoUrlSizeInPx": 32
    },
    "timeZone": "America/Denver"
  }
}

Następnie możesz wyświetlać uzyskane sugestie w sposób odpowiedni do Twojej aplikacji.