Arama (önizleme) için bot Bağlan

Bu makalede, özel bir federasyon arama sağlayıcısı oluşturma (botunuzun gücü) ve bunu Arama kanalına bağlama açıklanmaktadır. Kiracı yöneticisi sağlayıcınızı kiracısında etkinleştirdikten sonra, Office.com, SharePoint.com ve Bing.com kuruluş kullanıcı aramaları, özel arama sağlayıcınızın sonuçlarını içerebilir.

Microsoft Federasyon Arama Platformu, bilgilerinizin Microsoft 365 dizininizle birleştirmeye gerek kalmadan Microsoft Arama Yanıtları ve Dikey deneyimlerine katılmasına izin vermek için özel federasyon arama sağlayıcıları oluşturmanıza olanak tanır. Daha fazla bilgi için bkz . Microsoft Federasyon Arama Platformu ve Dynamics 365 federasyon araması (önizleme) için geliştirici önizlemesi duyuruları.

Dekont

Arama kanalı özel önizleme aşamasındadır. Erişim istemek için Microsoft Arama Geliştirici Özel Önizleme formunu kullanın. 7. soruda Federasyon Arama'yı seçin.

Botunuzu Arama kanalına bağlamak için aşağıdaki adımlar gereklidir. Bu adımlar, bu makalenin devamında daha ayrıntılı olarak açıklanmıştır.

1. Arama sağlayıcısı olarak çalışmak için botunuzu uygulayın.
2. Botunuz kullanıcıların oturum açmasını gerektiriyorsa:
   1. Azure portalında bot API'sini arama platformunda kullanıma sunun.
   2. Bot kodunuzda, kullanıcı belirteci oluşturmak için oluşturulan kapsam URI'sini kullanın.
3. Botunuzu Azure'a dağıtın.
4. Arama kanalını botunuza ekleyin.
5. BT yöneticinizden bot kaydınızı gözden geçirmesini ve botunuzu kiracıda yayımlamasını isteyin.

Bahşiş

Üretimde etkinleştirmeden önce test kiracısında arama sağlayıcısını etkinleştirmenizi öneririz.

Önkoşullar

• Bot Framework Hizmeti hakkında temel bilgiler ve Bot Framework SDK'sı ile bot oluşturma.
• Kanala bağlanmak için bot.
• Azure hesabınız yoksa, başlamadan önce ücretsiz hesap oluşturun.

Botunuzu Bot Framework SDK'sı tarafından desteklenen dillerden herhangi birinde uygulayabilirsiniz. Bu makalede örnek olarak C# federasyon arama botu kullanılır.

Bot API'sini Arama için kullanıma sunma

Bahşiş

Bu adım yalnızca botunuzun korumalı kullanıcı kaynaklarına erişmesi gerekiyorsa gereklidir.

Bazı iş iş akışlarında bot, kullanıcı adına eylem gerçekleştirmek için kullanıcı kimlik bilgilerini gerektirebilir. Arama kanalında botunuz için çoklu oturum açma (SSO) deneyimi oluşturmak için, arama platformunun kullanıcı adına Microsoft Entra Id'den erişim belirtecinin güvenliğini sağlamasına izin vermelisiniz.

Botunuz için kapsam URI'si ve uygulama kimliği oluşturmak için:

1. Azure portalına gidin.
2. Henüz bir bot kaynağınız yoksa bir Azure Bot kaynağı oluşturun.
3. Microsoft Entra ID hizmetine gidin.
4. Uygulama kayıtları bölmesine gidin.
5. Botunuzla ilişkili uygulamayı seçin.
6. API'yi kullanıma sunma bölmesine gidin.
7. Yeni bir kapsam ekle'yi seçin.
   1. Kapsam ekle bölmesinde, otomatik oluşturulan Uygulama Kimliği URI'sini tutmanızı öneririz. Kaydet ve devam et’i seçin.
   2. Bir Kapsam adı girin.
   3. Kim onay verebilir? için Yönetici ve kullanıcılar tercih edilir, ancak her iki seçenek de çalışır.
   4. bir Yönetici onay görünen adı ve Yönetici onay açıklaması girin.
   5. İsteğe bağlı olarak, bir Kullanıcı onayı görünen adı ve kullanıcı onayı açıklaması girin.
   6. Durum'un Etkin olarak ayarlandığını doğrulayın.
   7. Kapsam ekle'yi seçin.
