Method: query.search

Interfejs Cloud Search Query API udostępnia metodę wyszukiwania, która zwraca najbardziej trafne wyniki dla zapytania użytkownika. Wyniki mogą pochodzić z aplikacji Google Workspace, takich jak Gmail czy Dysk Google, lub z danych zindeksowanych przez Ciebie z zewnętrznych źródeł.

Uwaga: do wykonania tej operacji 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 (RequestOptions)
  },
  "query": string,
  "pageSize": integer,
  "start": integer,
  "dataSourceRestrictions": [
    {
      object (DataSourceRestriction)
    }
  ],
  "facetOptions": [
    {
      object (FacetOptions)
    }
  ],
  "sortOptions": {
    object (SortOptions)
  },
  "queryInterpretationOptions": {
    object (QueryInterpretationOptions)
  },
  "contextAttributes": [
    {
      object (ContextAttribute)
    }
  ]
}
Pola
requestOptions

object (RequestOptions)

opcje zapytania, takie jak aplikacja wyszukiwania i strefa czasowa użytkownika;
query

string

Nieprzetworzony ciąg zapytania. Informacje o obsługiwanych operatorach wyszukiwania znajdziesz w artykule Zawężanie wyszukiwania za pomocą operatorów.
pageSize

integer

Maksymalna liczba wyników wyszukiwania zwracanych na jednej stronie. Prawidłowe wartości to od 1 do 100 (obustronnie domknięte). Wartością domyślną jest 10. Minimalna wartość to 50, jeśli żądane są wyniki poza zakresem 2000.
start

integer

Początkowy indeks wyników.
dataSourceRestrictions[]

object (DataSourceRestriction)

Źródła danych, których chcesz używać do wysyłania zapytań. Jeśli nie zostaną określone, zostaną użyte wszystkie źródła danych z bieżącej aplikacji wyszukiwania.
facetOptions[]

object (FacetOptions)
sortOptions

object (SortOptions)

opcje sortowania wyników wyszukiwania;
queryInterpretationOptions

object (QueryInterpretationOptions)

opcji interpretacji zapytania użytkownika.
contextAttributes[]

object (ContextAttribute)

atrybuty kontekstu zapytania, 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 API wyszukiwania.

