CLI ile özel bir bağlayıcı oluşturma

paconn komut satırı aracı, Copilot Studio ve Power Platform için özel bağlayıcıların oluşturulmasına yardımcı olmak üzere tasarlanmıştır.

Not

Yükle

  1. Python 3.5+ sürümünü [https://www.python.org/downloads](Python downloads) adresinden yükleyin. Python 3.5’ten sonraki bir Python sürümünde İndir bağlantısını seçin. Linux ve macOS X için sayfadaki uygun bağlantıyı izleyin. Ayrıca seçtiğiniz işletim sistemine özgü paket yöneticisini kullanarak da yükleyebilirsiniz.

  2. Yükleyiciyi çalıştırarak yüklemeye başlayın ve Add Python X.X to PATH (PATH Değişkenine Python X.X Ekle) kutusunu işaretlediğinizden emin olun.

  3. Şu komutu çalıştırarak PATH değişkeninde yükleme yolunun bulunduğundan emin olun:

    python --version

  4. Python yüklendikten sonra şu komutu çalıştırarak paconn aracını yükleyin:

    pip install paconn

    Erişim engellendi olarak bir hata alırsanız, --user seçeneğini kullanmayı veya komutu bir Yönetici (Windows) olarak çalıştırmayı deneyin.

Özel bağlayıcı dizini ve dosyaları

Özel bir bağlayıcı iki ila dört dosyadan oluşur:

  • Açık API/swagger tanımı
  • bir API özellik dosyası
  • bağlayıcı için isteğe bağlı bir simge
  • isteğe bağlı csharp komut dosyası

Dosyalar adı bağlayıcı kimliğiyle aynı olan bir dizinde yer alır.

Bazen özel bağlayıcı dizini bir settings.json dosyası içerir. Bu dosya bağlayıcı tanımının bir parçası olmasa da, onu CLI için bir argüman deposu olarak kullanabilirsiniz.

API tanımı (swagger) dosyası

API tanımlama dosyası, swagger dosyası olarak da bilinen OpenAPI spesifikasyonunu kullanarak özel bağlayıcı için API'yi açıklar. Bir API tanım dosyasının özel bir bağlayıcı oluşturmanıza nasıl yardımcı olduğu hakkında daha fazla bilgi için OpenAPI tanımından özel bir bağlayıcı oluşturma bölümüne gidin. Ayrıca Özel bağlayıcı için OpenAPI tanımını genişletme eğitimini inceleyin.

API özellikleri dosyası

API özellikleri dosyası, özel bağlayıcı için API tanımının parçası olmayan bazı özellikler içerir. API özellik dosyası, marka rengi, kimlik doğrulama bilgileri vb. gibi bilgileri içerir. Normal bir API özellikleri dosyası aşağıdaki örneğe benzer:

{
  "properties": {
    "capabilities": [],
    "connectionParameters": {
      "api_key": {
        "type": "securestring",
        "uiDefinition": {
          "constraints": {
            "clearText": false,
            "required": "true",
            "tabIndex": 2
          },
          "description": "The KEY for this API",
          "displayName": "KEY",
          "tooltip": "Provide your KEY"
        }
      }
    },
    "iconBrandColor": "#007EE6",
    "scriptOperations": [
        "getCall",
        "postCall",
        "putCall"
    ],
    "policyTemplateInstances": [
      {
        "title": "MyPolicy",
        "templateId": "setqueryparameter",
        "parameters": {
            "x-ms-apimTemplateParameter.name": "queryParameterName",
            "x-ms-apimTemplateParameter.value": "queryParameterValue",
            "x-ms-apimTemplateParameter.existsAction": "override"
        }
      }
    ]    
  }
}

İşte her bir mülk hakkında daha fazla bilgi:

  • properties: Bilgilerin kapsayıcısı.

  • connectionParameters: Hizmetin bağlantı parametresini tanımlar.

  • iconBrandColor: Özel bağlayıcı için HTML onaltılık kodda simge marka rengi.

  • scriptOperations: Komut dosyasıyla yürütülen işlemlerin listesi. Boş scriptOperations listesi tüm işlemlerin betik dosyasıyla yürütüldüğünü gösterir.

  • capabilities: Bağlayıcının özelliklerinin açıklaması. Örneğin, yalnızca bulut tabanlı ve şirket içi ağ geçidi.

  • policyTemplateInstances: Özel bağlayıcının kullandığı ilke şablonu örneklerinin ve değerlerinin isteğe bağlı listesi.

Simge dosyası

Simge dosyası, özel bağlayıcı simgesini temsil eden küçük bir resimdir.

Betik dosyası

Visual C# Script (CSX) betik dosyası özel bağlayıcı için dağıtılır ve bağlayıcının işlemlerinin bir alt kümesine yapılan her çağrı için yürütülür.

Ayarlar dosyası

Bağımsız değişkenleri komut satırında sağlamak yerine bunları belirtmek için bir settings.json dosyası kullanılabilir. Tipik bir settings.json dosyası şu örneğe benzer:

{
  "connectorId": "CONNECTOR-ID",
  "environment": "ENVIRONMENT-GUID",
  "apiProperties": "apiProperties.json",
  "apiDefinition": "apiDefinition.swagger.json",
  "icon": "icon.png",
  "script": "script.csx",
  "powerAppsApiVersion": "2016-11-01",
  "powerAppsUrl": "https://api.powerapps.com"
}

Ayarlar dosyasında bu öğeleri bekleyin. Bir seçenek eksikse ama gerekliyse, konsol eksik bilgileri ister.

  • connectorId: Özel bağlayıcı için bağlayıcı kimliği dizesi. İndirme ve güncelleme işlemleri bağlayıcı kimliği parametresini gerektirirken, oluşturma ve doğrulama işlemleri gerektirmez. create komutu yeni bir kimliğe sahip yeni bir özel bağlayıcı oluşturur. Aynı ayarlar dosyasını kullanarak mevcut bir özel bağlayıcıyı güncellemeniz gerekiyorsa, ayarlar dosyasını oluşturma işleminden gelen yeni bağlayıcı kimliğiyle güncellediğinizden emin olun.

  • environment: Özel bağlayıcı için ortam kimliği dizesi. Doğrulama işlemi hariç tüm işlemler bu parametreyi gerektirir.

  • apiProperties: API özellikleri dosyasının yolu. Oluşturma ve güncelleştirme işlemleri için API özellikleri dosyası gerekir. İndirme sırasında bu seçenek mevcut olduğunda dosya olması gereken yere indirilir; aksi takdirde dosya apiProperties.json olarak kaydedilir.

  • apiDefinition: Swagger dosyasının yolu. Oluşturma, güncelleme ve doğrula işlemleri API tanımları dosyasını gerektirir. İndirme işlemi sırasında bu seçenek mevcut olduğunda dosya olması gereken yere indirilir; aksi takdirde dosya apiDefinition.swagger.json olarak kaydedilir.

  • icon: İsteğe bağlı simge dosyasının yolu. Bu parametre için bir belirtim yoksa, oluştur ve güncelleme işlemleri varsayılan simgeyi kullanır. İndirme işlemi sırasında bu seçenek mevcut olduğunda dosya olması gereken yere indirilir; aksi takdirde dosya icon.png olarak kaydedilir.

  • script: İsteğe bağlı betik dosyasının yolu. Oluşturma ve güncelleştirme işlemleri, yalnızca belirtilen parametre içindeki değeri kullanır. İndirme işlemi sırasında bu seçenek mevcut olduğunda dosya olması gereken yere indirilir; aksi takdirde dosya script.csx olarak kaydedilir.

  • powerAppsUrl: Power Apps için API URL'si. Parametre isteğe bağlıdır ve varsayılan olarak https://api.powerapps.com olarak ayarlanmıştır.

  • powerAppsApiVersion: Power Apps için kullanılacak API sürümü. Parametre isteğe bağlıdır ve varsayılan olarak 2016-11-01 olarak ayarlanmıştır.

Komut satırı işlemleri

Oturum Açın

Aşağıdaki komutu çalıştırarak Power Platform'da oturum açın:

paconn login

Bu komut, cihaz kodu oturum açma işlemini kullanarak oturum açmanızı ister. Oturum açma isteğini izleyin. Şu anda Hizmet Sorumlusu kimlik doğrulaması için destek yok.

Oturumu kapatma

Çalışırken oturumu kapatma:

paconn logout

Özel bağlayıcı dosyalarını indirme

Bağlayıcı dosyalarını her zaman dizin adı olarak bağlayıcı kimliğini kullanarak bir alt dizine indirin. Bir hedef dizin belirttiğinizde, belirtilen dizinde bir alt dizin oluşturulur. Aksi halde geçerli dizinde oluşturulur. İndirme işlemi, üç bağlayıcı dosyaya ek olarak, dosyaları indirmek için kullanılan parametreleri içeren settings.json adlı dördüncü bir dosyayı da yazar.

Aşağıdaki komutu çalıştırarak özel bağlayıcı dosyalarını indirin:

paconn download

or

paconn download -e [Power Platform Environment GUID] -c [Connector ID]

or

paconn download -s [Path to settings.json]

Ortam veya bağlayıcı kimliği belirtilmediğinde, komut eksik bağımsız değişkenleri ister. Komut, bağlayıcı başarıyla indirilirse indirme konumunu çıkış olarak verir.

Tüm bağımsız değişkenler settings.json dosyası kullanılarak da belirtilebilir.

Arguments
   --cid -c       : The custom connector ID.
   --dest -d      : Destination directory.
   --env -e       : Power Platform environment GUID.
   --overwrite -w : Overwrite all the existing connector and settings files.
   --pau -u       : Power Platform URL.
   --pav -v       : Power Platform API version.
   --settings -s  : A settings file containing required parameters.
                    When a settings file is specified some command 
                    line parameters are ignored.

Yeni bir özel bağlayıcı oluşturma

create işlemini çalıştırarak bağlayıcı dosyalarından yeni bir özel bağlayıcı oluşturabilirsiniz. Şu komutu çalıştırarak bir bağlayıcı oluşturun:

paconn create --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json]

