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 z minimalnymi wymaganiami rozważ użycie widżetu wyszukiwarki. 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
Generowanie danych logowania OAuth dla aplikacji
Wysyłanie zapytań do indeksu
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

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 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 przypadkach QueryInterpretation.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 tagu BLEND może zostać wyświetlony ciąg „Twoje wyszukiwanie pierwotnego zapytania nie zwróciło 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 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ń dotyczących menedżera lub bezpośrednich podwładnych osoby odpowiedź zawiera assistCardProtoHolder w 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 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:

Aby wyłączyć wszystkie optymalizacje na poziomie aplikacji wyszukiwania, w tym wyniki uzupełniające, synonimy i poprawki pisowni, ustaw QueryInterpretationConfig.force_verbatim_mode na true w aplikacjach wyszukiwania.
Aby wyłączyć wszystkie optymalizacje na poziomie zapytania wyszukiwania, w tym wyniki dodatkowe, synonimy i poprawki ortograficzne, ustaw parametr QueryInterpretationOptions.enableVerbatimMode na true w zapytaniu wyszukiwania.
Aby wyłączyć wyniki uzupełniające na poziomie aplikacji wyszukiwania, ustaw parametr QueryInterpretationOptions.forceDisableSupplementalResults na true w zapytaniu wyszukiwania.
Aby wyłączyć wyniki uzupełniające na poziomie zapytania, ustaw parametr QueryInterpretationOptions.disableSupplementalResults na true w zapytaniu.

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 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ę 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świetlaną typu obiektu i zbiór 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 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 podawana jest wartość rzeczywista lub oszacowana.

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

Dodaj filtry

Oprócz wyrażeń zapytań możesz jeszcze bardziej ograniczać wyniki za pomocą filtrów. 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ężanie wyników za pomocą aspektó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:

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

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ż 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.

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ść typu liczba całkowita 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 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 w wyszukiwarce, ani w żądaniu zapytania nie są zdefiniowane opcje aspektu. 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.

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 zasobnikó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

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