8. İstemci uygulaması ekle'yi seçin.
   1. İstemci uygulaması ekle bölmesinde, İstemci Kimliği'ni Arama platformunun istemci kimliği olarak 81473081-50b9-469a-b9d8-303109583ecbayarlayın.
   2. Yetkili kapsamlar'ın altında, önceki adımda oluşturduğunuz kapsam URI'sini seçin.
   3. Uygulama ekle'yi seçin.
9. Genel Bakış bölmesine gidin. Uygulama Kimliği URI'sini kopyalayın. Botunuzu Arama kanalına kaydederken buna ihtiyacınız olacaktır.

Botunuzu uygulama

Arama kanalı, her kullanıcı sorgusunu "uygulama/arama" adlı bir çağırma etkinliği olarak botunuza gönderir. Botunuz çağırma yanıtında sorgu sonuçlarını döndürür. Arama kanalına geri gönderilen sorgu sonuçları için Uyarlamalı Kart biçimini kullanın.

1. Projenizdeki tüm Bot Framework ve Uyarlamalı Kartlar paketlerini en son sürüme güncelleştirin.
2. İsteğe bağlı olarak, kullanıcı belirteci oluşturmak için kimlik doğrulama kodu ekleyin.
3. Eklenecek her veri kaynağı için bir veri arama yöntemi uygulayın.
4. Sonuçları görüntülemek için Uyarlamalı Kart oluşturun.

Arama platformu izleme kimliğini alma

Arama platformu botunuza gönderdiği her sorguya benzersiz bir izleme kimliği atar. Platform bunu çağırma etkinliğinin kanal verilerine ekler. İsteğin izleme kimliğini günlüğe kaydetmeye karar vekleyebilirsiniz. İzleme kimliğini almak için kanal verilerinin traceId özelliğini kullanın.

Federasyon arama örneğinde yöntemi, SearchHelper.GetSearchTraceId çağırma etkinliğinden izleme kimliğinin nasıl alınduğunu gösterir.

Kimlik doğrulaması ekleme

Bot API'nizi Arama'ya kullanıma kullandıysanız ve botunuzu Arama'ya bağladığınızda kimlik doğrulaması istediyseniz, etkinliğin kanal verilerinden kullanıcı kimlik doğrulama belirtecini alabilirsiniz.

Kanal verilerinin authorizations özelliği kimlik doğrulama belirteçlerinin listesini içerebilir. Bot API'nizi Arama için kullanıma sunarsanız, listede adına ait belirteç bulunur. Listedeki belirteç aşağıdaki yapıya sahip olacaktır:

Özellik Adı	Türü	Açıklama
Authtype	integer	Kimlik doğrulama belirteci türü: 0 bilinmeyen veya varsayılan veya 2 adına belirteç için.
token	Dize	Kimlik doğrulama belirtecinin kendisi.

Federasyon arama örneğinde:

• sınıfı SearchBotAuthenticationToken ve numaralandırması AuthenticationTypes bu bilgileri temsil etti.
• yöntemi, SearchHelper.GetSearchOboToken çağırma etkinliğinden belirtecin nasıl alınduğunu gösterir.

Belirteci aldıktan sonra, kullanıcı için herhangi bir korumalı kaynak istediğinizde bunu kullanabilirsiniz. Adına belirteçleri kullanma hakkında bilgi için bkz. Microsoft kimlik platformu ve OAuth 2.0 On-Behalf-Of akışı.

Her veri deposunu sorgulama

Search kanalı bota etkinlik olarak invoke bir sorgu gönderir ve sorgu ayrıntıları etkinliğin value özelliğinde bulunur ve bu da aşağıdaki yapıya sahip bir JSON nesnesini temsil eder:

Özellik Adı	Türü	Açıklama
queryText	Dize	Sorgu metni.
tür	Dize	Sorgu türü: Sonuçlar özel bir dikey sekmede görüntülendiğinde "ara" veya Tümü sekmesinde yanıt olarak bir sonuç görüntülendiğinde "searchAnswer".
Queryoptions	nesne	Sayfalandırma için kullanılan ek sorgu seçenekleri.
queryOptions.skip	integer	Gönderilecek ilk sonucun dizini.
queryOptions.top	integer	Gönderilecek en fazla sonuç sayısı.

