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

Not

Bu makale, Azure Logic Apps, Microsoft Power Automate ve Microsoft Power Apps'te özel bağlayıcılar oluşturma ve kullanma ve Microsoft Copilot Studio'da bağlayıcıları araç olarak çağırma öğ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 bir OpenAPI Tanımı (OAD ). Ö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 (eski adıyla Swagger) 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:
- Azure, Logic Apps kullanıyorsanız
- Power Automate
- Power Apps
Logic Apps kullanıyorsanız önce bir Azure Logic Apps özel bağlayıcısı oluşturun

Not

OpenAPI tanımının OpenAPI 2.0 (eski adı Swagger) biçiminde olması gerekir. OpenAPI 3.0 biçimindeki OpenAPI tanımları desteklenmez.
OpenAPI Belirtimleri'nde belge, tanım ve açıklama kullanımı gelişiyor... Bu makalede "terim", "tanım" ve "açıklama" kelimelerinin birbirinin yerine kullanıldığını görebilirsiniz.

OpenAPI tanımını içeri aktarma

Bu öğretici, Bilişsel Hizmetler Metin Analizi Duygu Analizi API'si için örnek bir OpenAPI tanımı kullanır. Takip edebilmek için, SentimentDemo.json adlı yerel bir JSON dosyası oluşturun ve aşağıdaki OpenAPI 2.0 tanımını içine yapıştırın:

{
  "swagger": "2.0",
  "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"],
  "consumes": ["application/json"],
  "produces": ["application/json"],
  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  },
  "security": [{"api_key": []}],
  "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",
        "parameters": [{
          "in": "body",
          "name": "body",
          "schema": {
            "type": "object",
            "properties": {
              "documents": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {"type": "string", "x-ms-summary": "id"},
                    "language": {"type": "string", "x-ms-summary": "language"},
                    "text": {"type": "string", "x-ms-summary": "text"}
                  }
                }
              }
            }
          }
        }],
        "responses": {
          "200": {
            "description": "200",
            "schema": {
              "type": "object",
              "properties": {
                "documents": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "score": {"type": "number", "format": "float", "description": "score", "x-ms-summary": "score"},
                      "id": {"type": "string", "description": "id", "x-ms-summary": "id"}
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Artık bu OpenAPI tanımını içeri aktarmaya hazırsınız. Tanım tüm gerekli bilgileri içerir. Özel bağlayıcı sihirbazında ilerledikçe 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.

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

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.
Bağlayıcı menüsünde, Logic Apps Bağlayıcısı öğesini seçin ve ardından Düzenle'yi seçin.
Genel bölümünde OpenAPI dosyasını karşıya yükle seçeneğini belirleyin ve oluşturduğunuz OpenAPI dosyasına gidin.

Not

Bu öğretici REST API'ye odaklanır, ancak Logic Apps ile bir SOAP API de kullanabilirsiniz.

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

Power Apps veya Power Automate uygulamasında oturum açın.
Sol bölmede Çözümler'i seçin, ardından kullanmak istediğiniz çözümü açın veya yeni bir çözüm oluşturun.
Yeni>Otomasyon>Özel bağlayıcı'yı seçin.
OpenAPI dosyasını içeri aktar'ı seçin.
Özel bağlayıcı için bir ad girin, oluşturduğunuz dosyayı seçin SentimentDemo.json ve ardından Devam'ı seçin.

Parametre Değer

Özel bağlayıcı başlığı SentimentDemo

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.

Sihirbazın üst kısmındaki adın SentimentDemo olarak ayarlandığından emin olun ve Bağlayıcı oluştur'u seçin.
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.

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ındaki Tanım sayfası, bağlayıcınızın nasıl çalıştığını ve Logic Apps, akışlar ve uygulamalarda nasıl sunulduğunu tanımlamanız için size birçok seçenek sunar. Bu bölümde kullanıcı arayüzünü açıklayacak ve birkaç seçeneği ele alacağız, ancak kendi başınıza da keşfetmenizi öneririz. Bu Kullanıcı arabiriminde nesneleri baştan tanımlamak hakkında bilgi için bkz. Bağlayıcı tanımı oluşturma.

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

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

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

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

Parametre Değer

Tanım Gönderdiğiniz her belge için bir sayısal tanımlayıcı
Parametre alanında Geri’yi seçerek ana tanım sayfasına dönün.
Sihirbazın sağ üst köşesinden Bağlayıcıyı güncelleştir'i seçin.

Parametre	Değer
Tanım	Gönderdiğiniz her belge için bir sayısal tanımlayıcı

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

Önemli

API anahtarı kullanırken, bağlayıcıyı oluşturur oluşturmaz test etmenizi önermiyoruz. Bağlayıcının API'ye bağlanmaya hazır olması birkaç dakika sürebilir.

Test sayfasında, Yeni bağlantı'yı seçin.
Metin Analizi API’sinden alınan API anahtarını girip Bağlantı oluştur’u seçin.
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.
- 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.
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.
Bağlayıcı API 'yi çağırır ve duyarlılık Puanını da içeren yanıtı gözden geçirebilirsiniz.

Özel bağlayıcı kullanma

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.

Satış için Microsoft 365 Copilot için özel bir bağlayıcı ve bağlayıcı eylemi oluşturun

Power Apps veya Power Automate içindeki OpenAPI tanımından özel bir bağlayıcı oluşturabilir ve bu bağlayıcıyı daha sonra Microsoft 365 Satış için Copilot için kullanabilirsiniz. Başlamak için nasıl başlayacağınızı öğrenmek üzere Özel bağlayıcı ve bağlayıcı eylemi oluşturma bölümüne gidin.

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.

Last updated on 2026-06-03