Method: query.search

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

Uwaga: ten interfejs API wymaga do działania standardowego konta użytkownika. Konto usługi nie może bezpośrednio wysyłać żądań do interfejsu API zapytań. 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 żądania, takie jak aplikacja wyszukiwania i strefa czasowa użytkownika.
query

string

Ciąg zapytania w formie nieprzetworzonej. Listę obsługiwanych operatorów wyszukiwania znajdziesz w artykule Zawężanie wyszukiwania za pomocą operatorów.
pageSize

integer

Maksymalna liczba wyników wyszukiwania do zwrócenia na jednej stronie. Prawidłowe wartości to od 1 do 100 włącznie. Wartość domyślna to 10. Minimalna wartość to 50, gdy żądane są wyniki powyżej 2000.
start

integer

Indeks początkowy wyników.
dataSourceRestrictions[]

object (DataSourceRestriction)

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

object (FacetOptions)
sortOptions

object (SortOptions)

Opcje sortowania wyników wyszukiwania
queryInterpretationOptions

object (QueryInterpretationOptions)

opcje interpretacji zapytania użytkownika.
contextAttributes[]

object (ContextAttribute)

Atrybuty kontekstu żądania, które będą używane do dostosowywania rankingu wyników wyszukiwania. Maksymalna liczba elementów to 10.

Treść odpowiedzi

Odpowiedź interfejsu API wyszukiwania. NEXT id: 19

W przypadku powodzenia treść żądania zawiera dane o następującej strukturze:

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. Puste, jeśli interpretacja zapytań jest wyłączona.
results[]

object (SearchResult)

wyniki wyszukiwania,
structuredResults[]

object (StructuredResult)

Ustrukturyzowane wyniki zapytania użytkownika. Te wyniki nie są wliczane do parametru pageSize.
spellResults[]

object (SpellResult)

Sugerowana pisownia zapytania.
facetResults[]

object (FacetResult)

Powtórzone wyniki aspektów.
hasMoreResults

boolean

czy jest więcej wyników wyszukiwania pasujących do zapytania;
debugInfo

object (ResponseDebugInfo)

Informacje na potrzeby debugowania odpowiedzi.
errorInfo

object (ErrorInfo)

Informacje o błędzie w odpowiedzi.
resultCounts

object (ResultCounts)

Rozwinięte informacje o liczbie wyników.

Pole zbiorcze result_count. Łączna liczba wyników we wszystkich źródłach danych, o które prosisz. Pomijane, jeśli w zbiorze źródeł danych, do których wysyłane są zapytania, znajdują się predefiniowane źródła. W tych przypadkach liczba wyników może być szacunkowa, a nie dokładna:

  • Gdy zapytanie zawiera więcej niż 2 słowa w frazie, np. „dokładna liczba wyników” w cudzysłowie.

  • Gdy liczba unikalnych list ACL wyników wyszukiwania do oceny jest zbyt duża, aby można było ją obliczyć w rozsądnym czasie.

W rzadkich przypadkach, gdy system nie może przeszukać wszystkich dokumentów, ponownie uruchom zapytanie. Pole result_count może mieć tylko jedną z tych wartości:
resultCountEstimate

string (int64 format)

Szacunkowa liczba wyników tego zapytania.
resultCountExact

string (int64 format)

Dokładna liczba wyników 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

opcje interpretacji zapytania użytkownika.

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

boolean

Flaga wyłączająca interpretację zapytań w języku naturalnym. Domyślna wartość to false. Ustaw wartość true, aby wyłączyć interpretację w języku naturalnym. Interpretacja w języku naturalnym dotyczy tylko wstępnie zdefiniowanych źródeł danych.
enableVerbatimMode

boolean

Włącz tę flagę, aby wyłączyć wszystkie wewnętrzne optymalizacje, takie jak interpretacja zapytań w języku naturalnym, pobieranie dodatkowych wyników i używanie synonimów, w tym niestandardowych. Interpretacja w języku naturalnym zostanie wyłączona, jeśli którykolwiek z tych 2 sygnałów będzie miał wartość „true”.
disableSupplementalResults

boolean

Użyj tej flagi, aby wyłączyć wyniki dodatkowe dla zapytania. Jeśli ustawienie wyników dodatkowych wybrane na poziomie SearchApplication ma wartość True, ma ono wyższy priorytet.

QueryInterpretation

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

string

Interpretacja zapytania użytego w wyszukiwaniu. Na przykład zapytania w języku naturalnym, takie jak „e-mail od Jana”, zostaną zinterpretowane jako „from:jan source:mail”. To pole nie zostanie wypełnione, jeśli powodem jest NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

Powód interpretacji zapytania. Jeśli typ interpretacji nie ma wartości NONE, to pole nie będzie miało wartości UNSPECIFIED.
interpretedQueryActualResultCount