Arama sonuçlarını çağırma yanıtında döndürürsiniz:

• Her zaman invoke yanıt nesnesinin Status özelliğini olarak 200ayarlayın. Bu, ağ bağlantısının iyi olduğunu gösterir. Nesnenin Body özelliği ayrı bir durum koduna sahiptir.

• Body özelliği aşağıdaki yapıya sahip bir JSON nesnesini temsil eder:

  Özellik Adı	Türü	Açıklama
  statusCode	integer	Botunun sorguyu başarıyla çalıştırıp çalıştıramadığını belirtmek için kullanılan http durum kodu.
  type	Dize	Değer alanının biçimini tanımlayan çağırma yanıtının türü. Arama sonuçları için "application/vnd.microsoft.search.searchResponse" veya hata iletisi için "application/vnd.microsoft.error" kullanın.
  değer	nesne	değerine karşılık gelen bir değer type.

  Hata iletileri için value nesnesi şunları içerir:

  Özellik Adı	Türü	Açıklama
  kod	Dize	Bot tarafından tanımlanan veya null belirtilmemiş bir hata kodu.
  ileti	Dize	Bir hata iletisi veya null belirtilmemişse.

  Arama sonuçları için value nesnesi şunları içerir:

  Özellik Adı	Türü	Açıklama
  Sonuçlar	arama sonucu nesneleri dizisi	Sonuçlar veya null yoksa.
  displayLayouts	görüntü düzeni nesneleri dizisi	Görüntü düzenleri veya null yoksa.
  totalResultCount	integer	Sayfalandırma destekleniyorsa kullanılabilir toplam sonuç; aksi takdirde , null.
  moreResultsAvailable	Boolean	Daha fazla sonuç olup olmadığını gösterir.

  Arama sonucu nesneleri:

  Özellik Adı	Türü	Açıklama
  değer	Dize	Bu arama sonucu için benzersiz bir tanımlayıcı veya değer.
  layoutId	Dize	Bu sonuç için kullanılacak görüntü düzeninin kimliği.
  data.searchResultText	Dize	Bu sonucun metni.

  Görüntü düzeni nesneleri:

  Özellik Adı	Türü	Açıklama
  layoutId	Dize	Düzen kimliği.
  layoutBody	Dize	Uyarlamalı Kartlar JSON nesnesi olarak düzen gövdesi.

Federasyon arama örneğinde yöntemi, SearchHelper.RunFederatedSearch çağırma etkinliğinden sorgu bilgilerinin nasıl alınıp çağrı yanıtının nasıl biçimlendirılacağını gösterir.

Arama sonuçlarını görüntüleme

Kullanıcıların SharePoint, Office ve Bing'de arama yaparken gördükleri arama sonuçlarını özelleştirmek için dikey arama ve sonuç türleri oluşturabilirsiniz. Dikeyler, kullanıcıların görme iznine sahip oldukları bilgileri bulmalarını kolaylaştırır. Daha fazla bilgi için Desteklenen Uyarlamalı Kart öğeleri bölümüne bakın.

Botunuz yanıtı olmayan bir sorgu alırsa, yanıtı boş bir yanıt içermelidir.

Botunuzu Azure'a kaydetme

Botunuzu Arama kanalına bağlamak için Azure'da sağlanan bir bot kaynağınız olmalıdır. Daha fazla bilgi için bkz. Azure'a bot kaydetme veya botunuzu Azure'dadağıtma.

Botunuzu Arama'ya Bağlan

Aşağıdaki yönergeler bir botu Arama'ya nasıl bağlayabileceğinizi gösterir.

Bahşiş

Üretimde etkinleştirmeden önce test kiracısında arama sağlayıcısını etkinleştirmenizi öneririz.

1. Azure portalına gidin.

2. Bot kaynağınızı açın.

3. Kanallar (Önizleme) bölmesini açın.

4. Ara'yı seçin.

