Query API ile arama arayüzü oluşturma

Query API, bir arama arayüzü oluşturmak veya arama sonuçlarını bir uygulamaya yerleştirmek için arama ve önerme 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:

  1. Arama uygulaması yapılandırma
  2. Uygulama için OAuth kimlik bilgileri oluşturma
  3. Dizini sorgulama
  4. Sorgu sonuçlarını görüntüleme

Arama arayüzünü sayfalama, sıralama, filtreleme, yönler ve otomatik önerme gibi özelliklerle daha da geliştirebilirsiniz.

Arama uygulaması 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 bilgilerinin 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. Yetki isteğinde bulunurken kapsamı https://www.googleapis.com/auth/cloud_search.query 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"}.

Dizini sorgulama

Dizinde arama yapmak için search yöntemini kullanın.

Her istekte iki bilgi bulunmalıdır: öğeleri eşleştirmek için kullanılacak bir metin query ve kullanılacak arama uygulamasının kimliğini belirten bir searchApplicationId.

Aşağıdaki snippet'te Titanic filmi için 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 öğeye bir bağlantıyı göstermesi beklenir. Arama sonuçlarında bulunan ek bilgilerden (ör. snippet ve meta veriler) yararlanarak arama sonuçlarının gösterimini daha da iyileştirebilirsiniz.

Ek sonuçları işleme

Cloud Search, kullanıcının sorgusu için yeterli sonuç olmadığında varsayılan olarak 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 birkaç sonuç ek sonuçlarla birlikte 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ğlamayı düşünebilirsiniz. Örneğin, bir REPLACE durumunda "Orijinal sorgunuzla ilgili aramanız herhangi bir sonuçla eşleşmedi. Benzer sorgular için sonuçlar gösteriliyor."

BLEND durumunda, "Orijinal sorgunuzla ilgili aramanız yeterli sayıda sonuçla eşleşmedi. Benzer sorgular için sonuçlar da gösteriliyor."

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 tür sonuç, 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 Kişi Arama özelliğidir. Bu özellik, kullanıcıların kuruluşlarındaki bir kişinin doğrudan raporlarını görmesine olanak tanır. Sonuç, structuredResults alanında gösterilir.

Bir kişinin yöneticisi veya bağlı çalışanları hakkındaki sorgular için yanıtta structuredResults içinde assistCardProtoHolder bulunur. assistCardProtoHolder, cardType adlı bir alana sahiptir ve bu alan RELATED_PEOPLE_ANSWER_CARD değerine eşittir. assistCardProtoHolder, gerçek yanıtı içeren relatedPeopleAnswerCard adlı bir kart içerir. subject (sorguya dahil edilen kişi) ve relatedPeople (konuyla ilgili kişilerin kümesi) öğelerini içerir. relationType alanı, MANAGER veya DIRECT_REPORTS değerini döndürür.

Aşağıdaki kodda, doğrudan raporlarla eşleşen bir sorgu için örnek 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

Varsayılan olarak ek sonuçlar gibi optimizasyonlar etkindir. Ancak hem arama uygulaması hem de sorgu düzeyinde tüm optimizasyonları veya yalnızca ek sonuçları devre dışı bırakabilirsiniz:

Öne çıkan snippet'ler

Dizinlenmiş 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 döndürülen öğenin alaka düzeyini belirlemesine yardımcı olur.

Snippet'te sorgu terimleri varsa terimlerin konumunu belirleyen 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ği, snippet'i HTML biçimlendirmesine dönüştürür. Eşleşen her aralık bir <span> etiketiyle sarmalanı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'i göz önünde bulundurarak:

{
  "snippet": "This is an example snippet...",
  "matchRanges": [
    {
      "start": 11,
      "end": 18
    }
  ]
}

Elde edilen HTML dizesi şöyledir:

This is an <span class="highlight">example</span> snippet...

Yayınlanan içerik meta verisi

Kullanıcılara alakalı olabilecek, döndürülen öğe hakkında ek bilgiler göstermek için metadata alanını kullanın. metadata alanı, öğenin createTime ve updateTime özelliklerinin yanı sıra öğ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 dizi metalines içerir. Her bir meta satır, şemada yapılandırıldığı şekilde görünen etiketler ve değer çiftlerinden oluşan bir dizidir.

Ek sonuçları alma

Ek sonuç almak için isteğin start alanını istediğiniz ofsete ayarlayın. Her sayfanın boyutunu pageSize alanı ile ayarlayabilirsiniz.

İade edilen öğelerin sayısını göstermek veya iade edilen öğeler arasında gezinmek için sayfalama kontrollerini göstermek üzere resultCount alanını kullanın. Sonuç kümesinin boyutuna bağlı olarak gerçek değer veya tahmini 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ğinin sıralanacağı operatör. Birden fazla operatörün bulunduğu mülklerde yalnızca ana eşitlik operatörünü kullanarak sıralama yapabilirsiniz.
  • sortOrder: Sıralama yönü (ASCENDING veya DESCENDING).

