Query API, arama arayüzü oluşturmak veya bir uygulamaya arama sonuçları yerleştirmek için arama ve öneri yöntemleri sunar.
Minimum gereksinimleri olan web uygulamaları için arama widget'ını kullanabilirsiniz. Daha fazla bilgi için Arama widget'ıyla arama arayüzü oluşturma bölümüne bakın
Arama arayüzü oluşturma
Minimal arama arayüzü oluşturmak için birkaç adım gerekir:
- Bir arama uygulamasını yapılandırın
- Uygulama için OAuth kimlik bilgileri oluşturma
- Dizini sorgulama
- Sorgu sonuçlarını görüntüleme
Sayfalama, sıralama, filtreleme, özellikler ve otomatik öneri gibi özelliklerle arama arayüzünü daha da geliştirebilirsiniz.
Bir arama uygulamasını yapılandırın
Oluşturduğunuz her arama arayüzüyle ilişkilendirmek için en az bir arama uygulaması oluşturmanız gerekir. Bir arama uygulaması, sorgu için kullanılacak veri kaynakları, sıralama düzeni, filtreler ve istenecek özellikler gibi varsayılan parametreleri sağlar. Gerekirse query API'yi kullanarak bu parametreleri geçersiz kılabilirsiniz.
Arama uygulamaları hakkında daha fazla bilgi için Cloud Search'te arama deneyimini özelleştirme bölümüne bakın.
Uygulama için OAuth kimlik bilgileri oluşturma
Google Cloud Search API'ye erişimi yapılandırma bölümündeki adımlara ek olarak, web uygulaması için OAuth kimlik bilgileri de oluşturmanız gerekir. Oluşturduğunuz kimlik bilgilerinin türü, API'nin kullanıldığı bağlama bağlıdır.
Kullanıcı adına yetkilendirme istemek için kimlik bilgilerini kullanın. Yetkilendirme talep ederken https://www.googleapis.com/auth/cloud_search.query
kapsamını kullanın.
OAuth seçenekleri ve istemci kitaplıkları hakkında daha fazla bilgi için [Google Kimlik Platformu](https://developers.google.com/identity/choose-auth{: .external target="_blank"}) sayfasını inceleyin.
Dizini sorgulama
Dizine göre arama yapmak için search
yöntemini kullanın.
Her istek iki bilgi içermelidir: öğelerin eşleştirileceği bir query
metni ve kullanılacak arama uygulamasının kimliğini tanımlayan bir searchApplicationId
.
Aşağıdaki snippet'te Titanic filminin film veri kaynağına gönderilen bir sorgu gösterilmektedir:
{
"query": "titanic",
"requestOptions": {
"searchApplicationId": "searchapplications/<search_app_id>"
},
}
Sorgu sonuçlarını görüntüle
En azından, arama arayüzlerinin orijinal öğenin bir bağlantısının yanı sıra title
öğesini görüntülemesi beklenir. Arama sonuçlarında bulunan snippet ve meta veriler gibi ek bilgilerden yararlanarak arama sonuçlarının görünümünü daha da iyileştirebilirsiniz.
Ek sonuçları işleme
Varsayılan olarak, kullanıcının sorgusu için yeterli sonuç olmadığında Cloud Search ek sonuçlar döndürür. Yanıttaki queryInterpretation
alanı, ek sonuçların ne zaman döndürüleceğini belirtir. Yalnızca ek sonuçlar döndürülürse InterpretationType
değeri REPLACE
olarak ayarlanır. Orijinal sorgu için ek sonuçlarla birlikte birkaç sonuç döndürülürse InterpretationType
, BLEND
olarak ayarlanır. Her iki durumda da
QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY
.
Bazı ek sonuçlar döndürüldüğünde ek sonuçların döndürüldüğünü belirten bir metin ekleyebilirsiniz. Örneğin, REPLACE
olması durumunda "Orijinal sorgunuzla ilgili aramanız hiçbir sonuçla eşleşmedi. Benzer sorgular için sonuçlar gösteriliyor."
BLEND
olması durumunda, "Orijinal sorgunuzla yaptığınız arama yeterli sonuçla eşleşmedi. Benzer sorgulara ilişkin
sonuçlar dahil."
Kullanıcı sonuçlarını işleme
Cloud Search iki tür "kişi sonucu" döndürür: sorguda adı kullanılan kişiyle ilgili belgeler ve sorguda adı kullanılan kişinin çalışan bilgileri. İkinci sonuç türü, Cloud Search'ün Kişi Arama özelliğinin bir işlevidir. Bu tür bir sorguyla ilgili sonuçlar, sorgu API yanıtının structuredResults
alanında bulunabilir:
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
Doğrudan Rapor Eşleştirme
Doğrudan Rapor Eşleştirme, Cloud Search'ün bir Kişi Arama özelliğidir ve kullanıcıların, kuruluşlarındaki bir kişinin doğrudan raporlarını görmesine olanak tanır.
Sonuç, structuredResults
alanında mevcuttur.
Bir kişinin yöneticisi veya bağlı çalışanlarıyla ilgili sorgular için yanıtta structuredResults
içinde bir assistCardProtoHolder
bulunur. assistCardProtoHolder
sütununda RELATED_PEOPLE_ANSWER_CARD
değerine eşit olan cardType
adlı bir alan vardır. assistCardProtoHolder
, gerçek yanıtı içeren relatedPeopleAnswerCard
adlı bir kart içerir.
subject
(sorguya dahil edilen kullanıcı) ve konuyla ilgili kişi kümesi olan relatedPeople
öğelerini içerir. relationType
alanı, MANAGER
veya DIRECT_REPORTS
değerini döndürür.
Aşağıdaki kod, sorguyla eşleşen doğrudan raporlar için örnek bir yanıt gösterilmektedir:
{
"results": [],
"structuredResults": [{
"assistCardProtoHolder": {
"extensions": {
"@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",
"cardMetadata": {
"cardCategory": "ANSWER"
},
"cardType": "RELATED_PEOPLE_ANSWER_CARD",
"relatedPeopleAnswerCard": {
"subject": {
"email": "AdamStanford@psincs-test01.newjnj.com",
"displayName": "Adam Stanford"
"manager": {
"email": "simonsais@psincs-test01.newjnj.com"
}
},
"relatedPeople": [{
"email": "EdgarMountainRamirez@psincs-test01.newjnj.com",
"displayName": "Edgar Mountain Ramirez"
}, {
"email": "FranciscoJoseMartinez@psincs-test01.newjnj.com",
"displayName": "Francisco Jose Martinez"
}],
"relationType": "DIRECT_REPORTS",
}
}
}
}]
}
Ek sonuçlar dahil optimizasyonları kapatın
Ek sonuçlar gibi optimizasyonlar varsayılan olarak etkindir. Ancak tüm optimizasyonları veya hem arama uygulaması hem de sorgu düzeyinde ek sonuçları devre dışı bırakabilirsiniz:
Ek sonuçlar, eş anlamlılar ve yazım düzeltmeleri dahil olmak üzere arama uygulaması düzeyindeki tüm optimizasyonları devre dışı bırakmak için arama uygulamalarında
QueryInterpretationConfig.force_verbatim_mode
değerinitrue
olarak ayarlayın.Ek sonuçlar, eş anlamlılar ve yazım düzeltmeleri dahil olmak üzere arama sorgusu düzeyindeki tüm optimizasyonları devre dışı bırakmak için arama sorgusunda
QueryInterpretationOptions.enableVerbatimMode
değerinitrue
olarak ayarlayın.Arama uygulaması düzeyinde ek sonuçları devre dışı bırakmak için arama sorgusunda
QueryInterpretationOptions.forceDisableSupplementalResults
değerinitrue
olarak ayarlayın.Arama sorgusu düzeyinde ek sonuçları devre dışı bırakmak için arama sorgusunda
QueryInterpretationOptions.disableSupplementalResults
değerinitrue
olarak ayarlayın.
Öne çıkan snippet'ler
Dizine eklenmiş metin veya HTML içeriği barındıran öğeler için içeriğin bir snippet'i döndürülür. Bu içerik, kullanıcıların iade edilen öğenin alaka düzeyini belirlemelerine yardımcı olur.
Snippet'te sorgu terimleri varsa terimlerin konumunu tanımlayan bir veya daha fazla eşleşme aralığı da döndürülür.
Sonuçları oluştururken eşleşen metni vurgulamak için matchRanges
özelliğini kullanın. Aşağıdaki JavaScript örneği, snippet'i her eşleşen aralık bir <span>
etiketine sarmalanmış şekilde HTML işaretlemesine dönüştürür.
function highlightSnippet(snippet) {
let text = snippet.snippet;
let formattedText = text;
if (snippet.matchRanges) {
let parts = [];
let index = 0;
for (let match of snippet.matchRanges) {
let start = match.start || 0; // Default to 0 if omitted
let end = match.end;
if (index < start) { // Include any leading text before/between ranges
parts.push(text.slice(index, start));
}
parts.push('<span class="highlight">');
parts.push(text.slice(start, end));
parts.push('</span>');
index = end;
}
parts.push(text.slice(index)); // Include any trailing text after last range
formattedText = parts.join('');
}
return formattedText;
}
Snippet'e göre:
{
"snippet": "This is an example snippet...",
"matchRanges": [
{
"start": 11,
"end": 18
}
]
}
Elde edilen HTML dizesi şöyle olur:
This is an <span class="highlight">example</span> snippet...
Meta verileri görüntüleme
Döndürülen öğe hakkında kullanıcılar için alakalı olabilecek ek bilgileri görüntülemek için metadata
alanını kullanın. metadata
alanı, öğenin createTime
ve updateTime
özelliklerinin yanı sıra öğeyle ilişkili tüm döndürülebilir yapılandırılmış verileri içerir.
Yapılandırılmış verileri görüntülemek için displayOptions
alanını kullanın. displayOptions
alanı, nesne türü için görüntü etiketini ve bir metalines
grubunu içerir. Her meta satır, şemada yapılandırıldığı şekliyle bir görüntü etiketleri ve değer çiftleri dizisidir.
Ek sonuçları al
Ek sonuçları almak için istekteki start
alanını istenen ofsete ayarlayın. pageSize
alanı ile her sayfanın boyutunu ayarlayabilirsiniz.
İade edilen öğe sayısını veya iade edilen öğelerle ilgili sayfa kontrollerini görüntülemek için resultCount
alanını kullanın. Sonuç kümesinin boyutuna bağlı olarak gerçek değer veya tahmini bir değer sağlanır.
Sıralama sonuçları
İade edilen öğelerin sırasını belirtmek için sortOptions
alanını kullanın. sortOptions
değeri, iki alanı olan bir nesnedir:
operatorName
: Yapılandırılmış veri özelliği için sıralamada kullanılacak bir operatör. Birden fazla operatöre sahip mülkler için yalnızca ana eşitlik operatörü kullanarak sıralama yapabilirsiniz.sortOrder
— sıralama yönü (ASCENDING
veyaDESCENDING
).
Alaka düzeyi ayrıca ikincil sıralama anahtarı olarak kullanılır. Bir sorguda sıralama düzeni belirtilmezse sonuçlar yalnızca alaka düzeyine göre sıralanır.
"sortOptions": {
"operatorName": "priority",
"sortOrder": "DESCENDING"
}
Filtre ekleyin
Sorgu ifadelerine ek olarak, filtreler uygulayarak sonuçları daha da kısıtlayabilirsiniz. Filtreleri hem arama uygulamasında hem de arama isteğinde belirtebilirsiniz.
Bir istek veya arama uygulamasına filtre eklemek için filtreyi dataSourceRestrictions.filterOptions[]
alanına ekleyin.
Bir veri kaynağını daha ayrıntılı filtrelemenin 2 temel yolu vardır:
filterOptions[].objectType
özelliği aracılığıyla nesne filtreleri, eşleşen öğeleri özel bir şemada tanımlandığı şekilde belirtilen türle kısıtlar.- Değer filtreleri: Eşleşen öğeleri sorgu operatörüne ve sağlanan değere göre kısıtlar.
Bileşik filtreler, daha karmaşık sorgular için birden çok değer filtresini mantıksal ifadelerle birleştirmeyi sağlar.
Film şeması örneğinde, mevcut kullanıcıya göre bir yaş kısıtlaması uygulayabilir ve kullanılabilir filmleri MPAA derecelendirmesine göre kısıtlayabilirsiniz.
{
"query": "adventure",
"requestOptions": {
"searchApplicationId": "<search_app_id>"
},
"dataSourceRestrictions": [
{
"source": {
"name": "datasources/<data_source_id>"
},
"filterOptions": [
{
"objectType": "movie",
"filter": {
"compositeFilter": {
"logicOperator": "AND"
"subFilters": [
{
"compositeFilter": {
"logicOperator": "OR"
"subFilters": [
{
"valueFilter": {
"operatorName": "rated",
"value": {
"stringValue": "G"
}
}
},
{
"valueFilter": {
"operatorName": "rated",
"value": {
"stringValue": "PG"
}
}
}
]
}
]
}
}
}
]
}
]
}
Özelliklerle sonuçları hassaslaştırma
Özellikler, arama sonuçlarını hassaslaştırmak için kategorileri temsil eden dizine eklenmiş özelliklerdir. Kullanıcıların sorgularını etkileşimli bir şekilde hassaslaştırmasına ve alakalı öğeleri daha hızlı bulmasına yardımcı olmak için özellikleri kullanın.
Özellikler arama uygulamanızda tanımlanabilir ve sorgunuzdaki ayarlar tarafından geçersiz kılınabilir.
Özellikler istendiğinde, Cloud Search eşleşen öğeler arasından istenen özellikler için en sık geçen değerleri hesaplar. Bu değerler yanıtta döndürülür. Sonraki sorgularda sonuçları daraltan filtreler oluşturmak için bu değerleri kullanın.
Özelliklerle tipik etkileşim kalıbı:
- Özellik sonuçlarına hangi özelliklerin dahil edileceğini belirten bir ilk sorgu yapın.
- Arama ve özellik sonuçlarını oluşturun.
- Kullanıcı, sonuçları hassaslaştırmak için bir veya daha fazla özellik değeri seçer.
- Seçili değerleri temel alan bir filtreyle sorguyu tekrarlayın.
Örneğin, film sorgularının yıla ve MPAA derecelendirmesine göre ayrıntılandırmasını etkinleştirmek için sorguya facetOptions
özelliğini ekleyin.
"facetOptions": [
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "year"
},
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "rated"
}
]
Tam sayı tabanlı alanlara sahip özellik sonuçları
Ayrıca, tam sayı tabanlı alanlarla istek sonuçlarını da değerlendirebilirsiniz. Örneğin, "100-200" sayfası olan kitaplar hakkındaki arama sonuçlarını hassaslaştırmak için book_pages
adlı bir tam sayı özelliğini özellikli bir tam sayı olarak işaretleyebilirsiniz.
Tam sayı özellik alanı şemanızı ayarlarken isFacetable
değerini true
olarak ayarlayın ve ilgili paketleme seçeneklerini integerPropertyOptions
öğesine ekleyin.
Bu, her bir tamsayı özellikli özellikte varsayılan paketleme seçeneklerinin tanımlanmasını sağlar.
Paketleme seçenekleri mantığını tanımlarken, aralıkları belirten bir dizi artımlı değer sağlayın. Örneğin, son kullanıcı aralıkları 2, 5, 10, 100
olarak belirtirse <2
, [2-5)
, [5-10)
, [10-100)
, >=100
özellikleri hesaplanır.
İstekte facetOptions
için aynı paketleme seçeneklerini tanımlayarak tam sayı tabanlı özellikleri geçersiz kılabilirsiniz. Gerekirse Cloud Search, arama uygulamasında veya sorgu isteğinde özellik seçenekleri tanımlanmamışsa şemada tanımlanan paketleme seçeneklerini kullanır. Sorguda tanımlanan façetalar, arama uygulamasında tanımlanan özelliklere göre önceliklidir ve arama uygulamasında tanımlanan özellikler, şemada tanımlanan özelliklere göre önceliklidir.
Doküman boyutuna veya tarihe göre özellik sonuçları
Arama sonuçlarını dokümanın dosya boyutuna, bayt cinsinden ölçülenne veya bir dokümanın oluşturulma ya da değiştirilme zamanına göre daraltmak için ayrılmış operatörleri kullanabilirsiniz. Özel bir şema tanımlamanız gerekmez ancak arama uygulamanızın FacetOptions
öğesinde operatorName
değerini belirtmeniz gerekir.
- Doküman boyutuna göre özellik belirleme için
itemsize
öğesini kullanın ve paketleme seçeneklerini tanımlayın. - Doküman oluşturma tarihine göre özellik belirleme için
createddatetimestamp
öğesini kullanın. - Dokümanın değiştirilme tarihine göre özellik belirleme için
lastmodified
işlevini kullanın.
Özellik paketlerini yorumlama
Arama sorgusu yanıtındaki facetResults
özelliğinde, her bucket
için filter
alanında kullanıcının tam filtre isteği yer alır.
Tam sayılara dayalı olmayan özellikler için facetResults
, istenen her özellik için bir giriş içerir. Her özellik için buckets
adlı bir değerler veya aralık listesi sağlanır. En sık geçen değerler önce gösterilir.
Kullanıcı filtre uygulamak üzere bir veya daha fazla değer seçtiğinde, seçilen filtrelerle yeni bir sorgu oluşturun ve API'yi tekrar sorgulayın.
Öneri ekle
Kullanıcının kişisel sorgu geçmişinin yanı sıra kişilerin ve kullanıcının belge topluluğuna göre sorguların otomatik olarak tamamlanmasını sağlamak için suggest API'yi kullanın.
Örneğin, aşağıdaki çağrıda jo kısmi kelime öbeği için öneriler sunulmaktadır.
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
Ardından, elde edilen önerileri uygulamanıza uygun şekilde görüntüleyebilirsiniz.