Method: query.search

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 (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 wyszukiwarka i strefa czasowa użytkownika.

query

string

Nieprzetworzony ciąg zapytania. Obsługiwane operatory 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 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

integer

Początkowy indeks wyników.

dataSourceRestrictions[]

object (DataSourceRestriction)

Ź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[]

object (FacetOptions)

sortOptions

object (SortOptions)

Opcje sortowania wyników wyszukiwania

queryInterpretationOptions

object (QueryInterpretationOptions)

do interpretacji zapytania użytkownika.

contextAttributes[]

object (ContextAttribute)

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 (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. Pole puste, jeśli interpretacja zapytań jest wyłączona.

results[]

object (SearchResult)

Wyniki wyszukiwania.

structuredResults[]

object (StructuredResult)

Uporządkowane wyniki dla zapytania użytkownika. Wyniki te nie są wliczane do parametru pageSize.

spellResults[]

object (SpellResult)

Sugerowana pisownia zapytania.

facetResults[]

object (FacetResult)

Powtórzone wyniki aspektu.

hasMoreResults

boolean

Informacja, czy istnieje więcej wyników wyszukiwania pasujących do zapytania.

debugInfo

object (ResponseDebugInfo)

debugowanie informacji o odpowiedzi;

errorInfo

object (ErrorInfo)

Informacje o błędzie dotyczące odpowiedzi.

resultCounts

object (ResultCounts)

Informacje o liczbie wyników rozwiniętych.

Pole sumy result_count. Łączna liczba wyników we wszystkich żądanych źródłach danych. Pominięta, jeśli w zbiorze źródeł danych, których dotyczy zapytanie, uwzględnione są wstępnie zdefiniowane źródła. Liczby wyników mogą być zwracane jako wartości szacunkowe, a nie dokładne, w następujących okolicznościach:

  • Gdy zapytanie zawiera więcej niż 2 wyrazy w wyrażeniu, na przykład "liczba wyników ścisła" w cudzysłowie.

  • Gdy liczba unikalnych list kontroli dostępu do oceny jest zbyt duża, aby ją obliczyć w rozsądnym czasie oczekiwania.

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

resultCountEstimate

string (int64 format)

Szacowana 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 po autoryzacji.

QueryInterpretationOptions

do analizowania zapytań użytkowników.

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

boolean

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

boolean

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

boolean

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 (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
Pola
interpretedQuery

string

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

enum (QueryInterpretation.InterpretationType)

reason

enum (QueryInterpretation.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 (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 elementu. Ten adres URL jest podpisany i nie należy go zmieniać.

snippet

object (Snippet)

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

metadata

object (Metadata)

metadane wyniku wyszukiwania.

clusteredResults[]

object (SearchResult)

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

object (ResultDebugInfo)

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 (MatchRange)
    }
  ]
}
Pola
snippet

string

Fragment dokumentu. Fragment dokumentu. Może zawierać znak HTML przed renderowaniem, bez zmiany znaczenia.

matchRanges[]

object (MatchRange)

Pasujące zakresy we fragmencie.

MatchRange

Dopasowany zakres fragmentu kodu [start, end).

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

integer

Pozycja początkowa dopasowania we fragmencie.

end

integer

Koniec dopasowania we fragmencie.

Metadane

metadanych pasujących wyników 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 wyniku wyszukiwania.

createTime

string (Timestamp format)

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: "2014-10-02T15:01:23Z" i "2014-10-02T15:01:23.045123456Z".

updateTime

string (Timestamp format)

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 updateTime, która nie jest ustawiona, ta wartość domyślna to 2 lata od bieżącego czasu.

Sygnatura czasowa w formacie RFC3339 UTC „Zulu”, z rozdzielczością nanosekundy i maksymalnie 9 cyframi po przecinku. Przykłady: "2014-10-02T15:01:23Z" i "2014-10-02T15:01:23.045123456Z".

fields[]

object (NamedProperty)

Zindeksowane pola w uporządkowanych danych zwrócone jako ogólna właściwość nazwana.

displayOptions

object (ResultDisplayMetadata)

opcje określające sposób wyświetlania wyników wyszukiwania 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)

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 (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
Pola
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

Wyświetl pola wyników query.search

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

string

Wyświetlana etykieta właściwości.

operatorName

string

Nazwa operatora właściwości.

property

object (NamedProperty)

Para wartości nazwy dla właściwości.

ResultDebugInfo

Informacje debugowania dotyczące wyniku.

Zapis JSON
{
  "formattedDebugInfo": string
}
Pola
formattedDebugInfo

string

Ogólne dane debugowania sformatowane do wyświetlania.

StructuredResult

Uporządkowane wyniki zwracane w odpowiedzi na żądanie wyszukiwania.

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

object (Person)

Przedstawianie osoby

SpellResult

Zapis JSON
{
  "suggestedQuery": string
}
Pola
suggestedQuery

string

Sugerowana pisownia zapytania.

FacetResult

Odpowiedź aspektu dotycząca konkretnego źródła

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

string

Nazwa źródła, dla której zwracane są wyniki aspektu. Pole nie będzie puste.

objectType

string

Typ obiektu, dla którego zwracane są wyniki aspektu. Pole może być puste.

operatorName

string

Nazwa operatora wybranego do określania aspektów. @see cloudsearch.SchemaPropertyOptions

buckets[]

object (FacetBucket)

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 (Filter)
  },
  "value": {
    object (Value)
  }
}
Pola
count

integer

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

integer

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

object (Filter)

Filtr, który zostanie przekazany w żądaniu wyszukiwania w przypadku wybrania odpowiedniego zasobnika.

value

object (Value)

ResponseDebugInfo

debugowanie informacji o odpowiedzi;

Zapis JSON
{
  "formattedDebugInfo": string
}
Pola
formattedDebugInfo

string

Ogólne dane debugowania sformatowane do wyświetlania.

ErrorInfo

Informacje o błędzie dotyczące odpowiedzi.

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

object (ErrorMessage)

ErrorMessage

Komunikat o błędzie w każdej odpowiedzi źródłowej.

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 wraz z wynikami.

SourceResultCount

Informacje o liczbie wyników według ź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

Określa, czy dla tego źródła dostępnych jest więcej wyników wyszukiwania.

Pole sumy result_count.

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

resultCountEstimate

string (int64 format)

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

resultCountExact

string (int64 format)

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