or

paconn create -e [Power Platform Environment GUID] --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json] --icon [Path to icon.png] --secret [The OAuth2 client secret for the connector]

or

paconn create -s [Path to settings.json] --secret [The OAuth2 client secret for the connector]

Ortamı belirtmediğinizde komut onu ister. Ancak API tanımını ve API özellik dosyasını komut satırı argümanının veya bir ayarlar dosyasının parçası olarak sağlamanız gerekir. OAuth2 kullanan bir bağlayıcı için OAuth2 sırrını sağlayın. Komut, başarıyla tamamlandığında yeni oluşturulan özel bağlayıcının bağlayıcı kimliğini yazdırır. Eğer create komutu için settings.json dosyasını kullanıyorsanız, yeni oluşturulan bağlayıcıyı güncellemeden önce onu yeni bağlayıcı kimliğiyle güncellediğinizden emin olun.

Arguments
   --api-def     : Location for the Open API definition JSON document.
   --api-prop    : Location for the API properties JSON document.
   --env -e      : Power Platform environment GUID.
   --icon        : Location for the icon file.
   --script -x   : Location for the script file.
   --pau -u      : Power Platform URL.
   --pav -v      : Power Platform API version.
   --secret -r   : The OAuth2 client secret for the connector.
   --settings -s : A settings file containing required parameters.
                   When a settings file is specified some command 
                   line parameters are ignored.

