Method: query.search

Cloud Search Query API, kullanıcı sorgusundan en alakalı sonuçları döndüren arama yöntemini sağlar. Sonuçlar Gmail veya Google Drive gibi Google Workspace uygulamalarından ya da üçüncü taraflardan dizine eklediğiniz verilerden gelebilir.

Not: Bu API'nin yürütülmesi için standart bir son kullanıcı hesabı gerekir. Hizmet hesabı, sorgu API isteklerini doğrudan gerçekleştiremez. Sorgu gerçekleştirmek için hizmet hesabı kullanmak istiyorsanız Google Workspace alan genelinde yetki devrini ayarlayın.

HTTP isteği

POST https://cloudsearch.googleapis.com/v1/query/search

URL, gRPC Kod Dönüştürme söz dizimini kullanır.

İstek metni

İstek içeriği aşağıdaki yapıyla birlikte verileri içerir:

JSON gösterimi 
{
  "requestOptions": {
    object (RequestOptions)
  },
  "query": string,
  "pageSize": integer,
  "start": integer,
  "dataSourceRestrictions": [
    {
      object (DataSourceRestriction)
    }
  ],
  "facetOptions": [
    {
      object (FacetOptions)
    }
  ],
  "sortOptions": {
    object (SortOptions)
  },
  "queryInterpretationOptions": {
    object (QueryInterpretationOptions)
  },
  "contextAttributes": [
    {
      object (ContextAttribute)
    }
  ]
}
Alanlar
requestOptions

object (RequestOptions)

Arama uygulaması ve kullanıcının saat dilimi gibi istek seçenekleri.
query

string

Ham sorgu dizesi. Desteklenen arama operatörlerini Operatörleri kullanarak aramanızı daraltma bölümünde bulabilirsiniz.
pageSize

integer

Bir sayfada döndürülecek maksimum arama sonucu sayısı. Geçerli değerler 1 ile 100 arasındadır (bu değerler dahil). Varsayılan değer 10'dur. 2.000'den fazla sonuç istendiğinde minimum değer 50'dir.
start

integer

Sonuçların başlangıç dizini.
dataSourceRestrictions[]

object (DataSourceRestriction)

Sorgu için kullanılacak kaynaklar. Belirtilmezse mevcut arama uygulamasındaki tüm veri kaynakları kullanılır.
facetOptions[]

object (FacetOptions)
sortOptions

object (SortOptions)

Arama sonuçlarını sıralama seçenekleri
queryInterpretationOptions

object (QueryInterpretationOptions)

kullanıcı sorgusunu yorumlama seçenekleri.
contextAttributes[]

object (ContextAttribute)

Arama sonuçlarının sıralamasını ayarlamak için kullanılacak isteğe ait bağlam özellikleri. Maksimum öğe sayısı 10'dur.

Yanıt metni

Search API yanıtı. NEXT kimliği: 19

Başarılı olursa yanıt metni aşağıdaki yapıyla birlikte verileri içerir:

JSON gösterimi 
{
  "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.
}
Alanlar
queryInterpretation

object (QueryInterpretation)

kullanıcı sorgusu için sorgu yorumlama sonucu. Sorgu yorumlama devre dışıysa boş olur.
results[]

object (SearchResult)

Arama sorgusunun sonuçları.
structuredResults[]

object (StructuredResult)

Kullanıcı sorgusu için yapılandırılmış sonuçlar. Bu sonuçlar, pageSize'a göre sayılmaz.
spellResults[]

object (SpellResult)

Sorgu için önerilen yazım.
facetResults[]

object (FacetResult)

Tekrarlanan yön sonuçları.
hasMoreResults

boolean

Sorguyla eşleşen daha fazla arama sonucu olup olmadığı
debugInfo

object (ResponseDebugInfo)

Yanıtla ilgili hata ayıklama bilgileri.
errorInfo

object (ErrorInfo)

Yanıtla ilgili hata bilgileri.
resultCounts

object (ResultCounts)

Genişletilmiş sonuç sayısı bilgileri.

