Tworzenie interfejsu wyszukiwania w interfejsie Query API

Query API udostępnia metody wyszukiwania i sugestii tworzenia interfejsu wyszukiwania lub umieszczania wyników wyszukiwania w aplikacji.

W przypadku aplikacji internetowych, które mają minimalne wymagania, rozważ użycie widżetu wyszukiwania. Więcej informacji znajdziesz w artykule Tworzenie interfejsu wyszukiwania za pomocą widżetu wyszukiwania.

Tworzenie interfejsu wyszukiwania

Utworzenie prostego interfejsu wyszukiwania wymaga kilku kroków:

  1. Konfigurowanie wyszukiwarki
  2. Wygeneruj dane logowania OAuth dla aplikacji
  3. Wysyłanie zapytania do indeksu
  4. Wyświetl wyniki zapytania

Możesz dodatkowo ulepszyć interfejs wyszukiwania za pomocą takich funkcji, jak strony, sortowanie, filtrowanie, aspekty i automatyczne sugestie.

Konfigurowanie wyszukiwarki

Musisz powiązać co najmniej jedną wyszukiwarkę, aby powiązać ją z każdym utworzonym interfejsem wyszukiwania. Wyszukiwarka zapewnia domyślne parametry zapytania, takie jak używane źródła danych, kolejność sortowania, filtry i aspekty. 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.

Wygeneruj dane 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 do aplikacji internetowej. Typ tworzonych danych logowania zależy od kontekstu, w którym jest używany interfejs API.

Użyj danych logowania, aby w imieniu użytkownika poprosić o autoryzację. Żądając 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 zapytania do indeksu

Użyj metody search, aby wyszukać coś w indeksie.

Każde żądanie musi zawierać 2 informacje: tekst query, do którego będą pasować elementy, oraz identyfikator searchApplicationId, który identyfikuje identyfikator aplikacji do wyszukiwania.

Ten fragment kodu zawiera zapytanie dotyczące źródła danych filmu Titanic:

{
  "query": "titanic",
  "requestOptions": {
    "searchApplicationId": "searchapplications/<search_app_id>"
  },
}

Wyświetl wyniki zapytania

Elementy interfejsu powinny wyświetlać co najmniej element title oraz link do pierwotnego elementu. Aby jeszcze bardziej pokazać wyniki wyszukiwania, możesz wykorzystać dodatkowe informacje, takie jak fragment i metadane.

Obsługa dodatkowych wyników

Domyślnie Cloud Search zwraca dodatkowe wyniki, gdy wyniki wyszukiwania zawierają niewystarczające wyniki. Pole queryInterpretation w odpowiedzi wskazuje, kiedy zwracane są dodatkowe wyniki. Jeśli zwracane są tylko dodatkowe wyniki, InterpretationType ma wartość REPLACE. Jeśli razem z wynikami dodatkowymi zostanie zwróconych kilka wyników oryginalnego zapytania, InterpretationType ma wartość BLEND. W obu przypadkach QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.

Gdy zwrócisz wyniki dodatkowe, rozważ umieszczenie tekstu, który wskazuje, że te wyniki zostały zwrócone. Na przykład w przypadku tagu REPLACE możesz zobaczyć tekst „Twoje zapytanie nie zwróciło żadnych wyników. Wyświetlanie wyników dla podobnych zapytań”.

W przypadku tagu BLEND możesz zobaczyć tekst „Twoje pierwotne zapytanie nie pasuje do wystarczającej liczby wyników. W tym wyniki dla podobnych zapytań”.

Obsługa wyników wyszukiwania osób

Cloud Search zwraca 2 rodzaje „wyników dotyczących osób”: dokumenty związane z osobą, której imię i nazwisko jest używane w zapytaniu, oraz informacje o pracowniku osoby, której imię i nazwisko jest użyte w zapytaniu. Drugi typ wyników jest funkcją wyszukiwarki osób w Cloud Search, a wyniki tego zapytania można znaleźć w polu structuredResults odpowiedzi interfejsu API zapytań:

{
  "results": [...],
  "structuredResults": [{
    "person": {...}
  }]
}

Wyłącz optymalizację, w tym dodatkowe wyniki

Domyślnie włączone są optymalizacje, np. wyniki uzupełniające. Możesz jednak wyłączyć wszystkie optymalizacje lub dodatkowe wyniki na poziomie wyszukiwarki i zapytania:

Wyróżnianie fragmentów

W przypadku zwróconych elementów zawierających zindeksowany tekst lub treść HTML zwracany jest fragment treści. Pomagają one użytkownikom określić znaczenie zwracanego produktu.

Jeśli fragment kodu zawiera wyszukiwane hasła, zwracany jest też co najmniej 1 zakres dopasowania określający lokalizację tych haseł.

Użyj matchRanges, aby wyróżnić pasujący tekst podczas renderowania wyników. Ten przykładowy kod JavaScript przekształca fragment kodu w znaczniki HTML z każdym pasującym zakresem opakowanym 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:

