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

2025-06-16

Not

Bu makale, Azure Logic Apps'te özel bağlayıcılar oluşturma ve kullanma, Microsoft Power Automate ve Microsoft Power Apps ve Microsoft Copilot Studio'te Copilot bağlayıcılarını ve eylemlerini kullanma hakkındaki eğitim dizisinin bir parçasıdır. İşlemi anlamak için özel bağlayıcıya genel bakışı okuduğunuzdan emin olun.

Bağlayıcıları, Microsoft Copilot aracınızda bağlayıcı eylemleri olarak nasıl çağırabileceğinizi öğrenmek için Copilot Studio'te Power Platform bağlayıcılarını kullan bölümüne gidin.

Ö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 makalede, Azure Bilişsel Hizmetler Metin Analizi API duygu işlemini (bu seri için örneğimiz) tanımlamak için OpenAPI tanımını 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

Power Apps veya Power Automate uygulamasında oturum açın.
Sol bölmede Çözümler'i seçin.
Özel bağlayıcınızı içerecek yönetilmeyen bir çözümü düzenleyin veya oluşturun. Çözüm oluşturmayı öğrenin
Yeni açılır menüsünü seçin ve Otomasyon>Özel bağlayıcı'yı seçin.

Yeni bağlayıcı sihirbazı açılır
Bağlayıcı Adı'nı yazın, örneğin SentimentDemo.

Aşağıdaki talimatları kullanarak adımların geri kalanını tamamlayın.

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:

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

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.

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

Parametre Değer

Parametre etiketi API anahtarı

Parametre adı Ocp-Apim-Subscription-Key

Parametre konumu Üst bilgi
Sihirbazın üst kısmındaki adın SentimentDemo olarak ayarlandığından emin olun ve Bağlayıcı oluştur'u seçin.

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

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. Tanım sekmesi üzerinde, sol bölmede bağlayıcı için tanımlanan tüm eylemler, tetikleyiciler (Logic Apps, Power Automate ve Copilot Studio için) ve başvurular görüntülenir.

Not

Bu bağlayıcıda tetikleyici yok. Özel bağlayıcılar için tetikleyiciler hakkında bilgi edinmek için Azure Logic Apps için tetikleyici olarak webhook kullanma ve Power Automate bölümüne gidin.

Yeni eylem'i seçin.

Genel alanına 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

İstek alanında Örneklerden içe aktar'ı seçin.
API'ye bağlanmak için gerekli bilgileri belirtin, istek gövdesini belirtin (tablodan sonra sağlanır) ve ardından İçe 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 Örnek JSON'u kullanın.

Örnek:
```
{
  "documents": [
    {
      "language": "string",
      "id": "string",
      "text": "string"
    }
  ]
}
```
Yanıt alanında Varsayılan yanıtı ekle'yi seçin.
Yanıt gövdesini belirtin ve ardından İçeri Aktar'ı seçin. İstek gövdesinde yaptığımız gibi, bu bilgiyi de sizin için sağlıyoruz, ancak bu bilgiler genellikle API belgelerinde sağlanır.

Örnek:
```
{
 "documents": [
   {
     "score": 0.0,
     "id": "string"
   }
 ],
 "errors": [
   {
     "id": "string",
     "message": "string"
   }
 ]
}
```
Doğrulama alanı, API tanımında algılanan sorunları görüntüler.
Tüm sorunları düzeltin. Tanım doğrulaması başarılı olduğunda yeşil bir onay işareti görmeniz gerekir.
Sihirbazın sağ üst köşesinden Bağlayıcıyı güncelle'yi seçin.

Parametre	Değer
Fiil	POST
URL	`https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment`
Body	Örnek JSON'u kullanın.

Tanımı güncelleştirme

Logic Apps'te kullanıldığında konektörün daha kullanıcı dostu olması için birkaç şeyi değiştirelim, Power Automate, Power Apps veya Copilot Studio.

İstek alanında gövde’yi ve sonra Düzenle’yi seçin.
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.
Ş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
Parametre alanında, dil>Düzenle'yi seçin ve ardından id için kullandığınız işlemi tekrarlayarak aşağıdaki language değerlerini ekleyin:

Parametre Değer

Title Dil

Description Metnin iki veya dört karakterlik dil kodu

Default value en

Gereklidir Evet
Parametre alanında, metin>Düzenle'yi seçin ve ardından id ve language için kullandığınız işlemi tekrarlayarak aşağıdaki text değerlerini ekleyin:

Parametre Değer

Title Metin

Description Yaklaşım analizi uygulanacak metin

Default value None

Gereklidir Evet
Parametre alanında, ana Tanım sekmesine dönmek için Geri'yi seçin.
Sihirbazın sağ üst köşesinden Bağlayıcıyı güncelleştir'i 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

Parametre	Değer
Title	Dil
Description	Metnin iki veya dört karakterlik dil kodu
Default value	en
Gereklidir	Evet

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

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ıma göre ö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 5: 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.

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

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.

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

Test sekmesinde Yeni bağlantı'yı seçin.
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.
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 bölmede Ö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.
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.

Bağlayıcı API'yi çağırır.
Duygu puanını da içeren yanıtı inceleyin.

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

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.

Geri bildirimde bulunun

Bağlayıcı platformumuzla veya yeni özellik fikirlerimizle ilgili sorunlar hakkındaki geri bildirimleriniz 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.

Aracılığıyla paylaş