Sıfırdan özel bağlayıcı oluşturma

Özel Bağlayıcı oluşturmak için, bağlanmak istediğiniz API’yi açıklayarak bağlayıcının bu API’nin işlemlerini ve veri yapılarını anlamasını sağlamalısınız. Bu konu, Bilişsel hizmetler metin analizleri duyarlılık API'sını tanımlamak için Postman koleksiyonu veya OpenAPI tanımı kullanmadan sıfırdan özel bir bağlayıcı oluşturursunuz (bu dizi için örneğimiz). Bunun yerine, bağlayıcıyı tamamen özel bağlayıcı sihirbazında açıklarsınız.

API 'yi tanımlamanın diğer yolları için aşağıdaki konulara bakın:

• Bir OpenAPI tanımından özel bağlayıcı oluşturma
• Bir Postman koleksiyonundan özel bağlayıcı oluşturma

Ön koşullar

• Bilişsel Hizmetler Metin Analizleri API’si için bir API anahtarı.
• Aşağıdaki aboneliklerden birini:
  • Power Automate
  • Power Apps

Özel bağlayıcı Sihirbazını Başlat

1. Power Apps veya Power Automate hizmetinde oturum açın.

2. Gezinti bölmesinde Veri > Özel bağlayıcılar’ı seçin.

   

3. Yeni özel bağlayıcı’yı ve ardından Sıfırdan oluştur’u seçin.

   

4. Özel bağlayıcı için bir ad girin ve ardından Devam’ı seçin.

   

   Parametre	Value
   Özel bağlayıcı başlığı	"SentimentDemo"

Adım 1: genel ayrıntıları güncelleştirin

Bu noktadan itibaren Power Automate kullanıcı arabirimi gösterilecektir, ancak teknolojilerde de adımlar aşağı yukarı aynıdır. Tüm farklılıkları göstereceğiz.

1. Genel sayfasında:

   • Açıklama için anlamlı bir değer girin. Bu açıklama, özel bağlayıcının ayrıntılarında görüntülenir ve diğerlerinin bağlayıcının onlara yararlı olup olmadığını anlamalarına yardımcı olabilir.

   • Ana bilgisayarı, metin analizi API 'sinin adresi olarak güncelleştirin. Bağlayıcı, API’nin nasıl çağrılacağını belirlemek için API ana bilgisayarını ve temel URL’yi kullanır.

   

   Parametre	Value
   Açıklama	"Metnin pozitif veya negatif olup olmadığını belirlemek için Bilişsel Hizmetler Metin Analizleri Yaklaşım API'sini kullanır"
   Ana bilgisayar	"westus.api.cognitive.microsoft.com"

   Not

   Şirket içi veri ağ geçidi ile bağlanma seçeneği hakkında daha fazla bilgi için bkz. veri ağ geçidi kullanarak şirket içinde API'lere bağlanma.

2. adım: Kimlik doğrulama türünü belirtin

Özel bağlayıcılarda kimlik doğrulaması için çeşitli seçenekler sunulmaktadır. Bilişsel Hizmetler API'Leri API anahtar kimlik doğrulaması kullanır, bu nedenle bu öğretici için bunu tanımladınız.

1. Güvenlik sayfasındaki Kimlik doğrulaması türü bölümünden API Anahtarı’nı seçin.

   

2. API Anahtarı'nın altında bir parametre etiketi, adı ve konumu belirtin. Bir kişi özel bağlayıcıya ilk kez bağlandığında bu etiket görüntüleneceğinden, anlamlı bir etiket belirtin. Parametre adı ve konumu API 'nin beklediği ile eşleşmelidir. Bağlan öğesini seçin.

   

   Parametre	Value
   Parametre etiketi	"API anahtarı"
   Parametre adı	"Ocp-Apim-Subscription-Key"
   Parametre konumu	"Üstbilgi"

3. Sihirbazın üst kısmındaki adın "SentimentDemo" olarak ayarlandığından emin olun ve Bağlayıcı oluştur’u seçin.

Adım 3: bağlayıcı tanımını oluşturun

Özel bağlayıcı sihirbazı, bağlayıcınızın nasıl çalıştığını ve mantıksal uygulamalarda, akışlarda ve uygulamalarda nasıl gösterildiğini tanımlamak için birçok seçenek sunar. Kullanıcı arabirimini açıklayacak ve bu bölümde birkaç seçenekten daha fazla yer alacağız, ancak sizin de kendi başınıza keşfetmeye öneririz.

Eylem oluşturma

Yapılacak ilk şey, metin analizleri duyarlılık API 'sini çağıran bir eylem oluşturmaktır.

