Query API, arama arayüzü oluşturmak veya arama sonuçlarını bir uygulamaya 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 bir arama arayüzü oluşturmak için birkaç adım gerekir:
- Bir arama uygulamasını yapılandırma
- Uygulama için OAuth kimlik bilgilerini oluşturma
- Dizini sorgulama
- Sorgu sonuçlarını görüntüleme
Sayfalara ayırma, sıralama, filtreleme, özellikler ve otomatik öneri gibi özelliklerle arama arayüzünü daha da geliştirebilirsiniz.
Bir arama uygulamasını yapılandırma
Oluşturduğunuz her arama arayüzüyle ilişkilendirilecek en az bir arama uygulaması oluşturmanız gerekir. Arama uygulamaları, sorgu için kullanılacak veri kaynakları, sıralama düzeni, filtreler ve istenecek özellikler gibi varsayılan parametreleri 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 konusuna bakın.
Uygulama için OAuth kimlik bilgilerini 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 isterken 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
Dizinde arama yapmak için search
yöntemini kullanın.
Her istek iki bilgi içermelidir: öğelerin eşleştirileceği bir metin query
ve kullanılacak arama uygulamasının kimliğini tanımlayan bir searchApplicationId
.
Aşağıdaki snippet'te Titanic filminin 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üle
Arama arayüzlerinin en azından, orijinal öğenin 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 Cloud Search, kullanıcının sorgusu için yetersiz sonuç olduğunda ek sonuçlar döndürür. Yanıttaki queryInterpretation
alanı, ek sonuçların ne zaman döndürüldüğünü belirtir. Yalnızca ek sonuçlar döndürülürse InterpretationType
, REPLACE
olarak ayarlanır. Ek sonuçlarla birlikte orijinal sorgudan 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 metin sağlayabilirsiniz. Örneğin, REPLACE
ile ilgili olarak şu dizeyi görüntüleyebilirsiniz: "Orijinal sorgunuz için yaptığınız arama hiçbir sonuçla eşleşmedi. Benzer sorgular için sonuçlar gösteriliyor."
BLEND
olması durumunda, şu dizeyi görüntüleyebilirsiniz: "Orijinal sorgunuz için yaptığınız arama yeterli sonuçla eşleşmedi. Benzer sorgulara ait sonuçları da
girmek zorunda kalacaksınız."
Kişi 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 belgeler ve adı bir sorguda kullanılan bir kişinin çalışan bilgileri. İkinci sonuç türü, Cloud Search'ün 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 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örmesini sağlar.
Sonuç, structuredResults
alanında mevcuttur.
Bir kişinin yöneticisi veya bağlı çalışanları hakkındaki sorgular için yanıta structuredResults
içinde bir assistCardProtoHolder
ifadesi eklenir. assistCardProtoHolder
, RELATED_PEOPLE_ANSWER_CARD
değerine eşit olan cardType
adlı bir alan içeriyor. assistCardProtoHolder
, gerçek yanıtı içeren relatedPeopleAnswerCard
adlı bir kart içerir.
subject
(sorguya dahil edilen kişi) ve konuyla ilgili kişi kümesi olan relatedPeople
öğesini 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österir:
{
"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 olmak üzere optimizasyonları devre dışı bırakma
Ek sonuçlar gibi optimizasyonlar varsayılan olarak etkindir. Bununla birlikte, tüm optimizasyonları veya hem arama uygulaması hem de sorgu düzeyinde ek sonuçları kapatabilirsiniz:
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ı kapatmak 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 vurgula
Dizine eklenmiş metin veya HTML içeriği barındıran 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 alakasını belirlemelerine yardımcı olur.
Snippet'te sorgu terimleri mevcutsa 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>
etiketiyle sarmalanmış olacak ş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;
}
Örneğin, snippet:
{
"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 öğe hakkında kullanıcılarla alakalı olabilecek ek bilgileri görüntülemek için metadata
alanını kullanın. metadata
alanı, öğenin createTime
ve updateTime
değerlerinin yanı sıra öğeyle ilişkili 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ü etiketi ve bir metalines
grubu içerir. Her meta çizgi, şemada yapılandırıldığı şekliyle bir görüntü etiketleri ve değer çiftleri dizisidir.
Ek sonuçları alma
Ek sonuçlar almak için istekteki start
alanını istediğiniz ofsete ayarlayın. pageSize
alanıyla her sayfanın boyutunu ayarlayabilirsiniz.
Döndürülen öğe sayısını görüntülemek veya döndürülen öğeler arasında sayfa oluşturma denetimlerini 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ıralama ölçütü olarak kullanılacak bir operatör. Birden fazla operatöre sahip mülklerde yalnızca ana eşitlik operatörünü kullanarak sıralama yapabilirsiniz.sortOrder
— sıralanacak yön;ASCENDING
veyaDESCENDING
.
Alaka düzeyi ikincil sıralama anahtarı olarak da 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 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 fazla filtrelemenin 2 temel yolu vardır:
filterOptions[].objectType
özelliği aracılığıyla nesne filtreleri, eşleşen öğeleri özel şemada tanımlandığı gibi 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 ifadelerde birleştirilmesine olanak tanır.
Film şeması örneğinde, geçerli kullanıcıya göre bir yaş kısıtlaması uygulayabilir ve kullanılabilen 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"
}
}
}
]
}
]
}
}
}
]
}
]
}
Özellikleri kullanarak sonuçları hassaslaştırın
Özellikler, arama sonuçlarını hassaslaştırmak için kategorileri temsil eden dizine eklenmiş özelliklerdir. Kullanıcıların sorgularını etkileşimli olarak 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 istenirken Cloud Search, 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. Bu değerleri, sonraki sorgularda sonuçları daraltan filtreler oluşturmak için kullanın.
Özelliklerle ilgili 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 façeta değeri seçer.
- Seçilen değerlere göre sorguyu bir filtreyle tekrarlayın.
Örneğin, film sorgularının yıla ve MPAA derecelendirmesine göre ayrıntılandırmasını sağlamak 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ı
Tam sayı tabanlı alanlarla özellik isteği sonuçlarını da kullanabilirsiniz. Örneğin, "100-200" sayfalı kitaplarla ilgili bir aramanın sonuçlarını hassaslaştırmak için book_pages
adlı bir tam sayı özelliğini Facetable olarak işaretleyebilirsiniz.
Tam sayı özelliği alanı şemanızı ayarlarken isFacetable
öğesini true
olarak ayarlayın ve ilgili paketleme seçeneklerini integerPropertyOptions
öğesine ekleyin.
Bu, her tamsayı-Faktörlü Tablo özelliğinde varsayılan paketleme seçeneklerinin tanımlanmasını sağlar.
Paketleme seçenekleri mantığını tanımlarken aralıkları belirten bir artımlı değerler 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 özellikler 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ı veya sorgu isteğinde özellik seçenekleri tanımlanmadığında şemada tanımlanan paketleme seçeneklerini kullanır. Sorguda tanımlanan özellikler, 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ı bayt cinsinden, bayt cinsinden veya bir dokümanın oluşturulma ya da değiştirilme zamanına göre hassaslaştırmak 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 eklemek için
itemsize
kullanın ve gruplandırma seçeneklerini tanımlayın. - Doküman oluşturma tarihine göre özellik eklemek için
createddatetimestamp
değerini kullanın. - Doküman değiştirilme tarihine göre özellik eklemek için
lastmodified
değerini kullanın.
Façeta gruplarını yorumlama
Arama sorgusu yanıtındaki facetResults
özelliği, her bir bucket
için filter
alanında kullanıcının tam filtre isteğini içerir.
Tamsayılara dayalı olmayan özelliklerde facetResults
, istenen her özellik için bir giriş içerir. Her özellik için buckets
adlı bir değer veya aralık listesi sağlanır. En sık görülen değerler başta gösterilir.
Kullanıcı filtreleme için 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
Sorgular için kullanıcının kişisel sorgu geçmişinin yanı sıra kişiler ve belge kitaplığını temel alan otomatik tamamlama özelliği sunmak için suggest API'yi kullanın.
Örneğin, aşağıdaki çağrıda jo kısmi ifadesi için öneriler sunulmaktadır.
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
Ardından, sunulan önerileri uygulamanız için uygun şekilde görüntüleyebilirsiniz.