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

Tworzenie interfejsu wyszukiwania za pomocą interfejsu Query API

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

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

Utwórz interfejs wyszukiwania

Stworzenie minimalnego interfejsu wyszukiwania wymaga kilku etapów:

Konfigurowanie wyszukiwarki
Wygeneruj dane logowania OAuth dla aplikacji
Tworzenie zapytania dotyczącego indeksu
Wyświetl wyniki zapytania

Możesz 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 utworzonym interfejsem wyszukiwania. Wyszukiwarka udostępnia parametry domyślne zapytania, np. źródła danych, które mają zostać użyte, kolejność sortowania, filtry i aspekty. W razie potrzeby możesz zastąpić te parametry za pomocą interfejsu Query API.

Więcej informacji o wyszukiwarkach znajdziesz w artykule na temat dostosowywania wyszukiwania w Cloud Search.

Wygeneruj dane logowania OAuth dla aplikacji

Oprócz czynności opisanych w sekcji 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 jakim jest używany interfejs API.

Użyj danych logowania, aby poprosić o autoryzację w imieniu użytkownika. Podczas wysyłania prośby o autoryzację 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"}.

Tworzenie zapytania dotyczącego indeksu

Za pomocą metody search możesz przeprowadzać wyszukiwania w indeksie.

Każde żądanie musi zawierać 2 informacje: tekst query służący do dopasowywania elementów oraz identyfikator searchApplicationId identyfikujący identyfikator wyszukiwarki, który ma zostać użyty.

Ten fragment kodu zawiera zapytanie do źródła danych o filmie „Titanic”:

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

Wyświetl wyniki zapytania

Interfejsy wyszukiwania powinny wyświetlać co najmniej element title oraz link do oryginalnego elementu. Możesz jeszcze bardziej poprawić wyświetlanie wyników wyszukiwania, wykorzystując dodatkowe informacje obecne w wynikach wyszukiwania, takie jak fragment kodu i metadane.

Obsługa wyników uzupełniających

Domyślnie Cloud Search zwraca wyniki uzupełniające, gdy liczba wyników jest niewystarczająca 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, InterpretationType ma wartość REPLACE. Jeśli zostanie zwróconych kilka wyników pierwotnego zapytania wraz z wynikami uzupełniającymi, InterpretationType ma wartość BLEND. W obu przypadkach QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.

W przypadku zwrócenia wyników uzupełniających możesz podać tekst informujący o ich zwróceniu. W przypadku REPLACE możesz na przykład wyświetlić ciąg „Pierwotne zapytanie nie zwróciło żadnych wyników. Wyświetlam wyniki podobnych zapytań”.

W przypadku BLEND możesz wyświetlić tekst „Pierwotne zapytanie nie zwróciło wystarczającej liczby wyników. Obejmuje to wyniki podobnych zapytań”.

Obsługa wyników wyszukiwania osób

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

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

Dopasowywanie bezpośrednich raportów

Bezpośrednie dopasowywanie raportów to funkcja wyszukiwarki osób w Cloud Search, która umożliwia użytkownikom przeglądanie bezpośrednich podwładnych osób w ich organizacji. Wynik jest dostępny w polu structuredResults.

Odpowiedź na pytanie o menedżera lub bezpośrednich podwładnych danej osoby zawiera w polu structuredResults kolumnę assistCardProtoHolder. assistCardProtoHolder zawiera pole o nazwie cardType, które ma wartość RELATED_PEOPLE_ANSWER_CARD. assistCardProtoHolder zawiera kartę relatedPeopleAnswerCard, która zawiera faktyczną odpowiedź. Zawiera on subject (osobę uwzględniony w zapytaniu) i relatedPeople, czyli zbiór osób powiązanych z danym tematem. Pole relationType zwraca wartość MANAGER lub DIRECT_REPORTS.

Poniższy kod pokazuje przykładową odpowiedź na żądanie bezpośredniego raportu pasującego do zapytania:

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

Aby wyłączyć wszystkie optymalizacje na poziomie wyszukiwarki, w tym wyniki uzupełniające, synonimy i poprawki pisowni, ustaw w wyszukiwarce parametr QueryInterpretationConfig.force_verbatim_mode na true.
Aby wyłączyć wszystkie optymalizacje na poziomie zapytania, w tym wyniki dodatkowe, synonimy i poprawki pisowni, wpisz w zapytaniu parametr QueryInterpretationOptions.enableVerbatimMode na true.
Aby wyłączyć wyniki uzupełniające na poziomie wyszukiwarki, wpisz wartość QueryInterpretationOptions.forceDisableSupplementalResults w zapytaniu na true.
Aby wyłączyć wyniki uzupełniające na poziomie zapytania, wpisz wartość QueryInterpretationOptions.disableSupplementalResults na true w zapytaniu.

Fragmenty z najciekawszymi momentami

W przypadku zwróconych elementów zawierających indeksowany tekst lub treść HTML zwracany jest fragment treści. Pomagają one użytkownikom określić trafność zwróconego elementu.

Jeśli fragment kodu zawiera wyszukiwane hasła, zwracany jest również co najmniej jeden zakres dopasowania określający ich lokalizację.

Użyj matchRanges, aby wyróżnić pasujący tekst podczas renderowania wyników. Ten przykład kodu w języku JavaScript przekształca fragment kodu w znaczniki HTML, a każdy pasujący zakres znajduje się 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:

