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

Query API ile arama arayüzü oluşturma

Query API, arama arayüzü oluşturmak veya bir uygulamaya arama sonuçları 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 arama arayüzü oluşturmak için birkaç adım gerekir:

Bir arama uygulamasını yapılandırın
Uygulama için OAuth kimlik bilgileri oluşturma
Dizini sorgulama
Sorgu sonuçlarını görüntüleme

Sayfalama, sıralama, filtreleme, özellikler ve otomatik öneri gibi özelliklerle arama arayüzünü daha da geliştirebilirsiniz.

Bir arama uygulamasını yapılandırın

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 kullanılacak veri kaynakları, sıralama düzeni, filtreler ve istenecek özellikler gibi varsayılan parametreleri sağlar. Gerekirse query API'yi kullanarak bu parametreleri geçersiz kılabilirsiniz.

Arama uygulamaları hakkında daha fazla bilgi için Cloud Search'te arama deneyimini özelleştirme bölümüne bakın.

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 istemek için kimlik bilgilerini kullanın. Yetkilendirme talep ederken 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

Dizine göre arama yapmak için search yöntemini kullanın.

Her istek iki bilgi içermelidir: öğelerin eşleştirileceği bir query metni ve kullanılacak arama uygulamasının kimliğini tanımlayan bir searchApplicationId.

Aşağıdaki snippet'te Titanic filminin film veri kaynağına gönderilen bir sorgu gösterilmektedir:

{
  "query": "titanic",
  "requestOptions": {
    "searchApplicationId": "searchapplications/<search_app_id>"
  },
}

Sorgu sonuçlarını görüntüle

En azından, arama arayüzlerinin orijinal öğenin bir 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, kullanıcının sorgusu için yeterli sonuç olmadığında Cloud Search ek sonuçlar döndürür. Yanıttaki queryInterpretation alanı, ek sonuçların ne zaman döndürüleceğini belirtir. Yalnızca ek sonuçlar döndürülürse InterpretationType değeri 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 ekleyebilirsiniz. Örneğin, REPLACE olması durumunda "Orijinal sorgunuzla ilgili aramanız hiçbir sonuçla eşleşmedi. Benzer sorgular için sonuçlar gösteriliyor."

BLEND olması durumunda, "Orijinal sorgunuzla yaptığınız arama yeterli sonuçla eşleşmedi. Benzer sorgulara ilişkin sonuçlar dahil."

Kullanıcı sonuçlarını işleme

Cloud Search iki tür "kişi sonucu" döndürür: sorguda adı kullanılan kişiyle ilgili belgeler ve sorguda adı kullanılan kişinin çalışan bilgileri. İkinci sonuç türü, Cloud Search'ün Kişi Arama özelliğinin bir işlevidir. Bu tür bir sorguyla ilgili 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örmesine olanak tanır. Sonuç, structuredResults alanında mevcuttur.

Bir kişinin yöneticisi veya bağlı çalışanlarıyla ilgili sorgular için yanıtta structuredResults içinde bir assistCardProtoHolder bulunur. assistCardProtoHolder sütununda RELATED_PEOPLE_ANSWER_CARD değerine eşit olan cardType adlı bir alan vardır. assistCardProtoHolder, gerçek yanıtı içeren relatedPeopleAnswerCard adlı bir kart içerir. subject (sorguya dahil edilen kullanıcı) ve konuyla ilgili kişi kümesi olan relatedPeople öğelerini 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ö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ı kapatın

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

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ı devre dışı bırakmak 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.

Öne çıkan snippet'ler

Dizine eklenmiş metin veya HTML içeriği barındıran öğ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 belirlemelerine 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 özelliğini kullanın. Aşağıdaki JavaScript örneği, snippet'i her eşleşen aralık bir <span> etiketine sarmalanmış ş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;
}

Snippet'e göre:

{
  "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...

Meta verileri görüntüleme

Döndürülen öğe hakkında kullanıcılar için alakalı olabilecek ek bilgileri görüntülemek için metadata alanını kullanın. metadata alanı, öğenin createTime ve updateTime özelliklerinin yanı sıra öğeyle ilişkili tüm 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ü etiketini ve bir metalines grubunu içerir. Her meta satır, şemada yapılandırıldığı şekliyle bir görüntü etiketleri ve değer çiftleri dizisidir.

Ek sonuçları al

Ek sonuçları almak için istekteki start alanını istenen ofsete ayarlayın. pageSize alanı ile her sayfanın boyutunu ayarlayabilirsiniz.

İade edilen öğe sayısını veya iade edilen öğelerle ilgili sayfa kontrollerini 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ıralamada kullanılacak bir operatör. Birden fazla operatöre sahip mülkler için yalnızca ana eşitlik operatörü kullanarak sıralama yapabilirsiniz.
sortOrder — sıralama yönü (ASCENDING veya DESCENDING).

Alaka düzeyi ayrıca ikincil sıralama anahtarı olarak 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 ekleyin

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ı 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 sorgu operatörüne ve sağlanan değere göre kısıtlar.

Bileşik filtreler, daha karmaşık sorgular için birden çok değer filtresini mantıksal ifadelerle birleştirmeyi sağlar.

Film şeması örneğinde, mevcut kullanıcıya göre bir yaş kısıtlaması uygulayabilir ve kullanılabilir 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"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Özelliklerle sonuçları hassaslaştırma

Özellikler, arama sonuçlarını hassaslaştırmak için kategorileri temsil eden dizine eklenmiş özelliklerdir. Kullanıcıların sorgularını etkileşimli bir şekilde 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 istendiğinde, Cloud Search eşleşen öğeler arasından istenen özellikler için en sık geçen 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.

Özelliklerle 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 özellik değeri seçer.
Seçili değerleri temel alan bir filtreyle sorguyu tekrarlayın.

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

Ayrıca, tam sayı tabanlı alanlarla istek sonuçlarını da değerlendirebilirsiniz. Örneğin, "100-200" sayfası olan kitaplar hakkındaki arama sonuçlarını hassaslaştırmak için book_pages adlı bir tam sayı özelliğini özellikli bir tam sayı olarak işaretleyebilirsiniz.

Tam sayı özellik alanı şemanızı ayarlarken isFacetable değerini true olarak ayarlayın ve ilgili paketleme seçeneklerini integerPropertyOptions öğesine ekleyin. Bu, her bir tamsayı özellikli özellikte varsayılan paketleme seçeneklerinin tanımlanmasını sağlar.

Paketleme seçenekleri mantığını tanımlarken, aralıkları belirten bir dizi artımlı değer sağlayın. Örneğin, son kullanıcı aralıkları 2, 5, 10, 100 olarak belirtirse <2, [2-5), [5-10), [10-100), >=100 özellikleri 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ında veya sorgu isteğinde özellik seçenekleri tanımlanmamışsa şemada tanımlanan paketleme seçeneklerini kullanır. Sorguda tanımlanan façetalar, 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ı dokümanın dosya boyutuna, bayt cinsinden ölçülenne veya bir dokümanın 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 öğesinde operatorName değerini belirtmeniz gerekir.

Doküman boyutuna göre özellik belirleme için itemsize öğesini kullanın ve paketleme seçeneklerini tanımlayın.
Doküman oluşturma tarihine göre özellik belirleme için createddatetimestamp öğesini kullanın.
Dokümanın değiştirilme tarihine göre özellik belirleme için lastmodified işlevini kullanın.

Özellik paketlerini yorumlama

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

Tam sayılara dayalı olmayan özellikler için facetResults, istenen her özellik için bir giriş içerir. Her özellik için buckets adlı bir değerler veya aralık listesi sağlanır. En sık geçen değerler önce gösterilir.

Kullanıcı filtre uygulamak üzere 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

Kullanıcının kişisel sorgu geçmişinin yanı sıra kişilerin ve kullanıcının belge topluluğuna göre sorguların otomatik olarak tamamlanmasını sağlamak için suggest API'yi kullanın.

Örneğin, aşağıdaki çağrıda jo kısmi kelime öbeği için öneriler sunulmaktadır.

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

Ardından, elde edilen önerileri uygulamanıza uygun şekilde görüntüleyebilirsiniz.