Mevcut bir özel bağlayıcıyı güncelleştirme

create işlemi gibi, update işlemini kullanarak mevcut özel bir bağlayıcıyı güncelleyebilirsiniz. Şu komutu çalıştırarak bağlayıcıyı güncelleştirin:

paconn update --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json]

or

paconn update -e [Power Platform Environment GUID] -c [Connector ID] --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json] --icon [Path to icon.png] --secret [The OAuth2 client secret for the connector]

or

paconn update -s [Path to settings.json] --secret [The OAuth2 client secret for the connector]

Ortam veya bağlayıcı kimliğini belirtmediğinizde, komut eksik argüman(lar)ı ister. Ancak API tanımını ve API özellik dosyasını komut satırı argümanının veya bir ayarlar dosyasının parçası olarak sağlamanız gerekir. OAuth2 kullanan bir bağlayıcı için OAuth2 sırrını sağlayın. Komut, başarıyla tamamlandığında güncelleştirilmiş bağlayıcı kimliğini yazdırır. Güncelleme komutu için settings.json dosyasını kullanıyorsanız, doğru ortamı ve bağlayıcı kimliğini belirttiğinizden emin olun.

Arguments
   --api-def     : Location for the Open API definition JSON document.
   --api-prop    : Location for the API properties JSON document.
   --cid -c      : The custom connector ID.
   --env -e      : Power Platform environment GUID.
   --icon        : Location for the icon file.
   --script -x   : Location for the script file.
   --pau -u      : Power Platform URL.
   --pav -v      : Power Platform API version.
   --secret -r   : The OAuth2 client secret for the connector.
   --settings -s : A settings file containing required parameters.
                   When a settings file is specified some command 
                   line parameters are ignored.

