Query API ile arama arayüzü oluşturma

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:

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

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

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:

  1. Kelime öbeği sonuçlarına hangi özelliklerin dahil edileceğini belirten ilk bir sorgu oluşturun.
  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 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.