5. Arama Ayarlar sekmesinde botunuzun bilgilerini girin.

   

   1. Arama Sağlayıcısı Meta Verileri'nin altında, arama kullanıcı arabiriminde görüntülenecek adı girin.

   2. Tetikleyici tümcecikleri'nin altında, botunuzun yanıtlayabileceğiniz sorguları temsil eden tümcecikleri tanımlayın.

      Dekont

      İlk sürümler için yalnızca İngilizce (en-US) kullanılabilir.

      • İfadeleri içeren bir .csv dosyayı karşıya yükleyin. Dosya, üst bilgi içermeyen tek bir veri sütunu içermelidir.
      • Dil tercih listesinden tetikleyici tümceciklerinin yazıldığı dili seçin.

   3. Kimlik Doğrulaması'nın altında, arama sağlayıcınız için kullanıcı kimlik doğrulaması gerekip gerekmediğini belirtin.

      • Kimlik doğrulaması gerekiyorsa kimlik doğrulama URL'sini girin. Botunuz için API'yi kullanıma açtığınızda kopyaladığınız Uygulama Kimliği URI'sini kullanın.

   4. İleri'yi seçin.

6. Dikeyler sekmesinde, arama sağlayıcınızın sonuçlarının arama sonuçları sayfasında kendi özel dikey öğesinde gösterilmesini istiyorsanız, alana dikey adı girin; aksi takdirde, bu alanı boş bırakın. Ardından İleri'yi seçin.
   Arama sonuçları sayfası Office.com, SharePoint.com ve Bing.com içindir.

7. Kiracı Yayımlama sekmesinde ayarlarınızı gözden geçirin ve yayımlama bilgileri ekleyin.

   1. Arama sağlayıcısı adını ve örnek sorguları gözden geçirin. Gerekirse bu bilgileri değiştirmek için önceki sekmelere dönün.
   2. Arama sağlayıcınızın açıklamasını girin.
   3. Destek iletişim e-postası girin. Arama sağlayıcısına erişimi olan bir geliştirici veya geliştirici grubunun e-postasını kullanın.

8. BT yöneticinizden onay istemek için Ekle'yi seçin.

Kiracıdaki arama sağlayıcısını onaylama

Kiracıdaki arama sağlayıcısı onayı, Microsoft 365 yönetim merkezi Arama ve Yönetim Bilgileri sayfasında bir BT yöneticisi tarafından yapılır.

Bağlantıyı test edin

Üretimde etkinleştirmeden önce test kiracısında arama sağlayıcısını etkinleştirmenizi öneririz.

Arama sağlayıcısını değiştirme

Arama sağlayıcısını BT yöneticisi tarafından gözden geçirilmeden önce düzenleyebilirsiniz. İlk isteğiniz reddedilirse veya hizmetiniz devre dışı bırakılırsa bunu yapmanız gerekebilir.

1. Azure portalında, düzenlemek istediğiniz arama sağlayıcısını içeren bot kaynağına gidin.
2. Kanallar (Önizleme) bölmesine gidin.
3. Arama kanalını ve ardından Düzenle'yi seçin.
   1. Azure, Arama Kanalı bölmesini görüntüler. Bu bölmede ayarlarınızı düzenleyebilirsiniz.
   2. Tetikleyici tümcecikleri değiştirmek için dosyayı indirin, yerel olarak düzenleyin ve dosyayı karşıya yükleyin.
   3. Düzenlemelerinizi tamamladıktan sonra, arama sağlayıcısını BT yöneticisinin gözden geçirmesi için göndermek için Yeniden Ekle'yi seçin.

Arama sağlayıcısını silme

Bot kaynağından Arama kanalını kaldırırsanız arama sağlayıcınız silinir.

Botunuzdan Arama kanalını kaldırmak için:

1. Azure portalında bot kaynağınıza gidin.
2. Kanallar (Önizleme) bölmesine gidin.
3. Arama kanalını seçin.
4. Kanal Ara bölmesinin üst kısmında Kanalı sil'i seçin.
5. İşlemi onaylamak için Evet'i seçin.

Bot kaynağınızı silmek için:

1. Azure portalında bot kaynağınıza gidin.
2. Henüz yapmadıysanız Botunuzdan Arama kanalını kaldırın.
3. Genel Bakış bölmesinin üst kısmında Sil'i seçin.
4. İşlemi onaylamak için Tamam'ı seçin.

Ek bilgi

