Query API ile arama arayüzü oluşturma

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:

  1. Bir arama uygulamasını yapılandırma
  2. Uygulama için OAuth kimlik bilgilerini oluşturma
  3. Dizini sorgulama
  4. 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:

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 veya DESCENDING.

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ı:

  1. Özellikte hangi özelliklerin dahil edileceğini belirten bir ilk sorgu oluşturun sonuç.
  2. Arama ve özellik sonuçlarını oluşturun.
  3. Kullanıcı, sonuçları hassaslaştırmak için bir veya daha fazla façeta değeri seçer.
  4. Seçilen değerlere göre sorguyu bir filtreyle tekrarlayın.
ziyaret edin.

Ö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.