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

Bu makale, Azure Logic Apps, Microsoft Power Automate ve Microsoft Power Apps’te özel bağlayıcı oluşturma ve kullanmayla ilgili öğretici serisinin bir parçasıdır.

Not

İşlemi anlamak için özel bağlayıcıya genel bakışı okuduğunuzdan emin olun.

Ö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 konuda, Azure Bilişsel Hizmetler Metin Analizleri API'sini açıklamak için (bu serideki örneğimiz) bir OpenAPI tanımı kullanmadan sıfırdan özel bir bağlayıcı oluşturacaksınız. Bunun yerine, bağlayıcıyı tamamen özel bağlayıcı sihirbazında açıklarsınız.

API'yi açıklamanın başka bir yolu için bkz. OpenAPI tanımından özel bağlayıcı oluşturma.

Not

Şu anda Power Automate ve Power Apps uygulamasında sıfırdan özel bir bağlayıcı oluşturabilirsiniz. Logic Apps için en azından bir temel OpenAPI tanımı ile başlamanız gerekir.

Önkoş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 uygulamasında oturum açın.

2. Sol panelde, Veriler > Özel bağlayıcılar'ı seçin.

3. Yeni özel bağlayıcı > Boş şablondan oluştur seçeneğini belirleyin.

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

   Parametre	Değer
   Ö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.

Genel sekmesinde aşağıdakileri yapabilirsiniz:

1. Açıklama alanında anlamlı bir değer girin. Bu açıklama, özel bağlayıcının ayrıntılarında görüntülenir ve bağlayıcının kendileri için yararlı olup olmayacağını başkalarının karar vermesine yardımcı olabilir.

2. Ana Bilgisayar alanını, Text Analytics API'nin 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	Değer
   Veri Akışı Açıklaması	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

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 sekmesinde, Kimlik doğrulaması türü altında 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'ı seçin.

   Parametre	Değer
   Parametre etiketi	API key
   Parametre adı	Ocp-Apim-Subscription-Key
   Parametre konumu	Üst bilgi

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 API'si duyarlılık operasyonunu çağıran bir eylem oluşturmaktır.