Swagger JSON'u doğrulama

Doğrulama işlemi bir Swagger dosyası alır ve önerilen tüm kurallara uyup uymadığını doğrular. Aşağıdakini çalıştırarak bir swagger dosyasını doğrulayın:

paconn validate --api-def [Path to apiDefinition.swagger.json]

or

paconn validate -s [Path to settings.json]

Komut, doğrulamanın sonucuna bağlı olarak hatayı, uyarıyı veya başarı iletisini yazdırır.

Arguments
   --api-def     : Location for the Open API definition JSON document.
   --pau -u      : Power Platform URL.
   --pav -v      : Power Platform API version.
   --settings -s : A settings file containing required parameters.
                   When a settings file is specified some command 
                   line parameters are ignored.

En iyi uygulama

Tüm özel bağlayıcıları indirin ve git'i veya başka herhangi bir kaynak denetim sistemini kullanarak dosyaları kaydedin. Yanlış bir güncelleştirme yapılması durumunda, güncelleştirme komutunu kaynak denetim 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.

Sınırlamalar

Proje, Copilot Studio, Power Automate ve Power Apps ortamlarında özel bir bağlayıcının oluşturulması, güncellenmesi ve indirilmesiyle sınırlıdır. Bir ortam belirtilmediğinde yalnızca Power Automate ortamını seçme seçeneğiniz vardır. Özel olmayan bir bağlayıcı için swagger dosyası döndürülmez.

Not

stackOwner özelliği ve API özellikleri dosyası

Şu anda, stackOwner özelliği API özellikleri dosyanızda varken Paconn kullanarak ortamınızda bağlayıcının yapılarını güncelleştirmenizi önleyen bir sınırlama vardır. Bunun için geçici bir çözüm olarak, bağlayıcı yapıtlarınızın iki sürümünü oluşturun:

  • stackOwner özelliğini içeren bir versiyon oluşturun ve sertifikasyona gönderin.
  • Kendi ortamınızda güncelleme yapabilmenizi sağlamak için stackOwner'i atlayan ikinci bir versiyon oluşturun.

Sınırlamayı kaldırmaya çalışıyoruz ve bu bölümü tamamlandıktan sonra güncelleştireceğiz.

Sorunlar ve geri bildirim bildirme

Araçla ilgili bir hatayla karşılaşırsanız, lütfen GitHub deposunun Sorunlar bölümünden sorunu bildirin.

Microsoft'un güvenlik açığı tanımına uyan bir güvenlik açığı bulduğunuzu düşünüyorsanız MSRC’ye rapor gönderin. Daha fazla bilgiyi MSRC raporlama hakkında sık sorulan sorular bölümünde bulabilirsiniz.

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