Bu sayfa, Cloud Translation API ile çevrilmiştir.

Query API ile arama arayüzü oluşturma

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ğerini true 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ğerini true olarak ayarlayın.
Arama uygulaması düzeyinde ek sonuçları kapatmak için arama sorgusunda QueryInterpretationOptions.forceDisableSupplementalResults değerini true olarak ayarlayın.
Arama sorgusu düzeyinde ek sonuçları devre dışı bırakmak için arama sorgusunda QueryInterpretationOptions.disableSupplementalResults değerini true 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 veya DESCENDING.

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

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.