result_count birleşik alanı. İstenen tüm veri kaynaklarındaki toplam sonuç sayısı. Önceden tanımlanmış kaynaklar, sorgulanan veri kaynakları kümesine dahil edilmişse atlanır. Sonuç sayıları, aşağıdaki durumlarda tam sayı yerine tahmin olarak döndürülebilir:

  • Sorguda, tırnak içinde "result count exact" gibi bir kelime öbeğinde 2'den fazla terim olduğunda.

  • Değerlendirilecek benzersiz arama sonucu ACL'lerinin sayısı, makul bir gecikme süresi içinde hesaplanamayacak kadar büyük olduğunda.

Sistemin tüm belgelerde arama yapamadığı nadir durumlarda sorguyu yeniden çalıştırın. result_count aşağıdakilerden yalnızca biri olabilir:
resultCountEstimate

string (int64 format)

Bu sorgu için tahmini sonuç sayısı.
resultCountExact

string (int64 format)

Bu sorgu için tam sonuç sayısı.

Yetkilendirme kapsamları

Aşağıdaki OAuth kapsamlarından birini gerektirir:

  • https://www.googleapis.com/auth/cloud_search.query
  • https://www.googleapis.com/auth/cloud_search

Daha fazla bilgi için Yetkilendirme kılavuzu'na bakın.

QueryInterpretationOptions

kullanıcı sorgusunu yorumlama seçenekleri.

JSON gösterimi 
{
  "disableNlInterpretation": boolean,
  "enableVerbatimMode": boolean,
  "disableSupplementalResults": boolean
}
Alanlar
disableNlInterpretation

boolean

Sorguların doğal dil (NL) yorumunu devre dışı bırakma işareti. Varsayılan değer false'tur. Doğal dil yorumlamayı devre dışı bırakmak için true olarak ayarlayın. Doğal dil yorumu yalnızca önceden tanımlanmış veri kaynakları için geçerlidir.
enableVerbatimMode

boolean

Sorguların doğal dil (NL) yorumlanması, ek sonuç alma ve özel olanlar da dahil olmak üzere eş anlamlı kelimelerin kullanımı gibi tüm dahili optimizasyonları devre dışı bırakmak için bu işareti etkinleştirin. İki işaretin herhangi biri doğruysa NL yorumu devre dışı bırakılır.
disableSupplementalResults

boolean

Bir sorgu için ek sonuçları devre dışı bırakmak üzere bu işareti kullanın. SearchApplication düzeyinde seçilen ek sonuç ayarı, True olarak ayarlanırsa öncelikli olur.

QueryInterpretation

JSON gösterimi 
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason),
  "interpretedQueryActualResultCount": integer,
  "interpretedQueryEstimatedResultCount": string
}
Alanlar
interpretedQuery

string

Aramada kullanılan sorgunun yorumu. Örneğin, "Ali'den gelen e-posta" gibi doğal dil amaçlı sorgular "from:ali source:mail" olarak yorumlanır. Bu alan, neden NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY olduğunda doldurulmaz.
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

Sorgunun yorumlanma nedeni. Yorum türü NONE değilse bu alan UNSPECIFIED olmaz.
interpretedQueryActualResultCount

integer

Yorumlanan sorgu tarafından döndürülen gerçek sonuç sayısı.
interpretedQueryEstimatedResultCount

string (int64 format)

Yorumlanan sorgu tarafından döndürülen tahmini sonuç sayısı.

QueryInterpretation.InterpretationType

Sıralamalar
NONE Arama sonuçlarını getirmek için ne doğal dil yorumu ne de sorgunun daha geniş bir sürümü kullanılır.
BLEND Orijinal sorgunun sonuçları diğer sonuçlarla karıştırılır. Bu diğer sonuçların orijinal sorgunun sonuçlarıyla karıştırılma nedeni aşağıdaki "neden" alanında belirtilir.
REPLACE Orijinal sorgunun sonuçları değiştirilir. Orijinal sorgudan elde edilen sonuçların değiştirilme nedeni aşağıdaki "neden" alanında belirtilir.

