- Żądanie HTTP
- Treść żądania
- Treść odpowiedzi
- Zakresy autoryzacji
- QueryInterpretationOptions
- QueryInterpretation
- QueryInterpretation.InterpretationType
- QueryInterpretation.Reason
- SearchResult
- Fragment
- MatchRange:
- Metadane
- ResultDisplayMetadata
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField
- ResultDebugInfo
- StructuredResult
- SpellResult
- FacetResult
- FacetBucket
- ResponseDebugInfo
- ErrorInfo
- ErrorMessage
- ResultCounts
- SourceResultCount
- Wypróbuj
Cloud Search Query API udostępnia metodę wyszukiwania, która zwraca najtrafniejsze wyniki zapytania użytkownika. Wyniki mogą pochodzić z aplikacji Google Workspace, takich jak Gmail czy Dysk Google, albo z danych zindeksowanych przez Ciebie od innych firm.
Uwaga: do wykonania tego interfejsu API wymagane jest standardowe konto użytkownika. Konto usługi nie może bezpośrednio wykonywać żądań do interfejsu Query API. Aby używać konta usługi do wykonywania zapytań, skonfiguruj przekazywanie uprawnień w całej domenie Google Workspace.
Żądanie HTTP
POST https://cloudsearch.googleapis.com/v1/query/search
Adres URL używa składni transkodowania gRPC.
Treść żądania
Treść żądania zawiera dane o następującej strukturze:
Zapis JSON |
---|
{ "requestOptions": { object ( |
Pola | |
---|---|
requestOptions |
Opcje żądania, takie jak wyszukiwarka i strefa czasowa użytkownika. |
query |
Nieprzetworzony ciąg zapytania. Obsługiwane operatory wyszukiwania znajdziesz w artykule Zawężanie wyszukiwania za pomocą operatorów. |
pageSize |
Maksymalna liczba wyników wyszukiwania zwracanych na jednej stronie. Prawidłowe wartości mieszczą się w zakresie od 1 do 100 włącznie. Wartość domyślna to 10. Minimalna wartość to 50, gdy wymagane są wyniki powyżej 2000. |
start |
Początkowy indeks wyników. |
dataSourceRestrictions[] |
Źródła, które mają być używane do wysyłania zapytań. Jeśli nie określono, używane są wszystkie źródła danych z bieżącej wyszukiwarki. |
facetOptions[] |
|
sortOptions |
Opcje sortowania wyników wyszukiwania |
queryInterpretationOptions |
do interpretacji zapytania użytkownika. |
contextAttributes[] |
Atrybuty kontekstu żądania, które zostaną użyte do dostosowania rankingu wyników wyszukiwania. Maksymalna liczba elementów to 10. |
Treść odpowiedzi
W przypadku powodzenia treść żądania zawiera dane o następującej strukturze:
Odpowiedź interfejsu Search API.
Zapis JSON |
---|
{ "queryInterpretation": { object ( |
Pola | |
---|---|
queryInterpretation |
Wynik interpretacji zapytania użytkownika. Pole puste, jeśli interpretacja zapytań jest wyłączona. |
results[] |
Wyniki wyszukiwania. |
structuredResults[] |
Uporządkowane wyniki dla zapytania użytkownika. Wyniki te nie są wliczane do parametru pageSize. |
spellResults[] |
Sugerowana pisownia zapytania. |
facetResults[] |
Powtórzone wyniki aspektu. |
hasMoreResults |
Informacja, czy istnieje więcej wyników wyszukiwania pasujących do zapytania. |
debugInfo |
debugowanie informacji o odpowiedzi; |
errorInfo |
Informacje o błędzie dotyczące odpowiedzi. |
resultCounts |
Informacje o liczbie wyników rozwiniętych. |
Pole sumy
W rzadkich przypadkach, gdy system nie może przeszukać wszystkich dokumentów, ponownie uruchom zapytanie. |
|
resultCountEstimate |
Szacowana liczba wyników dla tego zapytania. |
resultCountExact |
Dokładna liczba wyników dla tego zapytania. |
Zakresy autoryzacji
Wymaga jednego z tych zakresów OAuth:
https://www.googleapis.com/auth/cloud_search.query
https://www.googleapis.com/auth/cloud_search
Więcej informacji znajdziesz w przewodniku po autoryzacji.
QueryInterpretationOptions
do analizowania zapytań użytkowników.
Zapis JSON |
---|
{ "disableNlInterpretation": boolean, "enableVerbatimMode": boolean, "disableSupplementalResults": boolean } |
Pola | |
---|---|
disableNlInterpretation |
Oznacz, aby wyłączyć interpretację zapytań w języku naturalnym (NL). Wartość domyślna to false (fałsz). Ustaw na wartość prawda, aby wyłączyć interpretację języka naturalnego. Interpretacja NL ma zastosowanie tylko do wstępnie zdefiniowanych źródeł danych. |
enableVerbatimMode |
Włącz tę flagę, aby wyłączyć wszystkie wewnętrzne optymalizacje, takie jak interpretacja zapytań w języku naturalnym (NL), pobieranie wyników uzupełniających i używanie synonimów, w tym niestandardowych. Jeśli któraś z dwóch flag jest spełniony, interpretacja nl jest wyłączona. |
disableSupplementalResults |
Użyj tej flagi, aby wyłączyć wyniki uzupełniające dla zapytania. Jeśli ma wartość Prawda, ustawienie wyników dodatkowych wybranych na poziomie aplikacji SearchApplication ma pierwszeństwo. |
QueryInterpretation
Zapis JSON |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
Pola | |
---|---|
interpretedQuery |
Interpretacja zapytania użytego w wyszukiwaniu. Na przykład zapytania kierowane w języku naturalnym, takie jak „e-mail od jana”, będą interpretowane jako „from:jan source:poczta”. To pole nie będzie wypełnione, jeśli przyczyna to NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY. |
interpretationType |
|
reason |
Przyczyna interpretacji zapytania. Jeśli typ interpretacji jest inny niż BRAK, to pole nie będzie mieć wartości NIE OKREŚLONE. |
QueryInterpretation.InterpretationType
Wartości w polu enum | |
---|---|
NONE |
Przy pobieraniu wyników wyszukiwania nie jest używana żadna interpretacja języka naturalnego ani szersza wersja zapytania. |
BLEND |
Wyniki pierwotnego zapytania zostaną wymieszane z innymi. Przyczyna połączenia tych innych wyników z wynikami pierwotnego zapytania jest wpisana w polu „Przyczyna” poniżej. |
REPLACE |
Wyniki pierwotnego zapytania zostaną zastąpione. Przyczyna zastąpienia wyników oryginalnego zapytania zostanie podana w polu „Przyczyna” poniżej. |
QueryInterpretation.Reason
Wartości w polu enum | |
---|---|
UNSPECIFIED |
|
QUERY_HAS_NATURAL_LANGUAGE_INTENT |
Do pobierania wyników wyszukiwania używana jest interpretacja zapytania w języku naturalnym. |
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY |
Podobieństwo haseł w zapytaniu i dokumencie służy do selektywnego poszerzania zapytania w celu pobrania dodatkowych wyników wyszukiwania, ponieważ dla zapytania użytkownika nie znaleziono wystarczającej liczby wyników. W tym przypadku zinterpretowane zapytanie będzie puste. |
SearchResult
Wyniki zawierające zindeksowane informacje dotyczące dokumentu.
Zapis JSON |
---|
{ "title": string, "url": string, "snippet": { object ( |
Pola | |
---|---|
title |
Tytuł wyniku wyszukiwania. |
url |
Adres URL wyniku wyszukiwania. Adres URL zawiera przekierowanie Google do rzeczywistego elementu. Ten adres URL jest podpisany i nie należy go zmieniać. |
snippet |
Połączenie wszystkich fragmentów (podsumowań) dostępnych w przypadku tego wyniku. |
metadata |
metadane wyniku wyszukiwania. |
clusteredResults[] |
Jeśli źródło jest zgrupowane, podaj listę wyników pogrupowanych. Będzie tylko 1 poziom połączonych wyników. Jeśli bieżące źródło nie jest włączone do grupowania, to pole będzie puste. |
debugInfo |
Debugowanie informacji o tym wyniku wyszukiwania. |
Krótki opis
Fragment wyniku wyszukiwania, który podsumowuje treść wyświetlonej strony.
Zapis JSON |
---|
{
"snippet": string,
"matchRanges": [
{
object ( |
Pola | |
---|---|
snippet |
Fragment dokumentu. Fragment dokumentu. Może zawierać znak HTML przed renderowaniem, bez zmiany znaczenia. |
matchRanges[] |
Pasujące zakresy we fragmencie. |
MatchRange
Dopasowany zakres fragmentu kodu [start, end).
Zapis JSON |
---|
{ "start": integer, "end": integer } |
Pola | |
---|---|
start |
Pozycja początkowa dopasowania we fragmencie. |
end |
Koniec dopasowania we fragmencie. |
Metadane
metadanych pasujących wyników wyszukiwania.
Zapis JSON |
---|
{ "source": { object ( |
Pola | |
---|---|
source |
Nazwane źródło wyniku, np. Gmail. |
mimeType |
Typ MIME wyniku wyszukiwania. |
thumbnailUrl |
Adres URL miniatury wyniku. |
owner |
właściciel (zwykle twórca) dokumentu lub obiektu wyniku wyszukiwania. |
createTime |
Czas utworzenia danego dokumentu lub obiektu w wynikach wyszukiwania. Sygnatura czasowa w formacie RFC3339 UTC „Zulu”, z rozdzielczością nanosekundy i maksymalnie 9 cyframi po przecinku. Przykłady: |
updateTime |
Data ostatniej modyfikacji obiektu w wynikach wyszukiwania. Jeśli nie zostanie ona ustawiona w elemencie, zwrócona w tym miejscu wartość będzie pusta. Jeśli do obliczenia aktualności wyników używana jest zasada Sygnatura czasowa w formacie RFC3339 UTC „Zulu”, z rozdzielczością nanosekundy i maksymalnie 9 cyframi po przecinku. Przykłady: |
fields[] |
Zindeksowane pola w uporządkowanych danych zwrócone jako ogólna właściwość nazwana. |
displayOptions |
opcje określające sposób wyświetlania wyników wyszukiwania uporządkowanych danych. |
objectType |
Typ obiektu wyniku wyszukiwania. |
ResultDisplayMetadata
Zapis JSON |
---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
Pola | |
---|---|
objectTypeLabel |
Etykieta wyświetlana obiektu. |
metalines[] |
Zawartość metadanych, która ma być wyświetlana w wyniku. |
ResultDisplayMetadata.ResultDisplayLine
Zbiór pól składających się na wyświetlaną linię
Zapis JSON |
---|
{
"fields": [
{
object ( |
Pola | |
---|---|
fields[] |
ResultDisplayMetadata.ResultDisplayField
Wyświetl pola wyników query.search
Zapis JSON |
---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
Pola | |
---|---|
label |
Wyświetlana etykieta właściwości. |
operatorName |
Nazwa operatora właściwości. |
property |
Para wartości nazwy dla właściwości. |
ResultDebugInfo
Informacje debugowania dotyczące wyniku.
Zapis JSON |
---|
{ "formattedDebugInfo": string } |
Pola | |
---|---|
formattedDebugInfo |
Ogólne dane debugowania sformatowane do wyświetlania. |
StructuredResult
Uporządkowane wyniki zwracane w odpowiedzi na żądanie wyszukiwania.
Zapis JSON |
---|
{
"person": {
object ( |
Pola | |
---|---|
person |
Przedstawianie osoby |
SpellResult
Zapis JSON |
---|
{ "suggestedQuery": string } |
Pola | |
---|---|
suggestedQuery |
Sugerowana pisownia zapytania. |
FacetResult
Odpowiedź aspektu dotycząca konkretnego źródła
Zapis JSON |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
Pola | |
---|---|
sourceName |
Nazwa źródła, dla której zwracane są wyniki aspektu. Pole nie będzie puste. |
objectType |
Typ obiektu, dla którego zwracane są wyniki aspektu. Pole może być puste. |
operatorName |
Nazwa operatora wybranego do określania aspektów. @see cloudsearch.SchemaPropertyOptions |
buckets[] |
Zasobniki aspektów dla wartości w odpowiedzi zawierających co najmniej 1 wynik z odpowiednim filtrem. |
FacetBucket
Zasobnik w aspekcie to podstawowa jednostka działania. Zależnie od rodzaju pola zasobnik może się składać z jednej wartości LUB ciągłego zakresu wartości. Zasobnik Facet jest obecnie używany tylko do zwracania obiektu odpowiedzi.
Zapis JSON |
---|
{ "count": integer, "percentage": integer, "filter": { object ( |
Pola | |
---|---|
count |
Liczba wyników pasujących do wartości zasobnika. Liczby są zwracane tylko w przypadku wyszukiwań, gdy zapewnić ich dokładność. Cloud Search nie gwarantuje liczby aspektów dla zapytań, a liczba aspektów może być prezentowana nieregularnie, nawet w przypadku identycznych zapytań. Nie twórz zależności od istnienia liczby aspektów. Zamiast tego używaj wartości procentowych, które są zawsze zwracane. |
percentage |
Odsetek wyników, które pasują do wartości segmentu. Zwracana wartość mieści się w zakresie od 0 do 100 i jest zaokrąglana w dół do liczby całkowitej w przypadku wartości ułamkowych. Jeśli wartość nie jest zwracana bezpośrednio, jest to wartość procentowa, która jest zaokrąglana do 0. Wartości procentowe są zwracane w przypadku wszystkich wyszukiwań, ale są przybliżone. Wartości procentowe są zawsze zwracane, dlatego zamiast liczby powinny być renderowane wartości procentowe. |
filter |
Filtr, który zostanie przekazany w żądaniu wyszukiwania w przypadku wybrania odpowiedniego zasobnika. |
value |
|
ResponseDebugInfo
debugowanie informacji o odpowiedzi;
Zapis JSON |
---|
{ "formattedDebugInfo": string } |
Pola | |
---|---|
formattedDebugInfo |
Ogólne dane debugowania sformatowane do wyświetlania. |
ErrorInfo
Informacje o błędzie dotyczące odpowiedzi.
Zapis JSON |
---|
{
"errorMessages": [
{
object ( |
Pola | |
---|---|
errorMessages[] |
|
ErrorMessage
Komunikat o błędzie w każdej odpowiedzi źródłowej.
Zapis JSON |
---|
{
"source": {
object ( |
Pola | |
---|---|
source |
|
errorMessage |
|
ResultCounts
Informacje o liczbie wyników
Zapis JSON |
---|
{
"sourceResultCounts": [
{
object ( |
Pola | |
---|---|
sourceResultCounts[] |
Informacje o liczbie wyników dla każdego źródła wraz z wynikami. |
SourceResultCount
Informacje o liczbie wyników według źródła.
Zapis JSON |
---|
{ "source": { object ( |
Pola | |
---|---|
source |
Źródło, z którym powiązane są informacje o liczbie wyników. |
hasMoreResults |
Określa, czy dla tego źródła dostępnych jest więcej wyników wyszukiwania. |
Pole sumy
|
|
resultCountEstimate |
Szacowana liczba wyników dla tego źródła. |
resultCountExact |
Dokładna liczba wyników dla tego źródła. |