Bir OpenAPI tanımından ö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ımlayan OpenAPI tanımı kullanarak özel bir bağlayıcı oluşturursunuz (bu dizi için örneğimiz).

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

• Bir Postman koleksiyonundan özel bağlayıcı oluşturma
• Sıfırdan özel bağlayıcı oluşturma

Ön koşullar

• Örnek API 'yi tanımlayan bir openapı tanımı. Özel bir bağlayıcı oluştururken, OpenAPI tanımı 1 MB 'den küçük olmalıdır. OpenAPI tanımının, OpenAPI 2.0 (önceden Swagger olarak biliniyordu) biçiminde olması gerekir.
• Bilişsel Hizmetler Metin Analizi API'si için API anahtarı.
• Aşağıdaki aboneliklerden birini:
  • Bumantık uygulamalarını kullanıyorsanız Azure
  • Power Automate
  • Power Apps
• Logic Apps kullanıyorsanız önce bir Azure Logic Apps özel bağlayıcısı oluşturun

OpenAPI tanımını içe aktarma

Şimdi yüklediğiniz Openapı tanımıyla çalışmaya hazırsınız. Gerekli tüm bilgiler tanımda yer alır ve özel bağlayıcı Sihirbazı 'na giderek bu bilgileri gözden geçirebilir ve güncelleştirebilirsiniz.

İlk olarak Logic Apps’e ya da Power Automate ve Power Apps’e yönelik OpenAPI tanımını içeri aktarın.

Mantık uygulamaları için OpenAPI tanımını alın

1. Azure portalına gidin ve daha önce Azure Logic Apps özel bağlayıcısı oluşturma bölümünde oluşturduğunuz Logic Apps bağlayıcısını açın.

2. Connector menüsünde, Logic Apps Bağlayıcısı öğesini seçin ve sonra Düzenle'yi seçin.

   

3. Genel bölümünde Bir OpenAPI dosyasını karşıya yükle seçeneğini belirleyip oluşturduğunuz OpenAPI tanımına gidin.

   

Power Automate ve Power Apps için OpenAPI tanımını alın

1. make.powerapps.com veya flow.microsoft.com adresine gidin.

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

   

3. Yeni özel bağlayıcı'yı ve ardından Bir OpenAPI dosyasını içeri aktar'ı seçin.

   

4. Özel bağlayıcı için bir ad girin ve indiridğiniz veya oluşturduğunuz OpenAPI tanımı gidip Devam’ı seçin.

   

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

Genel ayrıntıları incele

Bu noktadan itibaren Power Automate kullanıcı arabirimi gösterilecektir, ancak üç teknolojide de adımlar aşağı yukarı aynıdır. Tüm farklılıkları göstereceğiz. Konu bu kısmında, kullanıcı arabirimini genellikle gözden geçireceğiz ve değerlerin OpenAPI dosyasının bölümlerine nasıl karşılık geldiğini göstereceğiz.

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

2. Genel sayfasında, konak ve API’nin temel URL’si dahil olmak üzere OpenAPI tanımı koleksiyonundan içeri aktarılan bilgileri gözden geçirin. Bağlayıcı, API’nin nasıl çağrılacağını belirlemek için API ana bilgisayarını ve temel URL’yi kullanır.

   

   Not

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

   Openapı tanımının şu bölümü, Kullanıcı arabiriminin bu sayfasıyla ilgili bilgileri içeriyor:

     "info": {
       "version": "1.0.0",
       "title": "SentimentDemo",
       "description": "Uses the Cognitive Services Text Analytics Sentiment API to determine whether text is positive or negative"
     },
     "host": "westus.api.cognitive.microsoft.com",
     "basePath": "/",
     "schemes": [
       "https"
     ]
   

Kimlik doğrulama türünü inceleme

Özel bağlayıcılarda kimlik doğrulaması için çeşitli seçenekler sunulmaktadır. Öğretici hizmet API 'Leri API anahtar kimlik doğrulaması kullanır, bu nedenle Openapı tanımında belirtilmiştir.

Güvenlik sayfasında, API anahtarının kimlik doğrulama bilgilerini gözden geçirin.

Etiket, biri özel bağlayıcıyla ilk kez bağlantı kurduğunda görüntülenir; Düzenle'yi seçebilir ve değeri değiştirebilirsiniz. Parametre adı ve konumu, API tarafından beklenen değerlerle (bu durumda, "Ocp-Apim-Subscription-Key" ve "Üst bilgi") eşleşmelidir.

Openapı tanımının şu bölümü, Kullanıcı arabiriminin bu sayfasıyla ilgili bilgileri içeriyor:

  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  }

Bağlayıcı tanımını gözden geçirme