QueryInterpretation.Reason

Sıralamalar
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT Arama sonuçlarını getirmek için sorgunun doğal dil yorumu kullanılır.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY Kullanıcı sorgusu için yeterli sonuç bulunmadığından ek arama sonuçları almak üzere sorguyu seçici bir şekilde genişletmek için sorgu ve doküman terimleri benzerliği kullanılır. Bu durumda yorumlanan sorgu boş olacaktır.

SearchResult

Bir dokümanla ilgili dizine eklenmiş bilgileri içeren sonuçlar. Sonraki kimlik: 16

JSON gösterimi 
{
  "title": string,
  "url": string,
  "snippet": {
    object (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
Alanlar
title

string

arama sonucunun başlığı.
url

string

Arama sonucunun URL'si. URL, Google yönlendirmesiyle asıl öğeye yönlendiriyor. Bu URL imzalıdır ve değiştirilmemelidir.
snippet

object (Snippet)

Bu sonuç için kullanılabilen tüm snippet'lerin (özetlerin) birleştirilmesi.
metadata

object (Metadata)

arama sonucunun meta verileri.
clusteredResults[]

object (SearchResult)

Kaynak kümelenmişse kümelenmiş sonuçların listesini sağlayın. Yalnızca bir düzeyde kümelenmiş sonuçlar gösterilir. Mevcut kaynak kümeleme için etkinleştirilmemişse bu alan boş olur.
debugInfo

object (ResultDebugInfo)

Bu arama sonucuyla ilgili hata ayıklama bilgileri.

Snippet

Sonuç sayfasının içeriğini özetleyen arama sonucu snippet'i.

JSON gösterimi 
{
  "snippet": string,
  "matchRanges": [
    {
      object (MatchRange)
    }
  ]
}
Alanlar
snippet

string

Dokümanın snippet'i. Oluşturulmadan önce kod dışına çıkarılması gereken, kod dışına çıkarılmış HTML karakteri içerebilir.
matchRanges[]

object (MatchRange)

Snippet'teki eşleşen aralıklar.

MatchRange

Bir snippet'in eşleşen aralığı [başlangıç, bitiş).

JSON gösterimi 
{
  "start": integer,
  "end": integer
}
Alanlar
start

integer

Snippet'teki eşleşmenin başlangıç konumu.
end

integer

Snippet'te maçın sonu.

Meta veri

eşleşen arama sonucunun meta verileri.

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

object (Source)

Sonucun adlandırılmış kaynağı (ör. Gmail).
mimeType

string

Arama sonucunun MIME türü.
thumbnailUrl

string

Sonucun küçük resim URL'si.
owner

object (Person)

Dokümanın veya arama sonucu nesnesinin sahibi (genellikle oluşturucusu).
createTime

string (Timestamp format)

Arama sonucundaki bu dokümanın veya nesnenin oluşturulma zamanı.

Zaman damgasında RFC 3339 kullanılır. Yani oluşturulan çıkış her zaman Z ile normalleştirilir ve 0, 3, 6 veya 9 kesirli basamak kullanılır. "Z" dışındaki zaman farkları da kabul edilir. Örnekler: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" veya "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

Arama sonucundaki nesnenin son değiştirilme tarihi. Öğede ayarlanmamışsa burada döndürülen değer boştur. updateTime, güncelliği hesaplamak için kullanılır ve ayarlanmamışsa bu değer, geçerli zamandan itibaren 2 yıl olarak ayarlanır.

Zaman damgasında RFC 3339 kullanılır. Yani oluşturulan çıkış her zaman Z ile normalleştirilir ve 0, 3, 6 veya 9 kesirli basamak kullanılır. "Z" dışındaki zaman farkları da kabul edilir. Örnekler: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" veya "2014-10-02T15:01:23+05:30".
fields[]

object (NamedProperty)

Yapılandırılmış verilerdeki dizine eklenmiş alanlar, genel adlandırılmış özellik olarak döndürülür.
displayOptions

object (ResultDisplayMetadata)

Yapılandırılmış veri arama sonucunun nasıl görüntüleneceğini belirten seçenekler.
objectType

string

Arama sonucunun nesne türü.

ResultDisplayMetadata

JSON gösterimi 
{
  "objectTypeLabel": string,
  "metalines": [
    {
      object (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
Alanlar
objectTypeLabel

string

Nesnenin görüntüleme etiketi.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

Sonuçla birlikte gösterilecek meta satırları içeriği.

ResultDisplayMetadata.ResultDisplayLine

Görüntülenen bir satırı oluşturan alanlar koleksiyonu

JSON gösterimi 
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
Alanlar
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

query.search sonuçları için görüntülenen alanlar

JSON gösterimi 
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
Alanlar
label

string

Tesisin görünen etiketi.
operatorName

string

Tesisin işletmecisinin adı.
property

object (NamedProperty)

Özelliğin ad-değer çifti.

ResultDebugInfo

Sonuçla ilgili hata ayıklama bilgileri.

JSON gösterimi 
{
  "formattedDebugInfo": string
}
Alanlar
formattedDebugInfo

string

Görüntüleme için biçimlendirilmiş genel hata ayıklama bilgileri.

StructuredResult

Arama isteğinin bir parçası olarak döndürülen yapılandırılmış sonuçlar.

JSON gösterimi 
{

  // 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.
}
Alanlar

structured_result birleşik alanı.

structured_result aşağıdakilerden yalnızca biri olabilir:
person

object (Person)

Bir kişinin temsili

SpellResult

JSON gösterimi 
{
  "suggestedQuery": string,
  "suggestionType": enum (SpellResult.SuggestionType),
  "suggestedQueryHtml": {
    object (SafeHtmlProto)
  }
}
Alanlar
suggestedQuery

string

Sorgunun önerilen yazımı.
suggestionType

enum (SpellResult.SuggestionType)

geçerli sorgu için öneri tetiklenir.
suggestedQueryHtml

object (SafeHtmlProto)

Kullanıcı arayüzünde kullanılabilen, yazımı düzeltilmiş sorguyu temsil eden temizlenmiş HTML. Bu genellikle, sorgunun yazım denetimi yapılan kısımlarını işaretlemek için dile özgü etiketler içerir.

SpellResult.SuggestionType

Sorgu için tetiklenen öneri türü.

Sıralamalar
SUGGESTION_TYPE_UNSPECIFIED Varsayılan yazım denetimi türü
NON_EMPTY_RESULTS_SPELL_SUGGESTION Sonuç değiştirilmeden yazım önerisi. Sonuçlar, sıfır olmayan sonuçlar içeren orijinal sorgu için gösterilmeye devam ederken sonuç içerecek yazım önerisi de gösterilir.
ZERO_RESULTS_FULL_PAGE_REPLACEMENT Orijinal sorgu sonuç içermediğinde yazım önerisi tetiklenir. Orijinal sorgu sonuç vermediğinde ve yazım önerisi sonuç verdiğinde, yazımı düzeltilmiş sorgunun sonuçlarını tetikleriz.

SafeHtmlProto

ÖNEMLİ: Saldırganların, türün güvenlik sözleşmesini karşılamayan serileştirilmiş iletiler oluşturması kolay olduğundan (örneğin, saldırgan tarafından kontrol edilen bir komut dosyası içerebilir) bu iletiyi güvenilmeyen bir kaynaktan kabul etmek güvenli değildir. SafeHtmlProto alan bir sistem, SafeHtmlProto'nun üreticisine örtülü olarak güvenir. Bu nedenle, bu mesajı RPC yanıtlarında döndürmek genellikle güvenli olsa da RPC isteklerinde kabul etmek genellikle güvenli değildir.

JSON gösterimi 
{
  "privateDoNotAccessOrElseSafeHtmlWrappedValue": string
}
Alanlar
privateDoNotAccessOrElseSafeHtmlWrappedValue

string

ÖNEMLİ: Bu alanı testlerden bile olsa asla ayarlamayın veya okumayın. Bu alan özeldir. Bu mesajı oluşturmak veya okumak için kullanılacak programlama dili paketleri hakkında bilgi edinmek üzere .proto dosyasının üst kısmındaki dokümanlara bakın.

FacetResult

Kaynağa özgü yön yanıtı

JSON gösterimi 
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
Alanlar
sourceName

string

Faset sonuçlarının döndürüldüğü kaynak adı. Boş olmayacak.
objectType

string

Faset sonuçlarının döndürüldüğü nesne türü. Boş olabilir.
operatorName

string

Facet oluşturma için seçilen operatörün adı. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

Yanıtın değerleri için, ilgili filtreyle en az bir sonuç içeren FacetBuckets.

FacetBucket

Bir yönün içindeki grup, temel işlem birimidir. Bir grup, gruplandırılan alanın türüne bağlı olarak tek bir değer VEYA bitişik bir değer aralığı içerebilir. FacetBucket şu anda yalnızca yanıt nesnesini döndürmek için kullanılmaktadır.

JSON gösterimi 
{
  "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.
}
Alanlar
count

integer

Paket değeriyle eşleşen sonuç sayısı. Sayım doğruluğu sağlandığında yalnızca arama için sonuç döndürülür. Cloud Search, hiçbir sorgu için yön sayısı garantisi vermez ve yön sayıları, aynı sorgular için bile yalnızca aralıklı olarak gösterilebilir. Faset sayısı varlığına bağımlılık oluşturmayın. Bunun yerine, her zaman döndürülen faset sayısı yüzdelerini kullanın.
percentage

integer

Paket değeriyle eşleşen sonuçların yüzdesi. Döndürülen değer (0-100] arasındadır ve kesirli ise tam sayıya yuvarlanır. Değer açıkça döndürülmüyorsa 0'a yuvarlanan bir yüzde değerini temsil eder. Yüzdeler tüm aramalar için döndürülür ancak bunlar tahmini değerlerdir. Yüzdeler her zaman döndürüldüğünden, sayı yerine yüzdeleri oluşturmanız gerekir.
filter

object (Filter)

İlgili grup seçilirse arama isteğinde iletilecek filtre.
bucket_value birleşik alanı. Fasetlenen grubun aralığı veya değeri bucket_value yalnızca aşağıdakilerden biri olabilir:
value

object (Value)

ResponseDebugInfo

Yanıtla ilgili hata ayıklama bilgileri.

JSON gösterimi 
{
  "formattedDebugInfo": string
}
Alanlar
formattedDebugInfo

string

Görüntüleme için biçimlendirilmiş genel hata ayıklama bilgileri.

ErrorInfo

Yanıtla ilgili hata bilgileri.

JSON gösterimi 
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
Alanlar
errorMessages[]

object (ErrorMessage)

ErrorMessage

Kaynak yanıtı başına hata mesajı.

JSON gösterimi 
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
Alanlar
source

object (Source)
errorMessage

string

ResultCounts

Sonuç sayısı bilgileri

JSON gösterimi 
{
  "sourceResultCounts": [
    {
      object (SourceResultCount)
    }
  ]
}
Alanlar
sourceResultCounts[]

object (SourceResultCount)

Sonuç içeren her kaynak için sonuç sayısı bilgileri.

SourceResultCount

Kaynak sonucu başına sayı bilgileri.

JSON gösterimi 
{
  "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.
}
Alanlar
source

object (Source)

Sonuç sayısı bilgilerinin ilişkilendirildiği kaynak.
hasMoreResults

boolean

Bu kaynak için daha fazla arama sonucu olup olmadığı.

result_count birleşik alanı.

result_count aşağıdakilerden yalnızca biri olabilir:
resultCountEstimate

string (int64 format)

Bu kaynak için tahmini sonuç sayısı.
resultCountExact

string (int64 format)

Bu kaynağın tam sonuç sayısı.