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

Arama uygulamasını yapılandırma
Uygulama için OAuth kimlik bilgileri oluşturma
Dizini sorgulama
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 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

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ü belirtir. 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 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 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 Raporlama Eşleştirme, Cloud Search'ın kullanıcıların kuruluşlarındaki bir kişinin doğrudan raporlarını görmesine olanak tanıyan Kişi Arama özelliğidir. Sonuç, structuredResults alanında kullanılabilir.

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 olacak cardType adlı bir alana sahiptir. 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 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:

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.
Ek sonuçları arama uygulaması düzeyinde 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.

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 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;
}

Snippet şöyleyse:

{
  "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ü için görüntü etiketi ve bir metalines grubu 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 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ü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 fazla 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, 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"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

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:

Kelime öbeği sonuçlarına hangi özelliklerin dahil edileceğini belirten ilk bir sorgu oluşturun.
Arama ve yön sonuçlarını oluşturun.
Kullanıcı, sonuçları hassaslaştırmak için bir veya daha fazla özellik değeri seçer.
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"
  }
]

Tam sayı tabanlı alanlarla özellik isteği sonuçlarını da kullanabilirsiniz. Ö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 tablolanabilir olarak işaretleyebilirsiniz.

Tam sayı mülk 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 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 özellikleri ise şemada tanımlanan özellikler geçersiz kılar.

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

Façeta gruplarını 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.

Tamsayılara dayalı olmayan özelliklerde facetResults, istenen her özellik 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ı 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

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, sunulan önerileri uygulamanız için uygun şekilde görüntüleyebilirsiniz.