{
  "snippet": "This is an example snippet...",
  "matchRanges": [
    {
      "start": 11,
      "end": 18
    }
  ]
}

Powstały ciąg HTML wygląda tak:

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

Wyświetl metadane

W polu metadata możesz wyświetlać dodatkowe informacje o zwracanym elemencie, które mogą być istotne dla użytkowników. Pole metadata zawiera wartości createTime i updateTime elementu, a także wszelkie 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 metawiersz jest tablicą etykiet wyświetlanych i par wartości skonfigurowane w schemacie.

Pobieranie dodatkowych wyników

Aby pobrać dodatkowe wyniki, ustaw żądane przesunięcie w polu start w żądaniu. Za pomocą pola pageSize możesz dostosować rozmiar każdej strony.

Aby wyświetlić liczbę zwróconych elementów lub wyświetlić opcje stronicowania na zwróconych elementach, użyj pola resultCount. W zależności od rozmiaru zestawu wyników dostarczana jest wartość rzeczywista lub szacunkowa.

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 usług z wieloma operatorami możesz sortować tylko za pomocą głównego operatora równości.
sortOrder – kierunek sortowania: ASCENDING lub DESCENDING.

Trafność jest również 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

Oprócz wyrażeń zapytań możesz dodatkowo ograniczyć wyniki, stosując filtry. Filtry można określić zarówno w wyszukiwarce, jak i w żądaniu wyszukiwania.

Aby dodać filtry w żądaniu lub wyszukiwarce, dodaj filtr w polu dataSourceRestrictions.filterOptions[].

Są 2 główne sposoby dalszego filtrowania źródła danych:

Filtry obiektów za pomocą właściwości filterOptions[].objectType – ogranicza dopasowanie elementów do określonego typu określonego w niestandardowym schemacie.
Filtry wartości – ogranicza 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 przeznaczone do 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ęź wyniki za pomocą aspektów

Aspekty to właściwości indeksowane, które reprezentują kategorie w celu zawężenia wyników wyszukiwania. Używaj aspektów, aby pomóc użytkownikom w interaktywnym doprecyzowaniu zapytań i szybciej znajdować odpowiednie produkty.

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

Podczas wysyłania żądania aspektów Cloud Search oblicza najczęstsze wartości dla żądanych właściwości spośród pasujących elementów. Wartości te są zwracane w odpowiedzi. Wartości te mogą posłużyć do utworzenia filtrów, które zawężają wyniki kolejnych zapytań.

Typowy wzorzec interakcji z aspektami to:

Utwórz wstępne zapytanie określające, które właściwości mają być uwzględnione w wynikach aspektu.
Renderuj wyniki wyszukiwania i aspektu.
Użytkownik wybiera co najmniej jedną wartość aspektu, aby zawęzić wyniki.
Powtórz zapytanie z użyciem filtra na podstawie wybranych wartości.

Aby np. umożliwić zawężenie 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"
  }
]

Możesz też podawać wyniki żądań aspektów za pomocą pól opartych na liczbach całkowitych. Możesz na przykład oznaczyć właściwość liczby całkowitej o nazwie book_pages jako możliwość aspektu, aby zawęzić wyniki wyszukiwania książek o liczbie stron „100–200”.

Po skonfigurowaniu schematu pola właściwości liczby całkowitej ustaw isFacetable na true i dodaj odpowiednie opcje zasobnika do integerPropertyOptions. Dzięki temu każda właściwość liczby całkowitej ma zdefiniowane domyślne opcje podziału na segmenty.

Definiując logikę opcji podziału na segmenty, podaj tablicę wartości przyrostowych określających zakresy. Jeśli na przykład użytkownik określi zakresy jako 2, 5, 10, 100, obliczane są aspekty <2, [2-5), [5-10), [10-100) i >=100.

Aby zastąpić aspekty oparte na liczbach całkowitych, możesz zdefiniować te same opcje podziału na segmenty w żądaniu facetOptions. W razie potrzeby Cloud Search używa opcji zasobnika zdefiniowanych w schemacie, gdy ani aplikacja wyszukiwania, ani żądanie zapytania nie mają zdefiniowanych opcji 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.

Możesz używać zarezerwowanych operatorów, aby zawężać wyniki wyszukiwania według rozmiaru pliku dokumentu (mierzonego w bajtach) lub daty utworzenia lub modyfikacji dokumentu. Nie musisz określać schematu niestandardowego, ale musisz określić wartość operatorName w regule FacetOptions w wyszukiwarce.

Do określania aspektów według rozmiaru dokumentu użyj funkcji itemsize i określ opcje podziału na segmenty.
Aby określić aspekty 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 dokładne żądanie filtra przesłane przez użytkownika w polu filter w poszczególnych 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 podana jest lista wartości lub zakresów o nazwie buckets. Wartości, które występują najczęściej, pojawiają się jako pierwsze.

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

Dodaj sugestie

Używaj interfejsu API suggest, aby włączać autouzupełnianie w przypadku zapytań na podstawie osobistej historii zapytań użytkownika oraz kontaktów i zbioru dokumentów.

Na przykład to wywołanie zawiera sugestie dotyczące częściowego wyrażenia jo.

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

Uzyskane sugestie możesz potem wyświetlić w zależności od aplikacji.