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

  • Makale

Not

Bu konu Azure Logic Apps, Microsoft Power Automate ve Microsoft Power Apps’te özel bağlayıcı oluşturma ve kullanmayla ilgili bir öğretici serisinin bir parçasıdır. İş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, Bilişsel Hizmetler Metin Analizi Duyarlılık API'sini (bu seri için örneğimiz) açıklayan bir OpenAPI tanımı kullanarak özel bir bağlayıcı oluşturacaksınız.

API'yi açıklamanın başka bir yolu için Sıfırdan özel bağlayıcı oluşturma'ya gidin.

Önkoşullar

  • Örnek API'yi açıklayan OpenAPI tanımı. Özel bir bağlayıcı oluştururken OpenAPI tanımının 1 MB'den küçük olması gerekir. OpenAPI tanımının OpenAPI 2.0 (önceden Swagger olarak biliniyordu) biçiminde olması gerekir.

    Birden çok güvenlik tanımı varsa, özel bağlayıcı en üst güvenlik tanımını seçer. Özel bağlayıcı oluşturma, OAuth güvenlik tanımında istemci kimlik bilgilerini (örneğin, uygulama ve parola) desteklemez.

  • Bilişsel Hizmetler Metin Analizi API'si için API anahtarı.

  • Aşağıdaki aboneliklerden birini:

  • Logic Apps kullanıyorsanız önce bir Azure Logic Apps özel bağlayıcısı oluşturun

OpenAPI tanımını içeri aktarma

Şimdi yüklediğiniz OpenAPI tanımıyla çalışmak için 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.

Not

OpenAPI tanımının OpenAPI 2.0 (önceden Swagger olarak biliniyordu) biçiminde olması gerekir. OpenAPI 3.0 biçimindeki OpenAPI tanımları desteklenmez.

Logic Apps için OpenAPI tanımını içeri aktarma

  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. Bağlayıcı menüsünde, Logic Apps Bağlayıcısı öğesini seçin ve ardından Düzenle'yi seçin.

    Logic Apps Bağlayıcısını düzenleme.

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

    OpenAPI dosyası yükleme.

Not

Bu öğretici bir REST API odaklanır, ancak Logic Apps ilebir SOAP apı de kullanabilirsiniz.

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

  1. Power Apps veya Power Automate uygulamasında oturum açın.

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

    Özel bağlayıcı seç.

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

    OpenAPI dosyası içeri aktar.

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

    Koleksiyon yükleyin.

    Parametre Değer
    Ö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. Konunun bu kısmında, çoğunlukla kullanıcı arabirimini gözden geçireceğiz ve değerlerin OpenAPI dosyanı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, API konağı ve API’nin temel URL’si dahil olmak üzere OpenAPI tanımından 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.

    Özel bağlayıcı genel sayfası.

    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.

    OpenAPI tanımının aşağıdaki bölümü, kullanıcı arabiriminin bu sayfasıyla ilgili bilgiler içerir:

      "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. Bilişsel Hizmetler API'leri, API anahtarı kimlik doğrulaması kullanır. Bu nedenle bu OpenAPI tanımında belirtilir.

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

API Anahtarı Parametreleri.

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.

OpenAPI tanımının aşağıdaki bölümü, kullanıcı arabiriminin bu sayfasıyla ilgili bilgiler içerir:

  "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 işleyişi ve mantıksal uygulamalarda, akışlarda ve uygulamalarda nasıl sunucağıyla ilgili 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. 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. Bu durumda, OpenAPI tanımdan DetectSentiment eylemi görüntülenir. 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.

    Tanım sayfası - eylemler ve Tetikleyiciler.

  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

      Tanım sayfası - genel.

  3. İstek alanı, OpenAPI tanımına dahil edilen HTTP isteğine dayalı olarak bilgileri görüntüler. Bu durumda, HTTP fiilinin, POST olduğunu ve URL'nin /text/analytics/v2.0/sentiment olduğunu görürsünüz (API'nin tam URL'si şu şekildedir: <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>). Kısa süre içinde gövde parametresine daha sonra bakacağız.

    Tanım sayfası - isteği.

    OpenAPI tanımının aşağıdaki bölümü, kullanıcı arabiriminin Genel ve İstek alanlarıyla ilgili bilgiler içerir:

    "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ı, OpenAPI tanımına dahil edilen HTTP yanıtına dayalı olarak bilgileri görüntüler. 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.

    Tanım sayfası - yanıt.

    OpenAPI tanımının aşağıdaki bölümü, yanıtla ilgili bilgilerin bazılarını içerir:

    "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 bir OpenAPI 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 sayfası - doğrulama.

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 bir değişiklik yapılacağını göstereceğiz.

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

    İstek gövdesini düzenle.

  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.

    İstek gövdesi kimliğini düzenle.

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

    Şema özelliğini düzenle.

    Parametre Değer
    Tanım 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öşesinden Bağlayıcıyı güncelleştir'i seçin.

Güncelleştirilmiş OpenAPI dosyasını indirme

OpenAPI dosyasından veya (Power Automate ve Power Apps uygulamasında) sıfırdan özel bir bağlayıcı oluşturabilirsiniz. Bağlayıcı nasıl oluşturduğunuzu gözetmeksizin hizmetin dahili olarak kullandığı OpenAPI tanımını indirebilirsiniz.

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

    Logic Apps için OpenAPI tanımını indirme.

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

    Power Automate için OpenAPI tanımını indirme.

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 sayfasında, Yeni bağlantı'yı seçin.

    Yeni bağlantı.

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

    Bağlantı oluşturma.

  3. Test sayfasına dönün ve şunlardan birini yapı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.

      Bağlantıyı yenileme.

    • Power Apps'te geçerli ortamda kullanılabilen bağlantıların listesine yönlendirilirsiniz. Sağ üst köşede dişli simgesini ve sonra Özel bağlayıcılar'ı seçin. Oluşturduğunuz bağlayıcıyı seçin, sonra da Test sayfasına dönün.

      Hizmette dişli simgesi.

  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.

    Test işlemi.

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

    Bağlayıcı yanıtı.

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