Alaka düzeyi, ikincil sıralama anahtarı olarak da kullanılır. Bir sorguda sıralama düzeni belirtilmemişse 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.

İstek veya arama uygulamasına filtre eklemek için filtreyi dataSourceRestrictions.filterOptions[] alanına ekleyin.

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 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 ifadeler halinde 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"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Fasetlerle sonuçları hassaslaştırma

Özellikler, arama sonuçlarını daraltmak için kullanılan kategorileri temsil eden dizine eklenmiş özelliklerdir. Kullanıcıların sorgularını etkileşimli olarak daraltmalarına ve alakalı öğeleri daha hızlı bulmalarına yardımcı olmak için yönleri kullanın.

Fasetler arama uygulamanızda tanımlanabilir ve sorgunuzdaki ayarlar tarafından geçersiz kılınabilir.

Cloud Search, yön isteğinde bulunurken eşleşen öğeler arasında istenen özelliklerin en sık kullanılan değerlerini 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.

Fasetlerle etkileşimde genellikle şu kalıp kullanılır:

  1. Hangi özelliklerin facet sonuçlarına dahil edileceğini belirten bir ilk sorgu gönderin.
  2. Arama ve yön sonuçlarını oluşturun.
  3. Kullanıcı, sonuçları hassaslaştırmak için bir veya daha fazla özellik değeri seçer.
  4. Sorguyu, seçilen değerlere göre bir filtreyle tekrarlayın.

Örneğin, film sorgularının yıla ve MPAA derecelendirmesine göre daraltılması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"
  }
]

Tamsayı tabanlı alanlarla sonuçları daraltma

Ayrıca, tam sayı tabanlı alanlarla istek sonuçlarını da yönlendirebilirsiniz. Örneğin, "100-200" sayfalık kitaplarla ilgili bir aramanın sonuçlarını daraltmak için book_pages adlı bir tam sayı özelliğini filtrelenebilir olarak işaretleyebilirsiniz.

Tam sayı özellik alanı şemanızı oluştururken isFacetable değerini true olarak ayarlayın ve integerPropertyOptions alanına karşılık gelen gruplandırma seçeneklerini ekleyin. Bu, her tam sayı yönlü özelliğin tanımlanmış varsayılan gruplandırma seçeneklerine sahip olmasını sağlar.

Paketleme seçenekleri mantığını tanımlarken aralıkları belirten 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 yönler hesaplanır.

İstekte facetOptions için aynı gruplandırma seçeneklerini tanımlayarak tam sayı tabanlı yönleri geçersiz kılabilirsiniz. Gerekirse Cloud Search, arama uygulamasında veya sorgu isteğinde gruplandırma seçenekleri tanımlanmadığında şemada tanımlanan gruplandırma seçeneklerini kullanır. Sorguda tanımlanan özellikler, arama uygulamasında tanımlanan özelliklere göre önceliklidir. Arama uygulamasında tanımlanan özellikler ise şemada tanımlanan özelliklere göre önceliklidir.

Sonuçları belge boyutuna veya tarihe göre daraltma

Arama sonuçlarını, bayt cinsinden ölçülen dosya boyutuna veya bir belgenin 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 bölümünde operatorName değerini belirtmeniz gerekir.

  • Belge boyutuna göre gruplandırma için itemsize simgesini kullanın ve gruplandırma seçeneklerini tanımlayın.
  • Belge oluşturma tarihine göre gruplandırma için createddatetimestamp kullanın.
  • Belgenin değiştirilme tarihine göre gruplandırma için lastmodified kullanın.

Özellik grubu paketlerini yorumlama

Arama sorgusu yanıtındaki facetResults özelliği, her bucket için filter alanında kullanıcının tam filtre isteğini içerir.

Tamsayılara dayanmayan yönler için facetResults, istenen her özellik için bir giriş içerir. Her özellik için buckets adı verilen bir değer veya aralık listesi sağlanır. En sık görülen değerler önce gösterilir.

Bir kullanıcı, filtrelenecek bir veya daha fazla değer seçtiğinde seçilen filtrelerle yeni bir sorgu oluşturun ve API'ye tekrar sorgu gönderin.

Öneri ekleme

Kullanıcının kişisel sorgu geçmişinin yanı sıra kişileri ve doküman derlemesine dayalı olarak sorgular için otomatik tamamlama sağlamak üzere suggest API'sini kullanın.

Örneğin, aşağıdaki çağrı, jo ifadesinin bir bölümü için önerilerde bulunur.

{
  "query": "jo",
  "requestOptions": {
    "searchApplicationId": "<search_app_id>",
    "peoplePhotoOptions": {
      "peoplePhotoUrlSizeInPx": 32
    },
    "timeZone": "America/Denver"
  }
}

Ardından, sonuç olarak elde edilen önerileri uygulamanıza uygun şekilde gösterebilirsiniz.