Ta strona została przetłumaczona przez Cloud Translation API.

Tworzenie interfejsu wyszukiwania za pomocą interfejsu Query API

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 na true.
Aby wyłączyć wszystkie optymalizacje na poziomie zapytania, w tym wyniki uzupełniające, synonimy i poprawki pisowni, ustaw w zapytaniu parametr QueryInterpretationOptions.enableVerbatimMode na true.
Aby wyłączyć wyniki uzupełniające na poziomie wyszukiwarki, ustaw w zapytaniu parametr QueryInterpretationOptions.forceDisableSupplementalResults na true.
Aby wyłączyć wyniki uzupełniające na poziomie zapytania, ustaw w zapytaniu parametr QueryInterpretationOptions.disableSupplementalResults na true.

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 lub DESCENDING.

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"
  }
]

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.

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.