1. Tanım sayfası üzerinde, sol alanda bağlayıcı için tanımlanan tüm eylemler, tetikleyiciler (Logic Apps ve Power Automate için) ve başvurular görüntülenir. Yeni eylem seçin.

   

   Bu bağlayıcıda tetikleyici yok. Azure Logic Apps ve Power Automate ile web kancalarını kullanma bölümünde özel bağlayıcılar için tetikleyiciler hakkında bilgi edinebilirsiniz.

2. Genel alanında, seçili eylem veya tetikleyici hakkında bilgi görüntülenir. Bu eylem için bir Özet, açıklama ve işlem KIMLIĞI ekleyin.

   

   Parametre	Value
   Özet	"Algılanan duyarlılık öğesini gösteren bir sayısal puan döndürür"
   Açıklama	"API, 0 ile 1 arasında sayısal bir puan döndürür. 1'e yaklaşan puanlar olumlu yaklaşımı ve 0'a yaklaşan puanlar olumsuz yaklaşımı gösterir."
   İşlem Kimliği	"DetectSentiment"

   Görünürlük özelliğini hiçbiri olarak ayarlanmış olarak bırakın. Bir mantık uygulamasındaki veya akıştaki işlemler ve parametreler için bu özellik aşağıdaki seçeneklere sahiptir:

   • hiçbiri - Normalde mantıksal uygulamada veya akışta görüntülenir
   • gelişmiş: başka bir menünün altına gizlenmiş
   • dahili - kullanıcıdan gizlenir
   • önemli - Her zaman kullanıcıya ilk olarak gösterilir

3. İstek alanı, eyleme yönelik HTTP isteğine göre bilgileri görüntüler. Örnekten aktar'ı seçin.

   

4. API'ya ve istek gövdesine bağlanmak için gerekli bilgileri belirtin, sonra İçeri Aktar'ı seçin. Bu bilgileri sizin yerinize sağlıyoruz (resmin altında). Genel API için, genellikle Metin Analizleri Duyarlılık API'si gibi belgelerinden alırsınız.

   

   Parametre	Value
   Fiil	"GÖNDERİ"
   URL	"https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment"
   Gövde	Aşağıya bakın

   {
     "documents": [
       {
         "language": "string",
         "id": "string",
         "text": "string"
       }
     ]
   }
   

5. Yanıt alanı, eyleme yönelik HTTP yanıtına göre bilgileri görüntüler. Varsayılan yanıt ekle’yi seçin.

   

6. Yanıt gövdesini belirtip Al seçeneğini belirleyin. İstek gibi, bu bilgileri sizin yerinize sağlıyoruz, ancak genellikle API belgelerinde yer vardır.

   

   {
    "documents": [
      {
        "score": 0.0,
        "id": "string"
      }
    ],
    "errors": [
      {
        "id": "string",
        "message": "string"
      }
    ]
   }
   

7. Doğrulama alanı, API tanımında algılanan sorunları görüntüler. Durumu denetleyip sihirbazın sağ üst kısmında bağlayıcıyı Güncelleştir seçeneğini belirleyin.

   

Tanımı güncelleştirme

Şimdi bağlayıcının bir mantıksal uygulamada, akışta veya uygulamada daha kolay kullanılmasını sağlamak için birkaç değişiklik yapalım.

1. İstek alanında gövde’yi ve sonra Düzenle’yi seçin.

   

2. Parametre alanında artık API’nin beklediği üç parametreyi görürsünüz: id, language ve text. ID parametresini ve sonra da Düzenle’yi seçin.

   

3. Şema Özelliği alanında parametre değerlerini güncelleştirin ve Geri’yi seçin.

   

4. Parametre alanında sırasıyla dil’i ve Düzenle’yi seçin, sonra da id için kullandığınız işlemi aşağıdaki değerlerle tekrarlayın.

   Parametre	Value
   Başlık	"Dil"
   Açıklama	"Metin için 2 veya 4 karakterli dil kodu"
   Varsayılan değer	"en"
   Gereklidir	"Evet"

5. Parametre alanında sırasıyla metin’i ve Düzenle’yi seçin, sonra da id ve language için kullandığınız işlemi aşağıdaki değerlerle tekrarlayın.

   Parametre	Value
   Başlık	"Metin"
   Açıklama	"Yaklaşım analizi uygulanacak metin"
   Varsayılan değer	Hiçbiri
   Gereklidir	"Evet"

6. Parametre alanında Geri’yi seçerek ana tanım sayfasına dönün.

7. Sihirbazın sağ üst kısmında Bağlayıcıyı güncelleştir’i seçin.

Adım 4: (İsteğe bağlı) Özel kod desteği kullanma