Özel bağlayıcı sihirbazının Tanım sayfası, bağlayıcınızın nasıl işlediğini ve mantıksal uygulamalar, akışlar ve uygulamalarda nasıl kullanıma sunulduğunu tanımlama konusunda size çok sayıda 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. Bu Kullanıcı arabiriminde nesneleri baştan tanımlamak hakkında bilgi için bkz. Bağlayıcı tanımı oluşturma.

1. Aşağıdaki alanda bağlayıcı için tanımlanmış tüm eylemler, tetikleyiciler (Logic Apps ve Power Automate için) ve başvurular görüntülenir. Burada OpenAPI tanımımdan DetectSentiment eylemi görüntülenmektedir. Bu bağlayıcıda tetikleyici yoktur, ancak Azure Logic Apps ve Power Automate ile web kancaları kullanma konusunda özel bağlayıcılara yönelik tetikleyiciler hakkında bilgi edinebilirsiniz.

   

2. Genel alanında, seçili eylem veya tetikleyici hakkında bilgi görüntülenir. Bir mantıksal uygulama veya akıştaki işlemler ve parametreler için Görünürlük özelliği dahil olmak üzere buradaki bilgileri düzenleyebilirsiniz:

   • hiçbiri - Normalde mantıksal uygulamada veya akışta görüntülenir

   • gelişmiş - Ek bir menünün altına gizlenir

   • dahili - kullanıcıdan gizlenir

   • önemli - Her zaman kullanıcıya ilk olarak gösterilir

     

3. İstek alanında, OpenApı tanımı eklenmiş HTTP isteğini temel alan bilgiler görüntülenir. Bu durumda, HTTP fiili, POST ve URL "/text/analytics/v2.0/sentiment" (API'nin tam URL'si "https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment"). Kısa süre içinde gövde parametresine daha sonra bakacağız.

   

   Openapı tanımının şu bölümü, Kullanıcı arabiriminin Genel ve İstek alanlarıyla ilgili bilgileri içeriyor:

   "paths": {
     "/text/analytics/v2.0/sentiment": {
       "post": {
         "summary": "Returns a numeric score representing the sentiment detected",
         "description": "The API returns a numeric score between 0 and 1. Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment.",
         "operationId": "DetectSentiment"
   

4. Yanıt alanında, OpenApı tanımı eklenmiş HTTP yanıtını temel alan bilgiler görüntülenir. Bu durumda yalnızca "200" (başarılı yanıt) için bir yanıt tanımlanmıştır ancak başka yanıtlar da tanımlayabilirsiniz.

   

   Openapı tanımının şu bölümü, yanıtla ilgili bazı bilgileri içeriyor:

   "score": {
    "type": "number",
    "format": "float",
    "description": "score",
    "x-ms-summary": "score"
   },
   "id": {
    "type": "string",
    "description": "id",
    "x-ms-summary": "id"
   }
   

   Bu bölüm, bağlayıcı tarafından döndürülen iki değeri gösterir: id ve score. Veri türlerini ve Openapı uzantısı olan x-ms-summary alanını içerir. Bu ve diğer uzantılar hakkında daha fazla bilgi için bkz. Özel bağlayıcı için OpenAPI tanımını genişletme.

5. Doğrulama alanı, API tanımında algılanan sorunları görüntüler. Bağlayıcıyı kaydetmeden önce bu alanı mutlaka denetleyin.

   

Tanımı güncelleştirme

İndirdiğiniz OpenAPI tanımı iyi bir temel örnektir. Ancak bağlayıcının bir mantıksal uygulamada, akışta veya uygulamada daha kolay kullanılabilmesi için çok fazla sayıda güncelleştirme gerektiren tanımlarla çalışabilirsiniz. Tanımda nasıl basit bir değişiklik yapılacağını göstereceğiz.

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 açıklamasını güncelleştirin ve Geri’yi seçin.

   

   Parametre	Value
   Açıklama	"Gönderdiğiniz her belge için bir sayısal tanımlayıcı."

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

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

Güncelleştirilmiş Openapı dosyasını karşıdan yükleyin

Bir OpenAPI dosyasından, bir Postman koleksiyonundan veya sıfırdan bir özel bağlayıcı oluşturabilirsiniz (Power Automate ve Power Apps’te). Bağlayıcı nasıl oluşturduğunuza bakılmaksızın hizmetin dahili olarak kullandığı OpenAPI tanımını indirebilirsiniz.

• Logic Apps'te özel bağlayıcıdan indirin.

  

• Power Automate veya Power Apps'te, özel bağlayıcılar listesinden yükleme yapın.

  

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:

   • Microsoft Flow’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. Sağ üst köşedeki dişli simgesini ve ardından Ö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.

   

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.

• Bir akışta özel bir bağlayıcı kullanma
• Uygulamadan özel bağlayıcı kullanma
• Bir mantıksal uygulamada özel bağlayıcı kullanma

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ı onaylayın