integer

Rzeczywista liczba wyników zwróconych przez zinterpretowane zapytanie.
interpretedQueryEstimatedResultCount

string (int64 format)

Szacunkowa liczba wyników zwróconych przez zinterpretowane zapytanie.

QueryInterpretation.InterpretationType

Wartości w polu enum
NONE Do pobierania 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. Przyczyna połączenia tych innych wyników z wynikami pierwotnego zapytania jest podana w polu „reason” poniżej.
REPLACE Wyniki pierwotnego zapytania zostaną zastąpione. Przyczyna zastąpienia wyników pierwotnego zapytania jest podana w polu „reason” 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 między zapytaniem a słowami w dokumencie jest używane do selektywnego rozszerzania zapytania w celu pobrania dodatkowych wyników wyszukiwania, ponieważ nie znaleziono wystarczającej liczby wyników dla zapytania użytkownika. W tym przypadku zinterpretowane zapytanie będzie puste.

SearchResult

Wyniki zawierające zindeksowane informacje o dokumencie. Następny identyfikator: 16

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)

Połączenie wszystkich fragmentów (podsumowań) dostępnych dla tego wyniku.
metadata

object (Metadata)

metadane wyniku wyszukiwania.
clusteredResults[]

object (SearchResult)

Jeśli źródło jest zgrupowane, podaj listę zgrupowanych wyników. Będzie tylko jeden poziom zgrupowanych wyników. Jeśli bieżące źródło nie jest włączone w przypadku klastrowania, to pole będzie puste.
debugInfo

object (ResultDebugInfo)

Informacje na potrzeby debugowania tego wyniku wyszukiwania.

Krótki opis

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

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

string

Fragment dokumentu. Może zawierać znak HTML ze zmienionym znaczeniem, który przed renderowaniem należy przywrócić do pierwotnej postaci.
matchRanges[]

object (MatchRange)

Zakresy dopasowań w kawałku kodu.

MatchRange

Dopasowany zakres fragmentu [start, end).

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

integer

Pozycja początkowa dopasowania w wycinku.
end

integer

Koniec meczu w kawałku kodu.

Metadane

metadane 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 (zwykle twórca) dokumentu lub obiektu w wynikach wyszukiwania;
createTime

string (Timestamp format)

Czas utworzenia tego dokumentu lub obiektu w wyniku wyszukiwania.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

Data ostatniej modyfikacji obiektu w wynikach wyszukiwania. Jeśli nie jest ustawiona w produkcie, zwracana wartość jest pusta. Jeśli do obliczania aktualności używana jest wartość updateTime, a nie jest ona ustawiona, domyślnie przyjmuje wartość 2 lat od bieżącego czasu.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".
fields[]

object (NamedProperty)

Indeksowane pola w danych strukturalnych zwracane jako ogólna właściwość nazwana.
displayOptions

object (ResultDisplayMetadata)

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

string

Typ obiektu wyniku wyszukiwania.

ResultDisplayMetadata

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

string

Etykieta wyświetlana obiektu.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

Treść metadanych, która ma być wyświetlana z wynikiem.

ResultDisplayMetadata.ResultDisplayLine

zbiór pól, które składają się na wyświetlaną linię;

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

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

Pola wyświetlania wyników zapytania query.search

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

string

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

string

Nazwa operatora usługi.
property

object (NamedProperty)

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

ResultDebugInfo

Informacje na potrzeby debugowania dotyczące wyniku.

Zapis JSON 
{
  "formattedDebugInfo": string
}
Pola
formattedDebugInfo

string

Ogólne informacje debugowania sformatowane do wyświetlenia.

StructuredResult

Ustrukturyzowane wyniki zwracane w ramach żądania wyszukiwania.

Zapis JSON 
{

  // Union field structured_result can be only one of the following:
  "person": {
    object (Person)
  }
  // End of list of possible types for union field structured_result.
}
Pola

Pole zbiorcze structured_result.

Pole structured_result może mieć tylko jedną z tych wartości:
person

object (Person)

Reprezentacja osoby

SpellResult

Zapis JSON 
{
  "suggestedQuery": string,
  "suggestionType": enum (SpellResult.SuggestionType),
  "suggestedQueryHtml": {
    object (SafeHtmlProto)
  }
}
Pola
suggestedQuery

string

Sugerowana pisownia zapytania.
suggestionType

enum (SpellResult.SuggestionType)

sugestia wywołana dla bieżącego zapytania.
suggestedQueryHtml

object (SafeHtmlProto)

Oczyszczony kod HTML reprezentujący zapytanie po korekcie pisowni, którego można używać w interfejsie. Zwykle zawiera tagi specyficzne dla danego języka, które oznaczają części zapytania, w których sprawdzono pisownię.

