Tworzenie interfejsu wyszukiwania za pomocą interfejsu Query API

Interfejs Query API udostępnia metody wyszukiwania i sugerowania lub osadzania wyników wyszukiwania w aplikacji.

W przypadku aplikacji internetowych o minimalnych wymaganiach rozważ użycie widżetu wyszukiwania. Więcej informacji: Tworzenie interfejsu wyszukiwania za pomocą widżetu wyszukiwania

Tworzenie interfejsu wyszukiwania

Stworzenie minimalnego interfejsu wyszukiwania wymaga kilku kroków:

  1. Konfigurowanie wyszukiwarki
  2. Wygeneruj dane logowania OAuth dla aplikacji
  3. Wykonywanie zapytania dotyczącego indeksu
  4. Wyświetl wyniki zapytania

Interfejs wyszukiwania można dodatkowo ulepszyć m.in. za pomocą funkcji stronicowania, sortowania, filtrowania, aspektów i automatycznych sugestii.

Konfigurowanie wyszukiwarki

Musisz utworzyć co najmniej jedną wyszukiwarkę, która będzie powiązana z każdą z nich tworzonego przez siebie interfejsu wyszukiwania. Wyszukiwarka domyślnie udostępnia parametrów zapytania, takich jak źródła danych, kolejność sortowania filtry i aspekty, o które chcesz poprosić. W razie potrzeby możesz zastąpić te parametry za pomocą interfejsu API zapytań.

Więcej informacji o wyszukiwarkach znajdziesz pod adresem Dostosowywanie wyszukiwania w Cloud Search

Wygeneruj dane logowania OAuth dla aplikacji

Poza wykonaniem kroków opisanych w Skonfiguruj dostęp 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 są używane dane logowania.

Użyj tych danych logowania, aby poprosić o autoryzację w imieniu użytkownika. Użyj zakres https://www.googleapis.com/auth/cloud_search.query podczas żądania autoryzacji.

