Query API, arama oluşturmak için arama ve öneri yöntemleri sunar veya bir uygulamaya yerleştirilmiş arama sonuçları.
Minimum gereksinimleri olan web uygulamaları için arama widget'ını kullanabilirsiniz. Daha fazla bilgi için bkz. Arama widget'ıyla bir arama arayüzü oluşturma
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
Arama arayüzünü aşağıdaki gibi özelliklerle daha da geliştirebilirsiniz: sayfalama, sıralama, filtreleme, özellikler ve otomatik öneri.
Bir arama uygulamasını yapılandırma
Her biriyle ilişkilendirmek için en az bir arama uygulaması oluşturmanız gerekir bir şablondur. Bir arama uygulaması, varsayılan sorgu için kullanılacak veri kaynakları, sıralama düzeni ve filtreleri ve özellikleri belirlemenize yardımcı olur. Gerekirse bu parametreleri geçersiz kılabilirsiniz. kullanabilirsiniz.
Arama uygulamaları hakkında daha fazla bilgi için Cloud Search'te arama deneyimini özelleştirin.
Uygulama için OAuth kimlik bilgilerini oluşturma
Bu adımların yanı sıra Google Cloud Search API'ye erişimi yapılandırın, web uygulaması için OAuth kimlik bilgileri de oluşturmanız gerekir. Tür veya kimlik bilgilerinin türü, API'nin kullanıldığı bağlama göre değişir.
Kullanıcı adına yetkilendirme istemek için kimlik bilgilerini kullanın. Şunu kullanın:
kapsam https://www.googleapis.com/auth/cloud_search.query
yetkilendirme.
OAuth seçenekleri ve istemci kitaplıkları hakkında daha fazla bilgi edinmek için bkz. [Google Kimlik Platformu](https://developers.google.com/identity/choose-auth{: .external target="_blank"}.
Dizini sorgulama
search
'ı kullanma
yöntemini kullanarak dizinde arama yapmasını sağlar.
Her talepte iki bilgi parçası bulunmalıdır: metin query
ve öğelerin kimliğini tanımlayan bir searchApplicationId
kullanılacak arama uygulaması.
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, title
öğesini
ve orijinal öğenin bağlantısı yer alır. Ayrıca, reklamlarınızın görüntülenmesini daha da
arama sonuçlarında bulunan ek bilgilerden yararlanarak arama sonuçları
farklı olabilir.
Ek sonuçları işleme
Varsayılan olarak, Cloud Search aşağıdaki durumlarda ek sonuçlar döndürür
Kullanıcı sorgusu için yetersiz sonuç. İlgili içeriği oluşturmak için kullanılan
queryInterpretation
alanı, ek sonuçların ne zaman döndürüldüğünü belirtir. Yalnızca
ek sonuç döndürülürse InterpretationType
, REPLACE
olarak ayarlandı. Eğer
orijinal sorgu için birkaç sonuç döndürülür ve
sonuç için InterpretationType
, BLEND
olarak ayarlandı. Her iki durumda da
QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY
Bazı ek sonuçlar döndürüldüğünde metin eklemeyi düşünün
ifadesini kullanın. Örneğin,
REPLACE
sorgusunda, "orijinal sorgunuz için yaptığınız arama
hiçbir sonuçla eşleşmiyor. Benzer sorgular için sonuçlar gösteriliyor."
BLEND
olması halinde, "
orijinal sorgu yeterli sonuçla eşleşmedi. Benzer terimler için sonuçlarla birlikte
girin."
Kişi sonuçlarını işleme
Cloud Search iki tür "kişi sonucu" döndürür: bir sorguyla ilişkili
sorguda ve kişinin çalışan bilgilerinde adı kullanılan kişi
kullanıcı adı bir sorguda kullanılan kullanıcı adıdır. İkinci sonuç türü ise Cloud
Arama'nın Kişi Arama özelliğine ve bu tür bir sorgunun sonuçları şurada bulunabilir:
"the"
structuredResults
alanı olacaktır:
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
Doğrudan Rapor Eşleştirme
Doğrudan Rapor Eşleştirme, Cloud Search'ün Kişi Arama özelliğidir.
Kullanıcılar, kuruluşlarındaki bir kişinin doğrudan raporlarını görür.
Sonuç, structuredResults
alanında mevcuttur.
Bir kişinin yöneticisi veya bağlı çalışanları ile ilgili sorgular için, yanıtta
structuredResults
içinde assistCardProtoHolder
. İlgili içeriği oluşturmak için kullanılan
assistCardProtoHolder
, cardType
adlı bir alana sahip. Bu alan şuna eşit:
RELATED_PEOPLE_ANSWER_CARD
. assistCardProtoHolder
bir kart içeriyor
relatedPeopleAnswerCard
adlı bir öğe ekleyin.
subject
(sorguya dahil edilen kişi) ve
relatedPeople
, konuyla ilgili kullanıcı kümesidir. İlgili içeriği oluşturmak için kullanılan
relationType
alanı, MANAGER
veya DIRECT_REPORTS
değerini döndürür.
Aşağıdaki kod, şununla eşleşen doğrudan raporlar için örnek bir yanıt gösterir: sorgu:
{
"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. Bu sayede, Ancak hem tüm optimizasyonları devre dışı bırakabilir hem de arama uygulaması ve sorgu düzeyi:
Aşağıdakiler dahil olmak üzere arama uygulaması düzeyindeki tüm optimizasyonları devre dışı bırakmak için: ek sonuçlar, eş anlamlılar ve yazım düzeltmeleri için
QueryInterpretationConfig.force_verbatim_mode
arama uygulamalarındatrue
adresine.Aşağıdakiler dahil olmak üzere arama sorgusu düzeyindeki tüm optimizasyonları devre dışı bırakmak için: eş anlamlılar ve yazım düzeltmeleri gibi
QueryInterpretationOptions.enableVerbatimMode
true
olarak ayarlamak için kullanılır.Arama uygulaması düzeyinde ek sonuçları kapatmak için
QueryInterpretationOptions.forceDisableSupplementalResults
true
olarak ayarlamak için kullanılır.Arama sorgusu düzeyinde ek sonuçları kapatmak için
QueryInterpretationOptions.disableSupplementalResults
true
olarak ayarlamak için kullanılır.
Snippet'leri vurgula
Dizine eklenmiş metin veya HTML içeriği barındıran döndürülen öğeler için geri döndüğünden emin olun. Bu içerik, kullanıcıların iade edilen öğenin alaka düzeyi
Snippet'te sorgu terimleri bulunuyorsa kullanıcıyı tanımlayan bir veya daha fazla terimlerin konumu da döndürülür.
Oluşturma sırasında eşleşen metni vurgulamak için matchRanges
özelliğini kullanın
daha iyi olur. Aşağıdaki JavaScript örneği, snippet'i
Eşleşen her aralığın bir <span>
etiketi içinde sarmalanmış olduğu HTML işaretlemesi.
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
metadata
'ı kullanma
Bu alana, iade edilen ürünle ilgili alakalı olabilecek ek bilgiler de gösterilir
değer teslim eder. metadata
alanı, createTime
ve
Öğenin updateTime
'ı ve ilişkili tüm döndürülebilir yapılandırılmış veriler
ayarlayacağım.
Yapılandırılmış verileri görüntülemek için displayOptions
özelliğini kullanın
girin. displayOptions
alanı, nesne türünün görüntü etiketini içerir
ve metalines
'lık bir set. Her meta çizgi, bir görüntülü reklam etiketleri dizisidir ve
değer çiftlerini şemada yapılandırıldıklarından oluşur.
Ek sonuçları alma
Ek sonuçlar almak için start
ayarını yapın.
alanının istenen ofsete ayarlayın. Boyutu ayarlayabilirsiniz
pageSize
içeren her sayfanın
girin.
Döndürülen öğe sayısını veya sayfalama denetimlerini
sayfasını gözden geçirmek için
resultCount
girin. Sonuç kümesinin boyutuna bağlı olarak, gerçek değer veya
tahmini bir değer girilir.
Sıralama sonuçları
sortOptions
'ı kullanma
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şitliği kullanarak sıralama yapabilirsiniz. operatörümüzü kullanabilirsiniz.sortOrder
— sıralanacak yön;ASCENDING
veyaDESCENDING
.
Alaka düzeyi ikincil sıralama anahtarı olarak da kullanılır. 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, filtrelerini inceleyin. Filtreleri her ikisinde de belirtebilirsiniz: arama uygulaması hem de arama isteğinde yer alır.
Bir istek veya arama uygulamasına filtre eklemek için filtreyi
dataSourceRestrictions.filterOptions[]
alanına giriş yapın.
Bir veri kaynağını daha fazla filtrelemenin 2 temel yolu vardır:
filterOptions[].objectType
özelliği aracılığıyla nesne filtreleri (kısıtlar) eşleşen öğeleri, özel şemada tanımlandığı gibi belirtilen türle eşleştirir.- Değer filtreleri — eşleşen öğeleri sorgu operatörü ve sağlanan değer.
Bileşik filtreler daha fazla değer elde etmek için birden fazla değer filtresini mantıksal ifadelerde birleştirmeyi karmaşık sorgular.
Film şeması örneğinde, mevcut müşteri sayısına göre geçerli filmi oynatır ve izleyebileceğiniz filmleri MPAA derecelendirmesine göre kısıtlar.
{
"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, aramayı hassaslaştırmaya yönelik kategorileri temsil eden dizine eklenmiş özelliklerdir sonuç. Kullanıcıların sorgularını etkileşimli bir şekilde hassaslaştırmasına ve daha hızlı yürütülmesini sağlamaktır.
Özellikler, arama uygulaması. ve sorgunuzdaki ayarlar tarafından geçersiz kılınır.
Özellikler istenirken Cloud Search, Search Ads 360'ta bulunan istenen özellikleri görebilirsiniz. Bu değerleri döndürülür. Filtreler oluşturmak için bu değerleri kullanın sonuçlar daraltılır.
Özelliklerle ilgili tipik etkileşim kalıbı:
- Özellikte hangi özelliklerin dahil edileceğini belirten bir ilk sorgu oluşturun sonuç.
- 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
facetOptions
özelliğini sorguya dahil et.
"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,
hassaslaştırmak için book_pages
adlı tam sayı özelliğini Facetable olarak işaretleyebilir
"100-200" içeren kitaplar hakkında bir arama için sonuçlar sayfalar.
Tam sayı özellik alanı şemanızı ayarlarken
isFacetable
true
öğesine tıklayın ve ilgili paketleme seçeneklerini
integerPropertyOptions
.
Bu, her tamsayılı yüz tablo özelliğinin varsayılan paketlemeye sahip olmasını sağlar.
tanımlanmış seçenekleri vardır.
Paketleme seçenekleri mantığını tanımlarken bir artımlı değerler dizisi sağlayın
anlamına gelir. Örneğin, son kullanıcı, aralıkları
2, 5, 10, 100
, ardından <2
, [2-5)
, [5-10)
, [10-100)
, >=100
için özellikler
hesaplanır.
Aynı gruplandırma seçeneklerini tanımlayarak tamsayı tabanlı özellikleri geçersiz kılabilir,
facetOptions
belirtin. Gerekirse Cloud Search,
arama uygulaması veya sorgu isteğinde özellik yoksa şema
tanımlanmış seçenekleri vardır. Sorguda tanımlanan özellikler, 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ı
Tekliflerinizi otomatikleştirmek ve optimize etmek için
ayrılmış operatörler
dosya boyutuna göre (bayt cinsinden ölçülen veya dosya boyutu) arama sonuçlarını
dokümanın oluşturulduğu veya değiştirildiği anlamına gelir. Özel bir şema tanımlamanız gerekmez.
ancak arama uygulamanızınoperatorName
FacetOptions
- 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
facetResults
özelliği, kullanıcının tam filtre isteğini içeriyorsa
her birinin filter
alanındaki
bucket
.
Tamsayılara dayalı olmayan özellikler için facetResults
,
ekleyebilirsiniz. Her özellik için değerlerden veya aralıklardan oluşan bir liste
buckets
değeri sağlandı. En sık görülen değerler başta gösterilir.
Bir kullanıcı filtre uygulamak için bir veya daha fazla değer seçtiğinde yeni bir sorgu oluşturun. Seçilen filtreleri seçip API'yi yeniden sorgulayın.
Öneri ekle
suggest API'yi kullanın kullanıcının kişisel özelliklerine dayalı sorgular için otomatik tamamlama olanağı sağlamak üzere sorgu geçmişinin yanı sıra kişiler ve onların doküman kitaplığı da gösterilir.
Örneğin, aşağıdaki çağrıda gösterilen kısmi jo ifadesi.
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
Ardından, önerilen sonuçları kendi amaçlarınıza uygun şekilde bir uygulamadır.