Özel kod, istek ve yanıt yüklerini varolan ilke şablonlarının kapsamı ötesinde dönüştürür. Dönüşümler, ek veri getirmek için harici istekler göndermeyi içerir. Kod kullanıldığında, kodsuz tanımdan önceliklidir. Bu, kodun yürütüleceği ve isteği arka uca göndermeyeceğimiz anlamına gelir.

Kodunuzu yapıştırabilir veya kodunuzla birlikte bir dosya yükleyebilirsiniz. Kodunuz aşağıdaki gereksinimleri karşılamalıdır:

• C# dilinde yazılmalıdır.
• Maksimum 5 saniye yürütme süresi olmalıdır.
• 1 MB'den fazla olamaz (kod dosyasının boyutu).

Yönergeler ve kod yazma örnekleri için Özel bağlayıcılarda kod yazma'ya gidin.

Özel kod hakkında sık sorulan sorular için Özel kod ile ilgili SSS bölümüne gidin.

1. Kod sayfasında, aşağıdaki seçeneklerden birini kullanarak özel kodunuzu ekleyin:

   • Kopyala/yapıştır veya
   • Karşıya Yükle düğmesini seçin.

   Özel kodunuzu karşıya yüklemeyi seçerseniz, yalnızca .cs veya .csx uzantılı dosyalar kullanılabilir.

   
   

   Önemli

   Şu anda, kod düzenleyicisinde yalnızca sözdizimi vurgulamayı destekliyoruz. Kodunuzu yerel olarak sınayın.

2. Kodunuzu yapıştırdıktan veya karşıya yükledikten sonra, kodunuzu etkinleştirmek için Kod Devre Dışı yanındaki iki durumlu düğmeyi seçin. İki durumlu düğme adı Kod Etkin olarak değişir.

   Kodunuzu istediğiniz zaman etkinleştirebilir veya devre dışı bırakabilirsiniz. Düğme Kod Deve Dışı ise, kodunuz silinir.

   

3. Açılan listeden bir seçenek belirleyerek özel kodunuza uygulanacak eylemleri ve tetikleyicileri seçin. Hiçbir işlem seçilmezse, tüm işlemlere uygulanır.

   

5. adım: Bağlayıcıyı test etme

Şimdi de oluşturduğunuz bağlantının düzgün çalıştığından emin olmak için bağlantıyı test edin. Sınama Şu anda yalnızca Power Automate ve Power Apps uygulamasında kullanılabilir.

1. Test sayfasında Yeni bağlantı’yı seçin.

   

2. Metin Analizi API’sinden alınan API anahtarını girip Bağlantı oluştur’u seçin.

   

3. Test sayfasına dönün:

   • Power Automate’da Test sayfasına geri dönersiniz. Bağlantı bilgilerinin güncelleştirildiğinden emin olmak için yenile simgesini seçin.

   

   • Power Apps'te geçerli ortamda kullanılabilen bağlantıların listesine yönlendirilirsiniz. Gezinti bölmesinde Veri > Özel bağlayıcılar’ı seçin. Oluşturduğunuz bağlayıcıyı seçin, sonra da Test sayfasına dönün.

     

4. Test sayfasında metin alanı için bir değer girin (diğer alanlarda, daha önce ayarladığınız varsayılan değerler kullanılır) ve İşlemi test et’i seçin.

   

5. Bağlayıcı API 'yi çağırır ve duyarlılık Puanını da içeren yanıtı gözden geçirebilirsiniz.

   

(CLI kullanıcıları için) En iyi uygulamalar

• Tüm bağlayıcılarınızı indirin ve git veya başka herhangi bir kaynak kod yönetimi sistemini kullanarak dosyaları kaydedin.

• Yanlış bir güncelleştirme yapılması durumunda, güncelleştirme komutunu kaynak kod yönetimi sistemindeki doğru dosya kümesiyle yeniden çalıştırarak bağlayıcıyı yeniden dağıtın.

• Özel bağlayıcıyı ve ayarlar dosyasını üretim ortamına dağıtmadan önce bir test ortamında test edin.

• Ortamın ve bağlayıcı kimliğinin doğruluğundan emin olmak için her zaman ikinci bir kez denetleyin.

Sonraki adımlar

Artık özel bir bağlayıcı oluşturup bağlayıcının davranışlarını tanımladığınıza göre bağlayıcıyı aşağıdakilerden kullanabilirsiniz:

• Akış
• Uygulama
• Mantıksal uygulama

Ayrıca, bir bağlayıcıyı kuruluşunuzun içinde paylaşabilir ve/veya kuruluşunuz dışındaki kişilerin de kullanabilmesi için bağlayıcınıza sertifika alabilirsiniz:

• Bağlayıcınızı paylaşın
• Bağlayıcınızı onaylama