1. Tanım sekmesi üzerinde, sol bölmede 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'i seçin.

   Bu bağlayıcıda tetikleyici yok. Özel bağlayıcılara yönelik tetikleyiciler hakkında bilgi edinmek için Azure Logic Apps ve Power Automate ile web kancalarını kullanma konusuna gidin.

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	Değer
   Özet	Algılanan duyarlılık öğesini gösteren bir sayısal puan döndürür
   Tanım	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'ye ve istek gövdesine bağlanmak (aşağıdaki görüntünün ardından sağlanır) için gerekli bilgileri belirtin ve sonra İçeri Aktar'ı seçin. Bu bilgileri sizin için sağlıyoruz; ancak genel API için bu bilgileri genellikle Metin Analizi API (v 2.0) gibi belgelerden alırsınız.

   Parametre	Değer
   Fiil	POST
   URL	<https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment>
   Body	Aşağıdaki JSON kodunu kullanın

   Örnek:

   {
     "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 belirtin ve ardından İçeri Aktar'ı seçin. İstek gövdesi için yaptığımız gibi bu bilgileri sizin için görüntüden sonra sağlıyoruz ancak bunlar genellikle API belgelerinde bulunur.

   Örnek:

   {
    "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 denetleyin ve sihirbazın sağ üst köşesinde Bağlayıcıyı güncelleştir'i seçin.

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. Kimlik'i seçin ve ardından Düzenle'yi seçin.

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

   Parametre	Değer
   Title	Kimlik
   Veri Akışı Açıklaması	Gönderdiğiniz her belge için bir tanımlayıcı
   Default value	Kategori 1
   Gereklidir	Evet

4. Parametre alanında, dil > Düzenle öğesini seçin ve ardından bu prosedürün 2. ve 3. adımlarında id için kullandığınız işlemi aşağıdaki değerlerle tekrarlayın.

   Parametre	Değer
   Title	Dil
   Veri Akışı Açıklaması	Metnin iki veya dört karakterlik dil kodu
   Default value	en
   Gereklidir	Evet

5. Parametre alanında, metin > Düzenle öğesini seçin ve ardından bu prosedürün 2. ve 3. adımlarında id için kullandığınız işlemi aşağıdaki değerlerle tekrarlayın.

   Parametre	Değer
   Title	Metin
   Tanım	Yaklaşım analizi uygulanacak metin
   Default value	None
   Gereklidir	Evet

6. Parametre alanında, sizi ana Tanım sekmesine geri götürmesi için Geri'yi seçin.

7. Sihirbazın sağ üst köşesinden Bağlayıcıyı güncelleştir'i seçin.

Adım 4: (İsteğe bağlı) Bağlayıcınızı yapay zeka eklentisi olarak etkinleştirin

Yalnızca bağlayıcınızı onaylamayı planlıyorsanız bağlayıcının Yapay Zeka Eklentisi (önizleme) sekmesini kullanın. Bağlayıcının yapay zeka eklentisi olarak kullanılabilmesi için sertifikalı olması gerekir.

Bağlayıcınızı yapay zeka eklentisi olarak etkinleştirmeden önce, yapay zeka eklentisi senaryolarının kullanım durumunu anladığınızdan ve desteklenebilirlik, en iyi uygulamalar ve öneriler gibi diğer hususları incelediğinizden emin olun. Daha fazla bilgi: Bağlayıcı yapay zeka eklentisi oluşturma (önizleme)

1. Sol gezinti bölmesinde, Özel bağlayıcılar'ı seçin.

   Özel bağlayıcılar'ı görmezseniz Diğer > Tümünü keşfet > Özel bağlayıcılar'ı seçin. Seçenek, sol gezinme bölmesinde görüntülenir.

2. Sağ üstte, Yeni özel bağlayıcı menüsünden bir seçenek belirleyin.

3. Bu makaledeki Adım 1, Adım 2 ve Adım 3 bölümlerini tamamladığınızdan emin olun.

4. Yapay Zeka Eklentisi (önizleme) sekmesini seçin.

5. Eklenti bildirimi bölümünde, bu bağlayıcıyı yapay zeka eklentisi olarak etkinleştirmek için ayrıntıları girin.

   

   Alan	Description
   Eklenti Bildirimi: Adı	Yapay zeka eklentisinin adı.
   Eklenti Bildirimi: Açıklama	Yapay zeka eklentisinin açıklaması. Daha fazla bilgi: Bağlayıcı yapay zeka eklentisi oluşturma (önizleme)
   Eklenti Bildirimi: İletişim E-postası	Bu yapay zeka eklentisi için ilgili kişinin e-posta adresi.
   Eklenti Bildirimi: Yasal Bilgiler URL'si	Yapay zeka eklentinizle ilgili yasal bilgilerin yayımlandığı, herkese açık bir konum.

6. Eklenti Eylemleri Ayrıntıları bölümüne aşağı kaydırın ve bağlayıcınızın yapay zeka eklentisinde her eylem için eylem ayrıntılarını girin.

   

   Alan	Description
   Eklenti Eylem Ayrıntıları: Özet	Kullanıcıların gerçekleştirebileceği her yapay zeka eklentisi eylemi hakkında özet.
   Eklenti Eylem Ayrıntıları: Açıklama	Kullanıcıların bu belirli yapay zeka eklentisi eylem adımıyla ilgili gerçekleştirebileceği her eylemin açıklaması.
   Onay kutusu: Yardımcı pilot eklentisi işlemi olarak etkinleştirme	Onay kutusunda onay işareti olduğunda yapay zeka eklentisi işlemi etkinleştirilir.
   Onay kutusu: Kullanıcı Onayı gerekiyor mu?	Onay kutusunda onay işareti olduğunda kullanıcı onayı gerekir.

   İpucu

   Eylemlerinizi tanımlama konusunda yardım gerekirse Swagger düzenleyicisi geçiş düğmesini açın.

7. Parametre bölümüne aşağı kaydırın ve bağlayıcınızın yapay zeka eklentisi için parametre ayrıntılarını girin.

   

   Alan	Description
   Parametre: Adı	Parametrenin adı. Kimlik yerine Firma Tanımlayıcısı gibi tanımlayıcı adlar kullanın.
   Parametre: Açıklama	Parametrenin açıklaması. b_date yerine GG/AA/YYYY biçiminde ilgili kişinin doğum günü gibi ayrıntılı açıklama kullanın. Bu tür adlar ve açıklamalar, LLM'lerin (büyük dil modelleri) yapay zeka eklentisiyle etkili şekilde etkileşime girmesine yardımcı olur.
   Parametre: Özet	Parametre hakkında özet bilgiler.
   Parametre: Varsayılan değer	Parametrenin varsayılan değeri.

8. Yapay Zeka Eklentisi (önizleme) bölümlerinin altındaki İstek bölümünde, giriş parametresini seçin ve ardından açıklama girin.

Adım 5: (İ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.

Not

• Bu adım isteğe bağlıdır. Bu adımı yok sayarak bağlayıcınızı oluşturmak için kodsuz deneyimi tamamlayabilir ve Adım 6: Bağlayıcıyı test etme'ye gidebilirsiniz.
• Özel kod desteği genel önizlemede kullanılabilir.

Kodunuzu yapıştırabilir veya kodunuzla birlikte bir dosya yükleyebilirsiniz. Kodunuz:

• C# dilinde yazılmalıdır.
• Maksimum beş saniye yürütme süresi olmalıdır.
• Dosya boyutunun 1 MB'den büyük olması gerekir.

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 sekmesinde, aşağıdaki seçeneklerden birini kullanarak özel kodunuzu girin:

   • Kopyala/yapıştır
   • 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 menüden bir seçenek belirleyerek özel kodunuza uygulanacak eylemleri ve tetikleyicileri seçin. İşlem seçilmezse eylemler ve tetikleyiciler, tüm işlemlere uygulanır.

   

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

Önemli

API anahtarı kullanırken bağlayıcıyı oluşturduktan hemen sonra sınamaması önerilir. Bağlayıcının API'ye bağlanmaya hazır olması birkaç dakika sürebilir.

1. Test sekmesinde Yeni bağlantı'yı seçin.

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

   Not

   Taşıyıcı kimlik doğrulaması gerektiren API'ler için API anahtarından önce Taşıyıcı ve bir boşluk ekleyin.

3. Test sekmesine dönün ve şunlardan birini yapın:

   • (Power Automate uygulamasında) Yeniden Test sekmesine yönlendirilirsiniz. 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. Sol panelde, Veriler > Özel bağlayıcılar'ı seçin. Oluşturduğunuz bağlayıcıyı seçin ve ardından Test sekmesine geri dönün.

4. Test sekmesinde, metin alanı için bir değer girin (diğer alanlar daha önce ayarladığınız varsayılanları kullanır) ve ardından Test işlemi'ni 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 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ı onaylayın

Geri bildirimde bulunun

Bağlayıcı platformumuzla ilgili sorunlar veya yeni özellik fikirleri hakkındaki geri bildiriminiz bizim için çok önemlidir. Geri bildirimde bulunmak için Sorun gönderme veya bağlayıcılarla ilgili yardım alma bölümüne gidip geri bildirim türünü seçin.