SpellResult.SuggestionType

Typ sugestii wywołanej w przypadku zapytania.

Wartości w polu enum
SUGGESTION_TYPE_UNSPECIFIED Domyślny typ sprawdzania pisowni
NON_EMPTY_RESULTS_SPELL_SUGGESTION Sugestia pisowni bez żadnych zmienionych wyników. Wyniki są nadal wyświetlane dla oryginalnego zapytania (które ma wyniki inne niż zero), a także pojawia się sugestia pisowni, która dałaby wyniki.
ZERO_RESULTS_FULL_PAGE_REPLACEMENT Sugestia pisowni wywoływana, gdy pierwotne zapytanie nie zwraca żadnych wyników. Gdy oryginalne zapytanie nie daje żadnych wyników, a sugestia pisowni daje wyniki, wyświetlamy wyniki dla zapytania z poprawioną pisownią.

SafeHtmlProto

WAŻNE: przyjmowanie tej wiadomości z niezaufanego źródła jest niebezpieczne, ponieważ atakujący może łatwo sfałszować serializowane wiadomości, które nie spełniają umowy bezpieczeństwa typu – na przykład mogą zawierać skrypt kontrolowany przez atakującego. System, który otrzymuje SafeHtmlProto, domyślnie ufa producentowi tego obiektu. Dlatego zwykle można bezpiecznie zwracać tę wiadomość w odpowiedziach RPC, ale zwykle nie można jej akceptować w żądaniach RPC.

Zapis JSON 
{
  "privateDoNotAccessOrElseSafeHtmlWrappedValue": string
}
Pola
privateDoNotAccessOrElseSafeHtmlWrappedValue

string

WAŻNE: nigdy nie ustawiaj ani nie odczytuj tego pola, nawet w testach. Jest ono prywatne. Więcej informacji o pakietach języków programowania, za pomocą których można tworzyć lub odczytywać tę wiadomość, znajdziesz w dokumentacji u góry pliku .proto.

FacetResult

Odpowiedź dotycząca aspektu specyficznego dla ź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 aspektów. Nie będzie pusta.
objectType

string

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

string

Nazwa operatora wybranego do fasetowania. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

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

FacetBucket

Kosz w aspekcie to podstawowa jednostka działania. Kosz może obejmować pojedynczą wartość LUB ciągły zakres wartości, w zależności od typu pola, które zostało podzielone na kosze. Obecnie element FacetBucket służy tylko do zwracania obiektu odpowiedzi.

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

  // Union field bucket_value can be only one of the following:
  "value": {
    object (Value)
  }
  // End of list of possible types for union field bucket_value.
}
Pola
count

integer

Liczba wyników pasujących do wartości zasobnika. Liczby są zwracane tylko w przypadku wyszukiwań, w których można zapewnić dokładność liczby. Cloud Search nie gwarantuje liczby aspektów w przypadku żadnego zapytania, a liczby aspektów mogą być dostępne tylko okresowo, nawet w przypadku identycznych zapytań. Nie twórz zależności od istnienia liczby aspektów. Zamiast tego używaj procentów liczby aspektów, które są zawsze zwracane.
percentage

integer

Odsetek wyników, które pasują do wartości zasobnika. Zwracana wartość mieści się w przedziale (0–100] i jest zaokrąglana w dół do liczby całkowitej, jeśli jest ułamkowa. Jeśli wartość nie jest jawnie zwracana, oznacza to wartość procentową zaokrągloną do 0. W przypadku wszystkich wyszukiwań zwracane są wartości procentowe, ale są one szacunkowe. Zawsze zwracane są wartości procentowe, więc zamiast liczby wyświetlaj wartości procentowe.
filter

object (Filter)

Filtr, który ma być przekazywany w żądaniu wyszukiwania, jeśli wybrany jest odpowiedni zasobnik.
Pole zbiorcze bucket_value. Zakres lub wartość segmentu, który jest fasetowany bucket_value, może być tylko jedną z tych wartości:
value

object (Value)

ResponseDebugInfo

Informacje na potrzeby debugowania odpowiedzi.

Zapis JSON 
{
  "formattedDebugInfo": string
}
Pola
formattedDebugInfo

string

Ogólne informacje debugowania sformatowane do wyświetlenia.

ErrorInfo

Informacje o błędzie w odpowiedzi.

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

object (ErrorMessage)

ErrorMessage

Komunikat o błędzie w odpowiedzi ź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, które zawiera wyniki.

SourceResultCount

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

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 dla tego źródła jest więcej wyników wyszukiwania.

Pole zbiorcze result_count.

Pole result_count może mieć tylko jedną z tych wartości:
resultCountEstimate

string (int64 format)

Szacunkowa liczba wyników dla tego źródła.
resultCountExact

string (int64 format)

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