{
  "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świetlanie metadanych

W polu metadata możesz wyświetlić dodatkowe informacje o zwróconym produkcie, które mogą być przydatne dla użytkowników. Pole metadata zawiera createTime i updateTime elementu oraz wszelkie zwracane uporządkowane dane, które są z nim powiązane.

Aby wyświetlić uporządkowane dane, użyj pola displayOptions. Pole displayOptions zawiera etykietę wyświetlania typu obiektu oraz zestaw metalines. Każda metalina to tablica wyświetlanych etykiet i par wartości skonfigurowanych zgodnie ze schematem.

Pobierz dodatkowe wyniki

Aby pobrać dodatkowe wyniki, w polu start ustaw w polu odpowiednią wartość przesunięcia. Rozmiar każdej strony możesz dostosować za pomocą pola pageSize.

Aby wyświetlić liczbę zwróconych elementów lub wyświetlić elementy podziału na strony za pomocą zwróconych elementów, użyj pola resultCount. W zależności od wielkości zestawu wyników podana jest wartość rzeczywista lub szacowana.

Sortuj wyniki

W polu sortOptions możesz określić kolejność zwracanych produktów. Wartość sortOptions jest obiektem z dwoma polami:

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

Trafność jest też 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

Poza wyrażeniami zapytań możesz jeszcze bardziej ograniczyć wyniki, stosując filtry. 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ą dopasowane elementy do określonego typu zgodnie ze schematem niestandardowym.
  • Filtry wartości – ograniczają dopasowane elementy na podstawie operatora zapytania i podanej wartości.

Filtry złożone pozwalają łączyć wiele filtrów wartości w wyrażenia logiczne w bardziej złożonych zapytaniach.

W przykładzie schematu filmowego 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 indeksowane właściwości reprezentujące kategorie służące do zawężania wyników wyszukiwania. Używaj aspektów, aby pomóc użytkownikom w interaktywnym sprecyzowaniu zapytań i szybszym znajdowaniu odpowiednich informacji.

Aspekty można definiować w aplikacji wyszukiwarki i zastępować je ustawieniami w zapytaniu.

Gdy żądasz aspektów, Cloud Search oblicza najczęstsze wartości żądanych właściwości spośród pasujących elementów. Te wartości są zwracane w odpowiedzi. Wartości te służą do tworzenia filtrów, które zawężają wyniki w przypadku kolejnych zapytań.

Typowy wzorzec interakcji to aspekty:

  1. Napisz pierwsze zapytanie, które określa właściwości, które mają być uwzględnione w wynikach aspektu.
  2. Renderuj wyniki wyszukiwania i aspektu.
  3. Użytkownik wybiera co najmniej jedną wartość aspektu, aby zawęzić wyniki.
  4. Powtórz zapytanie z filtrem na podstawie wybranych wartości.

Aby na przykład włączyć zawężanie 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 aspektu z polami liczb całkowitych

Wyniki można też rozpatrywać za pomocą pól liczb całkowitych. Możesz np. oznaczyć właściwość liczbową o nazwie „book_pages” jako aspekt, aby zawęzić wyniki wyszukiwania książek o wartości „100–200”.

Po skonfigurowaniu schematu pola właściwości liczby całkowitej ustaw w polu isFacetable wartość true i dodaj odpowiednie opcje grupowania do elementu integerPropertyOptions. Dzięki temu każda usługa z liczbą całkowitą ma zdefiniowane domyślne opcje grupowania.

Podczas logiki opcji grupowania podaj tablicę wartości przyrostowych oznaczających zakresy. Jeśli na przykład użytkownik określi zakresy jako 2, 5, 10, 100, obliczone zostaną aspekty <2, [2-5), [5-10), [10-100), >=100.

Możesz zastąpić aspekty oparte na liczbach całkowitych, definiując te same opcje grupowania do facetOptions w żądaniu. W razie potrzeby Cloud Search używa opcji grupowania zdefiniowanych w schemacie, jeśli ani wyszukiwarka, ani zapytanie w zapytaniu nie mają skonfigurowanych opcji aspektu. Aspekty zdefiniowane w zapytaniu mają pierwszeństwo przed aspektami określonymi w wyszukiwarce, a aspekty określone w tej wyszukiwarce mają pierwszeństwo przed aspektami określonymi w schemacie.

Wyniki aspektu według rozmiaru lub daty dokumentu

Za pomocą zarezerwowanych operatorów możesz zawęzić wyniki wyszukiwania według rozmiaru pliku, liczby bajtów lub czasu utworzenia lub modyfikacji dokumentu. Nie musisz definiować schematu niestandardowego, ale musisz określić wartość operatorName w FacetOptions wyszukiwarki.

  • Do określania aspektów według rozmiaru dokumentu użyj itemsize i określ 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 lastmodified.

Interpretowanie zasobników aspektów

Właściwość facetResults w odpowiedzi na zapytanie zawiera precyzyjne żą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 jest podawana lista wartości lub zakresów o nazwie buckets. Wartości wyświetlane najczęściej pojawiają się jako pierwsze.

Gdy użytkownik wybierze co najmniej jedną wartość filtrowania, utwórz nowe zapytanie z użyciem wybranych filtrów i ponownie wyślij zapytanie do interfejsu API.

Dodaj sugestie

Korzystaj z interfejsu API suggest, aby zapewnić autouzupełnianie dla zapytań na podstawie osobistej historii zapytań użytkownika, a także kontaktów i korpusów dokumentów.

Na przykład następujące wywołanie zawiera częściową frazę jo.

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

Dzięki temu możesz wyświetlić wynikowe sugestie dla swojej aplikacji.