Więcej informacji o opcjach protokołu OAuth i bibliotekach klienta znajdziesz w artykule [Platforma tożsamości Google](https://developers.google.com/identity/choose-auth{: .external target="_blank"}).

Wykonywanie zapytania dotyczącego indeksu

Korzystanie z search do wyszukiwania w indeksie.

Każde żądanie musi zawierać 2 informacje: tekst query w celu dopasowania elementów do oraz searchApplicationId identyfikującego identyfikator wyszukiwarki, której chcesz użyć.

Ten fragment kodu zawiera zapytanie do źródła danych filmu Titanic:

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

Wyświetl wyniki zapytania

Interfejsy wyszukiwania powinny wyświetlać przynajmniej element title jako oraz link do oryginalnego elementu. Można jeszcze bardziej poprawić wygląd z wykorzystaniem dodatkowych informacji w wynikach wyszukiwania. np. fragmentu i metadanych.

Obsługa wyników dodatkowych

Domyślnie Cloud Search zwraca wyniki uzupełniające, jeśli: niewystarczająca ilość wyników dla zapytania użytkownika. queryInterpretation w odpowiedzi wskazuje, kiedy zwracane są wyniki uzupełniające. Jeśli tylko zwracane są wyniki uzupełniające, dla którego InterpretationType ma wartość REPLACE. Jeśli zwracanych jest kilka wyników pierwotnego zapytania wraz z dodatkowymi wyników, kolumna 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, możesz podać tekst co wskazuje, że zostały zwrócone dodatkowe wyniki. Na przykład w przypadku REPLACE, możesz zobaczyć tekst „Twoje wyszukiwanie oryginalnego zapytania nie nie pasuje do żadnych wyników. Wyświetlam wyniki dla podobnych zapytań”.

W przypadku BLEND może wyświetlić się tekst „Twoje wyszukiwanie oryginalne zapytanie nie dało wystarczającej liczby wyników. W tym wyniki dla podobnych zapytań”.

Zarządzaj wynikami dotyczącymi osób

Cloud Search zwraca 2 typy „wyników dotyczących osób”: dokumenty powiązane z osoba, której imię i nazwisko zostało użyte w zapytaniu oraz w informacjach o pracowniku danej osoby imię i nazwisko użyte w zapytaniu. Ten drugi typ wyniku to funkcja Cloud Wyszukiwarki osób w wyszukiwarce, a wyniki takiego zapytania można znaleźć tutaj: structuredResults w odpowiedzi interfejsu API zapytania:

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

Dopasowywanie bezpośrednich raportów

Dopasowanie raportów bezpośrednich to funkcja Wyszukiwarki osób w Cloud Search, która użytkownicy widzą bezpośrednie podwładny osoby w swojej organizacji. Wynik jest dostępny w polu structuredResults.

W przypadku zapytań o menedżera lub bezpośrednich podwładnych odpowiedź zawiera assistCardProtoHolder w: structuredResults. assistCardProtoHolder ma pole o nazwie cardType, które będzie równe RELATED_PEOPLE_ANSWER_CARD assistCardProtoHolder zawiera kartę o nazwie relatedPeopleAnswerCard, który zawiera rzeczywistą odpowiedź. Zawiera on subject (osobę uwzględnioną w zapytaniu) oraz relatedPeople, czyli zbiór osób związanych z danym tematem. Pole relationType zwraca wartość MANAGER lub DIRECT_REPORTS.

Poniższy kod zawiera przykładową odpowiedź na potrzeby bezpośredniego dopasowania raportów zapytanie:

{
  "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żesz: należy jednak wyłączyć wszystkie optymalizacje lub tylko wyniki uzupełniające na poziom aplikacji i zapytania:

Fragmenty z najciekawszymi momentami

W przypadku zwracanych elementów zawierających indeksowany tekst lub treść HTML fragment kodu treści. Pomagają one użytkownikom określić trafność zwracanego produktu.

Jeśli fragment kodu zawiera wyszukiwane hasła, oznacza to, zwracana jest również lokalizacja hasła.

Użyj komponentu matchRanges, aby podświetlić pasujący tekst podczas renderowania wyniki. Następujący przykładowy kod JavaScript przekształca fragment kodu na Znaczniki HTML z każdym pasującym zakresem 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

Korzystanie z metadata pole do wyświetlania dodatkowych informacji o zwróconym produkcie, które mogą być istotne użytkownikom. Pole metadata zawiera zmienne createTime i updateTime produktu oraz wszystkie powiązane uporządkowane dane podlegające zwrotom z danym produktem.

Aby wyświetlić uporządkowane dane, użyj komponentu displayOptions . Pole displayOptions zawiera etykietę wyświetlaną typu obiektu oraz metalines. Każda metalina jest tablicą etykiet displayowych pary wartości skonfigurowane w tym schemacie.

Pobierz dodatkowe wyniki

Aby pobrać dodatkowe wyniki, ustaw start w żądaniu ustaw żądane przesunięcie. Możesz dostosować rozmiar na każdej stronie z tagiem pageSize .

Aby wyświetlić liczbę zwróconych elementów lub wyświetlić elementy sterujące stronicowaniem przeglądania zwróconych produktów, użyj resultCount . W zależności od rozmiaru zbioru wyników może to być rzeczywista wartość lub zostanie podana wartość szacowana.

Sortuj wyniki

Korzystanie z sortOptions aby określić kolejność zwracanych elementów. Wartość sortOptions to obiekt z dwoma 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ć tylko według głównej równości .
  • sortOrder – kierunek sortowania: ASCENDING lub DESCENDING.

Trafność służy też jako dodatkowy klucz sortowania. Jeśli nie określono kolejności sortowania wyniki są wyświetlane tylko według trafności.

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

Dodaj filtry

Oprócz wyrażeń zapytań możesz jeszcze bardziej ograniczać wyniki, stosując: filtry. Filtry możesz określić zarówno w wyszukiwarka jak również w żądaniu wyszukiwania.

Aby dodać filtry w żądaniu lub wyszukiwarce, dodaj go w sekcji 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ą dopasowania elementów do określonego typu zdefiniowanego w schemacie niestandardowym.
  • Filtry wartości – ogranicza dopasowanie elementów na podstawie operator zapytania i podaną wartość.

Filtry złożone Łącz wiele filtrów wartości w wyrażenia logiczne, aby zwiększyć złożonych zapytań.

W przykładzie schematu filmu można zastosować ograniczenie wiekowe na podstawie bieżącego użytkownika i ograniczyć dostępność filmów 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 wyszukiwania wyników. Za pomocą aspektów można ułatwić użytkownikom interaktywne zawężanie zapytań odpowiednie produkty.

Aspekty można zdefiniować w wyszukiwarki. i zastąpiony ustawieniami w zapytaniu.

Gdy żądasz aspektów, Cloud Search oblicza najczęstsze wartości dla właściwości wśród pasujących elementów. Te są zwracane w odpowiedzi. Użyj tych wartości do tworzenia filtrów które zawężają wyniki w kolejnych zapytaniach.

Typowy wzorzec interakcji z aspektami to:

  1. Wykonaj wstępne zapytanie określające, które właściwości mają zostać uwzględnione w aspektie wyników.
  2. Renderuj wyniki wyszukiwania i aspektów.
  3. Użytkownik wybiera co najmniej 1 wartość aspektu, aby zawęzić wyniki.
  4. Powtórz zapytanie z użyciem filtra opartego na wybranych wartościach.
.

Aby na przykład doprecyzować zapytania dotyczące filmów 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 zawierającymi liczby całkowite

Możesz też ustalać aspekty żądań za pomocą pól zawierających liczby całkowite. Na przykład: może oznaczyć właściwość liczby całkowitej o nazwie book_pages jako dostępną do aspektu w celu doprecyzowania wyniki wyszukiwania książek z wartością „100–200” .

Podczas konfigurowania schematu pola właściwości z liczbą całkowitą ustaw isFacetable do true i dodaj odpowiednie opcje grupowania do integerPropertyOptions Dzięki temu każda właściwość z możliwością przedstawiania liczb całkowitych ma domyślne zasobniki zdefiniowanych opcji.

Podczas definiowania logiki opcji zasobnika podaj tablicę wartości przyrostowych zakresów symbolizujących. Jeśli na przykład użytkownik określi zakresy jako 2, 5, 10, 100, potem 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 grupowania w facetOptions do danego wniosku. W razie potrzeby Cloud Search używa opcji grupowania zdefiniowanych w schemat, gdy ani wyszukiwarka, ani żądanie zapytania nie mają aspektu zdefiniowanych opcji. Aspekty zdefiniowane w zapytaniu mają pierwszeństwo przed aspektami zdefiniowanymi w wyszukiwarce, a aspekty zdefiniowane w wyszukiwarce przyjmą nad aspektami zdefiniowanymi w schemacie.

Wyniki aspektu według rozmiaru lub daty dokumentu

Za pomocą zastrzeżone operatory zawężać wyniki wyszukiwania według rozmiaru pliku dokumentu, mierzonego w bajtach lub dokument został utworzony lub zmodyfikowany. Nie musisz definiować schematu niestandardowego, ale musisz określić wartość operatorName w polu wyszukiwania FacetOptions

  • 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

facetResults właściwość w odpowiedzi na zapytanie zawiera dokładne żądanie filtra użytkownika w polu filter dla każdego bucket

W przypadku aspektów, które nie są oparte na liczbach całkowitych, facetResults zawiera wpis dla dla każdej żądanej usługi. Dla każdej właściwości znajduje się lista wartości lub zakresów, 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, używając wybrane filtry i ponownie wysłać zapytanie do interfejsu API.

Dodaj sugestie

Korzystanie z interfejsu API suggest aby umożliwić autouzupełnianie zapytań na podstawie danych osobowych użytkownika a także historię zapytań, a także kontakty i ich korpus dokumentów.

Na przykład to wywołanie podaje sugestie dotyczące częściowych wyrażenie jo.

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

Można następnie wyświetlić uzyskane sugestie odpowiednio do aplikacji.