Zapis JSON 
{
  "queryInterpretation": {
    object (QueryInterpretation)
  },
  "results": [
    {
      object (SearchResult)
    }
  ],
  "structuredResults": [
    {
      object (StructuredResult)
    }
  ],
  "spellResults": [
    {
      object (SpellResult)
    }
  ],
  "facetResults": [
    {
      object (FacetResult)
    }
  ],
  "hasMoreResults": boolean,
  "debugInfo": {
    object (ResponseDebugInfo)
  },
  "errorInfo": {
    object (ErrorInfo)
  },
  "resultCounts": {
    object (ResultCounts)
  },

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
Pola
queryInterpretation

object (QueryInterpretation)

Wynik interpretacji zapytania użytkownika. Pusty, jeśli interpretacja zapytań jest wyłączona.
results[]

object (SearchResult)

Wyniki wyszukiwania
structuredResults[]

object (StructuredResult)

uporządkowane wyniki dla zapytania użytkownika; Te wyniki nie są wliczane do rozmiaru strony.
spellResults[]

object (SpellResult)

Sugerowana pisownia zapytania.
facetResults[]

object (FacetResult)

powtarzające się wyniki filtrowania;
hasMoreResults

boolean

Czy są jeszcze inne wyniki wyszukiwania pasujące do zapytania.
debugInfo

object (ResponseDebugInfo)

Informacje o debugowaniu odpowiedzi.
errorInfo

object (ErrorInfo)

Informacje o błędzie odpowiedzi.
resultCounts

object (ResultCounts)

Rozwinięte informacje o liczbie wyników

Pole unii result_count. Łączna liczba wyników we wszystkich żądanych źródłach danych. Pomijany, jeśli wśród zapytań do źródeł danych znajdują się wstępnie zdefiniowane źródła. Liczba wyników może być zwracana jako przybliżona zamiast dokładna w tych sytuacjach:

  • gdy zapytanie zawiera więcej niż 2 wyrazy w zwrotach, np. „dokładna liczba wyników” w cudzysłowie;

  • Gdy liczba unikalnych reguł dostępu do wyników wyszukiwania jest zbyt duża, aby można było ją przetworzyć w rozsądnym czasie.

W rzadkich przypadkach, gdy system nie może przeszukać wszystkich dokumentów, ponownie uruchom zapytanie. result_count może być tylko jednym z tych elementów:
resultCountEstimate

string (int64 format)

Szacunkowa liczba wyników dla tego zapytania.
resultCountExact

string (int64 format)

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 dotyczącym autoryzacji.

QueryInterpretationOptions

opcje interpretowania zapytania użytkownika.

Zapis JSON 
{
  "disableNlInterpretation": boolean,
  "enableVerbatimMode": boolean,
  "disableSupplementalResults": boolean
}
Pola
disableNlInterpretation

boolean

Flaga do wyłączania interpretacji zapytań w języku naturalnym. Wartość domyślna to false. Aby wyłączyć interpretację w języku naturalnym, ustaw wartość na true. Interpretacja NL dotyczy tylko wstępnie zdefiniowanych źródeł danych.
enableVerbatimMode

boolean

Włączenie tego parametru spowoduje wyłączenie wszystkich optymalizacji wewnętrznych, takich jak interpretacja zapytań w języku naturalnym, pobieranie dodatkowych wyników i używanie synonimów, w tym niestandardowych. Interpretacja nl zostanie wyłączona, jeśli jeden z tych 2 flag jest ustawiony na „Prawda”.
disableSupplementalResults

boolean

Użyj tej flagi, aby wyłączyć wyniki uzupełniające dla zapytania. Ustawienie wyników uzupełniających wybrane na poziomie SearchApplication ma pierwszeństwo, jeśli ma wartość Prawda.

QueryInterpretation

Zapis JSON 
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
Pola
interpretedQuery

string

Interpretacja zapytania użytego w wyszukiwaniu. Na przykład zapytania z intencją wyrażoną w języku naturalnym, takie jak „e-mail od Jana”, będą interpretowane jako „from:john source:mail”. To pole nie będzie wypełnione, gdy przyczyną jest NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

Powód interpretacji zapytania. To pole nie będzie puste, jeśli typ interpretacji nie jest NONE.

QueryInterpretation.InterpretationType

Wartości w polu enum
NONE Do pobrania wyników wyszukiwania nie jest używana ani interpretacja w języku naturalnym, ani szersza wersja zapytania.
BLEND Wyniki pierwotnego zapytania są łączone z innymi wynikami. Powód połączenia tych wyników z wynikami z pierwotnego zapytania jest podany w polu „Powód” poniżej.
REPLACE Wyniki pierwotnego zapytania zostaną zastąpione. W polu „Powód” poniżej podano powód zastąpienia wyników pierwotnego zapytania.

QueryInterpretation.Reason

Wartości w polu enum
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT Do pobierania wyników wyszukiwania służy interpretacja zapytania w języku naturalnym.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY Podobieństwa między zapytaniem a dokumentami są używane do selektywnego poszerzania zapytania w celu uzyskania dodatkowych wyników wyszukiwania, ponieważ nie udało się znaleźć wystarczającej liczby wyników dla zapytania użytkownika. W tym przypadku zainterpretowane zapytanie będzie puste.

SearchResult

Wyniki zawierające zindeksowane informacje o dokumencie.

Zapis JSON 
{
  "title": string,
  "url": string,
  "snippet": {
    object (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
Pola
title

string

Tytuł wyniku wyszukiwania.
url

string

Adres URL wyniku wyszukiwania. Adres URL zawiera przekierowanie Google do rzeczywistego produktu. Ten adres URL jest podpisany i nie należy go zmieniać.
snippet

object (Snippet)

Konkatenacja wszystkich fragmentów (podsumowań) dostępnych dla tego wyniku.
metadata

object (Metadata)

metadanych wyniku wyszukiwania.
clusteredResults[]

object (SearchResult)

Jeśli źródło jest pogrupowane, podaj listę pogrupowanych wyników. Wyniki będą grupowane tylko na 1 poziomie. Jeśli bieżące źródło nie jest włączone do grupowania, to pole będzie puste.
debugInfo

object (ResultDebugInfo)

Informacje o debugowaniu dotyczące tego wyniku wyszukiwania.

Krótki opis

Krótki opis wyniku wyszukiwania, który podsumowuje zawartość strony wyników.

Zapis JSON 
{
  "snippet": string,
  "matchRanges": [
    {
      object (MatchRange)
    }
  ]
}
Pola
snippet

string

Fragment dokumentu. Fragment dokumentu. Może zawierać znak HTML z escapowaniem, który należy usunąć przed renderowaniem.
matchRanges[]

object (MatchRange)

Pasujące zakresy w fragmentach kodu.

MatchRange

Dopasowany zakres fragmentu [start, end].

Zapis JSON 
{
  "start": integer,
  "end": integer
}
Pola
start

integer

Pozycja początkowa dopasowania w fragmentie.
end

integer

Koniec dopasowania w fragmentie kodu.

Metadane

metadanych pasującego wyniku wyszukiwania.

Zapis JSON 
{
  "source": {
    object (Source)
  },
  "mimeType": string,
  "thumbnailUrl": string,
  "owner": {
    object (Person)
  },
  "createTime": string,
  "updateTime": string,
  "fields": [
    {
      object (NamedProperty)
    }
  ],
  "displayOptions": {
    object (ResultDisplayMetadata)
  },
  "objectType": string
}
Pola
source

object (Source)

Nazwane źródło wyniku, np. Gmail.
mimeType

string

Typ MIME wyniku wyszukiwania.
thumbnailUrl

string

Adres URL miniatury wyniku.
owner

object (Person)

właściciel (zazwyczaj twórca) dokumentu lub obiektu w wyniku wyszukiwania.
createTime

string (Timestamp format)

Czas utworzenia tego dokumentu lub obiektu w wyniku wyszukiwania.

Sygnatura czasowa w formacie UTC „Zulu” zdefiniowanym w dokumencie RFC 3339, z dokładnością do nanosekund i maksymalnie 9 miejsc po przecinku. Przykłady: "2014-10-02T15:01:23Z" i "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

Data ostatniej modyfikacji obiektu w wyniku wyszukiwania. Jeśli nie jest ustawiony w produkcie, zwracana wartość jest pusta. Jeśli do obliczania świeżości używany jest parametr updateTime, a nie jest on ustawiony, jego wartość domyślna wynosi 2 lata od bieżącej daty.

Sygnatura czasowa w formacie UTC „Zulu” zdefiniowanym w dokumencie RFC 3339, z dokładnością do nanosekund i maksymalnie 9 miejsc po przecinku. Przykłady: "2014-10-02T15:01:23Z" i "2014-10-02T15:01:23.045123456Z".
fields[]

object (NamedProperty)

Indeksowane pola w uporządkowanych danych, zwracane jako ogólna nazwana właściwość.
displayOptions

object (ResultDisplayMetadata)

opcje określające sposób wyświetlania wyniku wyszukiwania uporządkowanych danych.
objectType

string

Typ obiektu w wyniku wyszukiwania.

ResultDisplayMetadata

Zapis JSON 
{
  "objectTypeLabel": string,
  "metalines": [
    {
      object (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
Pola
objectTypeLabel

string

Etykieta wyświetlania obiektu.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

Treść metalinii, która ma się wyświetlać wraz z wynikiem.

ResultDisplayMetadata.ResultDisplayLine

Zbiór pól, które tworzą wyświetlaną pozycję

Zapis JSON 
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
Pola
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

Wyświetlane pola w wynikach zapytania.

Zapis JSON 
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
Pola
label

string

Etykieta wyświetlania właściwości.
operatorName

string

Nazwa operatora obiektu.
property

object (NamedProperty)

Para nazwa-wartość właściwości.

ResultDebugInfo

Informacje o debugowaniu dotyczące wyniku.

Zapis JSON 
{
  "formattedDebugInfo": string
}
Pola
formattedDebugInfo

string

Ogólne informacje debugowania sformatowane do wyświetlania.

StructuredResult

Ustrukturyzowane wyniki zwracane w ramach żądania wyszukiwania.

Zapis JSON 
{
  "person": {
    object (Person)
  }
}
Pola
person

object (Person)

reprezentacja osoby,

SpellResult

Zapis JSON 
{
  "suggestedQuery": string
}
Pola
suggestedQuery

string

Sugerowana pisownia zapytania.

FacetResult

Odpowiedź dotycząca atrybutu źródła

Zapis JSON 
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
Pola
sourceName

string

Nazwa źródła, dla którego zwracane są wyniki. nie może być puste.
objectType

string

Typ obiektu, dla którego zwracane są wyniki posortowania. Może być puste.
operatorName

string

Nazwa operatora wybranego do podziału na podgrupy. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

FacetBuckets dla wartości w odpowiedzi zawierających co najmniej 1 wynik z odpowiednim filtrem.

FacetBucket

W przypadku osi podstawowej grupa jest podstawową jednostką działania. W zależności od typu pola zagregowanego grupa może zawierać jedną wartość LUB ciągły zakres wartości. FacetBucket jest obecnie używany tylko do zwracania obiektu odpowiedzi.

Zapis JSON 
{
  "count": integer,
  "percentage": integer,
  "filter": {
    object (Filter)
  },
  "value": {
    object (Value)
  }
}
Pola
count

integer

Liczba wyników pasujących do wartości zasobnika. Wykazywana liczba wyników wyszukiwania jest dokładna tylko wtedy, gdy jest to możliwe. Cloud Search nie gwarantuje liczby atrybutów dla żadnego zapytania, a liczby atrybutów mogą być obecne tylko sporadycznie, nawet w przypadku identycznych zapytań. Nie twórz zależności od istnienia liczby atrybutów. Zamiast tego używaj odsetków liczby atrybutów, które są zawsze zwracane.
percentage

integer

Odsetek wyników pasujących do wartości zasobnika. Zwrócona wartość mieści się w przedziale (0–100] i jest zaokrąglana w dół do liczby całkowitej, jeśli jest ułamkiem. Jeśli wartość nie jest zwracana wprost, oznacza wartość procentową zaokrągloną do 0. Odsetki są zwracane dla wszystkich wyszukiwań, ale są tylko szacunkowe. Ponieważ wartości procentowe są zawsze zwracane, renderowanie powinno się odbywać na podstawie wartości procentowych, a nie liczby.
filter

object (Filter)

Filtr, który ma być przekazany w żądaniu wyszukiwania, jeśli wybrano odpowiedni zasób.
value

object (Value)

ResponseDebugInfo

Informacje o debugowaniu odpowiedzi.

Zapis JSON 
{
  "formattedDebugInfo": string
}
Pola
formattedDebugInfo

string

Ogólne informacje debugowania sformatowane do wyświetlania.

ErrorInfo

informacje o błędzie odpowiedzi;

Zapis JSON 
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
Pola
errorMessages[]

object (ErrorMessage)

ErrorMessage

Komunikat o błędzie na odpowiedź źródła.

Zapis JSON 
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
Pola
source

object (Source)
errorMessage

string

ResultCounts

Informacje o liczbie wyników

Zapis JSON 
{
  "sourceResultCounts": [
    {
      object (SourceResultCount)
    }
  ]
}
Pola
sourceResultCounts[]

object (SourceResultCount)

Informacje o liczbie wyników dla każdego źródła z wynikami.

SourceResultCount

Informacje o liczbie wyników z poszczególnych źródeł.

Zapis JSON 
{
  "source": {
    object (Source)
  },
  "hasMoreResults": boolean,

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
Pola
source

object (Source)

Źródło, z którym powiązane są informacje o liczbie wyników.
hasMoreResults

boolean

Czy w przypadku tego źródła jest więcej wyników wyszukiwania.

Pole unii result_count.

result_count może być tylko jednym z tych elementów:
resultCountEstimate

string (int64 format)

Szacowana liczba wyników w tym źródle.
resultCountExact

string (int64 format)

Dokładna liczba wyników dla tego źródła.