Arama kanalı federasyon aramasını ve Uyarlamalı Kartlar şemasını kullanır:

Uyarlamalı Kart şeması hakkında daha fazla bilgi için bkz . Bot geliştiricileri için Uyarlamalı Kartlar.

Tetikleyici tümcecikleri hakkında

Tetikleyici tümcecik, arama platformunun botunuz tarafından desteklenen özel arama sağlayıcınıza sorgu yönlendirmek için kullandığı bir tümceciktir. Federasyon araması, konuşma tetikleyici tümceciklerinden biriyle yakın bir eşleşme olduğunda kullanıcının konuşmasını arama sağlayıcınıza iletir.

Bahşiş

Birden fazla arama sağlayıcısı varsa, federasyon araması sağlanan tetikleyici tümceciklerine ve kullanıcının sorgusuna göre yalnızca bir arama seçer.

Örnek olarak, uçuş zamanlamalarını ve durumunu yöneten bir bot düşünün.

1. Bir kullanıcının botunuza başvuracağı veya botunuzdan yararlanacağı birkaç yaygın yolu düşünün. Botunuzu diğerlerinden ayırt etmeye özen gösterin.

   Okullara ve TV programlarına uygulanabilen "zaman çizelgesi" gibi genel bir terim yerine , "uçuş zamanı tablosu" ve "uçuş planı" gibi daha belirgin ifadeler kullanın.

2. Botunuzun kalkış saati ve geçerli durum gibi özelliklerinin kapsamını kapsayan çeşitli ifadeler ekleyin.

   Örneğin, varış veya kalkış saatleri ve havaalanları hakkındaki sorguları ekleyin.

Böyle bir uçuş zamanlaması ve durum botu için tetikleyici tümcecikler şunları içerebilir:

• Uçuş zaman çizelgesi
• Uçuş durumu
• Uçuş 675 kalkış saati
• Uçağım ne zaman kalkacak?
• Uçuş 468 varış zamanı
• Seattle Tacoma uçuş durumu
• Heathrow uçuş durumu

Başka bir örnek olarak, hava durumu tahmin botu için tetikleyici tümcecikleri şunları içerebilir:

• Yerel hava durumu tahmini
• Hava durumu bilgileri
• Yarın hava durumu
• 10 günlük hava durumu tahmini
• Bugün yüksek
• Bugünün yağmur olasılığı
• Yarın kar yağacak mı?
• Yarın rüzgar hızı
• Dışarısı rüzgarlı mı?
• Londra hava durumu

Desteklenen Uyarlamalı Kart öğeleri

Federasyon aramasında Uyarlamalı Kart şemasının bir alt kümesi desteklenir. Arama sonuçlarınızı biçimlendirme hakkında bilgi için bkz . Arama sonuçları sayfasını özelleştirme.

Destek şu Uyarlamalı Kart öğelerini içerir: TextBlock, RichTextBlock, Image, ColumnSet, ImageSet ve FactSet. Daha fazla bilgi için bkz. Microsoft Arama Arama sonucu düzenlerini yönetme ve Uyarlamalı Kartlar Şema Gezgini.

Her kartı doğrudan JSON olarak yazabilir veya AdaptiveCards NuGet paketini kullanabilirsiniz.

Federasyon araması HTML'i desteklemiyor

Önemli

Federasyon araması HTML içeren Uyarlamalı Kart metnini işlemez.

Arama platformu html ayrıştırıcısı içermez. Ancak, bazı etiketleri ortadan kaldırıp Html2Markdown NuGet paketini kullanarak HTML'yi Markdown'a dönüştürebilirsiniz:

1. ve <u> öğelerini kaldırın<span>.
2. ve <br> öğelerini paragraf (<p>) öğeleriyle değiştirin<div>.
3. Kalan HTML'yi Markdown'a dönüştürün.

Sonraki adımlar

• Bot Bağlan veya Hizmeti'nde kanal desteği hakkında bilgi için bkz. Kanallara bot Bağlan.
• Bot oluşturma hakkında bilgi için bkz . Botlar nasıl çalışır ve Bot Framework SDK'sı ile bot oluşturma hızlı başlangıcı.
• Botları dağıtma hakkında bilgi için bkz . Botunuzu dağıtma ve Sürekli dağıtımı ayarlama.