Sorgu API'si, arama arayüzü oluşturmak veya arama sonuçlarını bir uygulamaya yerleştirmek için arama ve öneri yöntemleri sağlar.
Minimum gereksinimleri olan web uygulamaları için arama widget'ını kullanabilirsiniz. Daha fazla bilgi için Arama widget'ı ile arama arayüzü oluşturma başlıklı makaleyi inceleyin.
Arama arayüzü oluşturma
Minimum düzeyde bir arama arayüzü oluşturmak için birkaç adım gerekir:
- Arama uygulamasını yapılandırma
- Uygulama için OAuth kimlik bilgileri oluşturma
- Dizini sorgulama
- Sorgu sonuçlarını görüntüleme
Sayfalama, sıralama, filtreleme, yönler ve otomatik öneri gibi özelliklerle arama arayüzünü daha da geliştirebilirsiniz.
Arama uygulamasını yapılandırma
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 varsayılan parametreleri (kullanılacak veri kaynakları, sıralama düzeni, filtreler ve istenecek özellikler gibi) sağlar. Gerekirse sorgu API'sini kullanarak bu parametreleri geçersiz kılabilirsiniz.
Arama uygulamaları hakkında daha fazla bilgi için Cloud Search'te arama deneyimini özelleştirme başlıklı makaleyi inceleyin.
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 bilgisi türü, API'nin kullanıldığı bağlama bağlıdır.
Kullanıcı adına yetkilendirme isteğinde bulunmak için kimlik bilgilerini kullanın. Yetkilendirme isteğinde bulunurken 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 Identity Platform](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 metin query
ve arama uygulamasının kullanacağı kimliği tanımlayan bir searchApplicationId
.
Aşağıdaki snippet'te, Titanic filmiyle ilgili film veri kaynağına yönelik bir sorgu gösterilmektedir:
{
"query": "titanic",
"requestOptions": {
"searchApplicationId": "searchapplications/<search_app_id>"
},
}
Sorgu sonuçlarını görüntüleme
Arama arayüzlerinin en azından title
öğesini ve orijinal öğenin bağlantısını göstermesi beklenir. Arama sonuçlarında bulunan snippet ve meta veriler gibi ek bilgilerden yararlanarak arama sonuçlarının görüntülenmesini daha da iyileştirebilirsiniz.
Ek sonuçları işleme
Cloud Search, varsayılan olarak kullanıcının sorgusu için yeterli sonuç olmadığında ek sonuçlar döndürür. Yanıttaki queryInterpretation
alanı, ek sonuçların ne zaman döndürüldüğünü gösterir. Yalnızca ek sonuçlar döndürülürse InterpretationType
, 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 sağlayabilirsiniz. Örneğin, REPLACE
durumunda "Orijinal sorgunuz için yaptığınız arama hiçbir sonuçla eşleşmedi. Benzer sorgular için sonuçlar gösteriliyor."
BLEND
durumunda, "Orijinal sorgunuz için yaptığınız arama yeterli sonuçla eşleşmedi. Benzer sorgular için sonuçlar dahil edilir."
Kullanıcı sonuçlarını işleme
Cloud Search iki tür "kişi sonucu" döndürür: sorguda adı kullanılan bir kişiyle ilgili dokümanlar ve sorguda adı kullanılan bir kişinin çalışan bilgileri. İkinci sonuç türü, Cloud Search'in Kişi Arama özelliğinin bir işlevidir ve bu tür bir sorgunun sonuçları, sorgu API yanıtının structuredResults
alanında bulunabilir:
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
Doğrudan Çalışan Eşleştirme
Doğrudan Raporlayan Eşleştirme, Cloud Search'ın kullanıcıların kuruluşlarındaki bir kişinin doğrudan raporlayanlarını görmesine olanak tanıyan Kişi Arama özelliğidir.
Sonuç, structuredResults
alanında kullanılabilir.
Bir kullanıcının yöneticisi veya doğrudan raporları hakkındaki sorgularda yanıtta structuredResults
içinde assistCardProtoHolder
yer alır. assistCardProtoHolder
, RELATED_PEOPLE_ANSWER_CARD
ile eşit olacak cardType
adlı bir alana sahiptir. assistCardProtoHolder
, gerçek yanıtı içeren relatedPeopleAnswerCard
adlı bir kart içerir.
Bu veri türü, subject
(sorguya dahil edilen kişi) ve konuyla ilgili kişi grubu olan relatedPeople
öğelerini içerir. relationType
alanı MANAGER
veya DIRECT_REPORTS
değerini döndürür.
Aşağıdaki kodda, doğrudan rapor eşleştirme sorgusu 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ı devre dışı bırakma
Ek sonuçlar gibi optimizasyonlar varsayılan olarak etkindir. Ancak hem arama uygulamasında hem de sorgu düzeyinde tüm optimizasyonları veya yalnızca 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.Ek sonuçları arama uygulaması düzeyinde 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.
Snippet'leri vurgulama
Dizine eklenen metin veya HTML içeriği içeren döndürülen öğ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 belirlemesine 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
simgesini kullanın. Aşağıdaki JavaScript örneğinde, eşleşen her aralık <span>
etiketine sarmalanarak snippet HTML işaretçisine dönüştürülü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;
}
Aşağıdaki snippet'te:
{
"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...
Yayınlanan içerik meta verisi
İade edilen öğeyle ilgili kullanıcılar için alakalı olabilecek ek bilgileri görüntülemek üzere metadata
alanını kullanın. metadata
alanı, öğenin createTime
ve updateTime
değerini ve öğeyle ilişkili iade edilebilir tüm 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ünün görünen etiketini ve bir metalines
grubunu içerir. Her metaline, şemada yapılandırıldığı şekilde bir dizi görüntüleme etiketi ve değer çiftidir.
Ek sonuçlar alma
Daha fazla sonuç almak için istekteki start
alanını istediğiniz ofset değerine ayarlayın. pageSize
alanını kullanarak her sayfanın boyutunu ayarlayabilirsiniz.
İade edilen öğelerin sayısını görüntülemek veya iade edilen öğeler arasında gezinmek için sayfalama denetimlerini görüntülemek üzere 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 alana sahip bir nesnedir:
operatorName
: Yapılandırılmış veri mülkünün sıralanacağı operatör. Birden fazla operatöre sahip mülkler için yalnızca ana eşitlik operatörünü kullanarak sıralama yapabilirsiniz.sortOrder
: Sıralama yönü (ASCENDING
veyaDESCENDING
).
Alaka düzeyi, ikincil sıralama anahtarı olarak da kullanılır. Sorguda sıralama düzeni belirtilmezse sonuçlar yalnızca alaka düzeyine göre sıralanır.
"sortOptions": {
"operatorName": "priority",
"sortOrder": "DESCENDING"
}
Filtre ekleme
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ı şekilde filtrelemenin iki temel yolu vardır:
filterOptions[].objectType
mülkü 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 bir sorgu operatörüne ve sağlanan değere göre kısıtlar.
Bileşik filtreler, daha karmaşık sorgular için birden fazla değer filtresinin mantıksal ifadelerle birleştirilmesine olanak tanır.
Film şeması örneğinde, mevcut kullanıcıya göre bir yaş kısıtlaması uygulayabilir ve mevcut 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"
}
}
}
]
}
]
}
}
}
]
}
]
}
Yönlerle sonuçları hassaslaştırma
Özellikler, arama sonuçlarını hassaslaştırmak için kategorileri temsil eden dizine eklenen özelliklerdir. Kullanıcıların sorgularını etkileşimli olarak hassaslaştırmalarına ve alakalı öğeleri daha hızlı bulmalarına yardımcı olmak için yönleri kullanın.
Yönler arama uygulamanızda tanımlanabilir ve sorgunuzdaki ayarlarla geçersiz kılınabilir.
Cloud Search, boyut isteğinde bulunurken eşleşen öğeler arasında istenen özellikler için en sık kullanılan 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.
Yönlerle tipik etkileşim şekli şudur:
- Kelime öbeği sonuçlarına hangi özelliklerin dahil edileceğini belirten ilk bir sorgu oluşturun.
- Arama ve yön sonuçlarını oluşturun.
- Kullanıcı, sonuçları hassaslaştırmak için bir veya daha fazla özellik değeri seçer.
- Sorguyu, seçilen değerlere dayalı bir filtreyle tekrarlayın.
Örneğin, film sorgularının yıla ve MPAA derecelendirmesine göre hassaslaştırılmasını sağlamak için sorguya facetOptions
mülkünü ekleyin.
"facetOptions": [
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "year"
},
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "rated"
}
]
Tamsayı tabanlı alanlara sahip facet sonuçları
Sonuçları, tam sayıya dayalı alanlarla da gruplandırabilirsiniz. Örneğin, "100-200" sayfası olan kitaplarla ilgili bir aramanın sonuçlarını hassaslaştırmak için book_pages
adlı bir tam sayı özelliğini yüze bölünebilir olarak işaretleyebilirsiniz.
Tam sayı mülk alanı şemanızı ayarlarken isFacetable
değerini true
olarak ayarlayın ve integerPropertyOptions
alanına karşılık gelen gruplandırma seçeneklerini ekleyin.
Bu sayede, her tam sayı tablosu özelliği için varsayılan gruplandırma seçenekleri tanımlanır.
Paketleme seçenekleri mantığını tanımlarken aralıkları belirten bir artımlı değer dizisi sağlayın. Örneğin, son kullanıcı aralıkları 2, 5, 10, 100
olarak belirtirse <2
, [2-5)
, [5-10)
, [10-100)
, >=100
için yönler hesaplanır.
İstekte aynı gruplandırma seçeneklerini facetOptions
olarak tanımlayarak tam sayıya dayalı özellikleri geçersiz kılabilirsiniz. Gerekirse Cloud Search, arama uygulamasında veya sorgu isteğinde facet seçenekleri tanımlanmadığında şemada tanımlanan gruplandırma seçeneklerini kullanır. Sorguda tanımlanan özellikleri, arama uygulamasında tanımlanan özellikler, arama uygulamasında tanımlanan özellikler de şemada tanımlanan özelliklerden önceliklidir.
Doküman boyutuna veya tarihine göre ayrılmış sonuçlar
Arama sonuçlarını, bayt cinsinden ölçülen doküman dosya boyutuna veya dokümanın oluşturulduğu ya da değiştirildiği zamana göre daraltmak için ayrılmış operatörleri kullanabilirsiniz. Özel bir şema tanımlamanız gerekmez ancak arama uygulamanızın FacetOptions
bölümünde operatorName
değerini belirtmeniz gerekir.
- Belge boyutuna göre segmentlere ayırmak için
itemsize
simgesini kullanın ve gruplandırma seçeneklerini tanımlayın. - Doküman oluşturma tarihine göre segmentlere ayırmak için
createddatetimestamp
değerini kullanın. - Belgenin değiştirildiği tarihe göre segmentlere ayırmak için
lastmodified
değerini kullanın.
Özellik grubu paketlerini yorumlama
Arama sorgusu yanıtındaki facetResults
mülkü, her bucket
için filter
alanında kullanıcının tam filtre isteğini içerir.
Tam sayılara dayalı olmayan yönler için facetResults
, istenen her mülk için bir giriş içerir. Her mülk için buckets
adlı bir değer veya aralık listesi sağlanır. En sık görülen değerler önce gösterilir.
Kullanıcı filtrelenecek bir veya daha fazla değer seçtiğinde, seçilen filtrelerle yeni bir sorgu oluşturun ve API'yi tekrar sorgulayın.
Öneri ekleme
Kullanıcının kişisel sorgu geçmişine, kişilerine ve dokümanlarına dayalı olarak sorgularda otomatik tamamlama sağlamak için suggest API'sini kullanın.
Örneğin, aşağıdaki çağrıda jo kısmi ifadesi için öneriler gösterilmektedir.
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
Ardından, elde edilen önerileri uygulamanıza uygun şekilde gösterebilirsiniz.