Microsoft Power Platform Bağlayıcı CLI'ları

Makale
08/31/2021
Okumak için 6 dakika

Not

Bu sürüm notlarında henüz kullanıma sunulmamış olabilecek işlevler açıklanır. Bu işlevlerin planlanan kullanıma sunulma tarihini görmek için Common Data Model ve Veri Tümleştirme'deki yenilikler ve eklenmesi planlanan özellikler makalesine bakın. Teslim zaman çizelgeleri ve öngörülen işlevler değiştirilebilir veya gönderilmeyebilir (bkz. Microsoft ilkesi).

paconn komut satırı aracı, Microsoft Power Platform özel bağlayıcılarını geliştirmeye yardımcı olmak için tasarlanmıştır.

Yükleniyor

Python 3.5+ sürümünü https://www.python.org/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.
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.
Şu komutu çalıştırarak PATH değişkeninde yükleme yolunun bulunduğundan emin olun:

python --version
Python yüklendikten sonra şu komutu çalıştırarak paconn aracını yükleyin:

pip install paconn

Özel Bağlayıcı Dizini ve Dosyaları

Özel bağlayıcı üç dosyadan oluşur: Bağlayıcının simgesi, Open API swagger tanımı ve API özellikleri dosyası. Dosyalar genellikle adı bağlayıcı kimliğiyle aynı olan bir dizinde yer alır.

Bazen özel bağlayıcı dizini bir settings.json dosyası içerebilir. Bu dosya, bağlayıcı tanımının bir parçası olmasa da CLI için bağımsız değişken deposu olarak kullanılabilir.

API Tanımı (Swagger) Dosyası

API tanımı dosyası, OpenAPI belirtimini kullanan özel bağlayıcı için API'yi tanımlar. Bu dosya swagger dosyası olarak da bilinir. Özel bağlayıcı yazmak için kullanılan API tanımları hakkında daha fazla bilgiyi konuyla ilgili bağlayıcı belgelerinde bulabilirsiniz. Ayrıca OpenApi tanımını genişletme hakkındaki öğreticiyi de gözden geçirin.

API Özellikleri Dosyası

API özellikleri dosyası, özel bağlayıcıya yönelik bazı özellikler içerir. Bu özellikler API tanımının bir parçası değildir. Marka rengi ya da kimlik doğrulama bilgileri gibi ayrıntıları 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",
    "policyTemplateInstances": [
      {
        "title": "MyPolicy",
        "templateId": "setqueryparameter",
        "parameters": {
            "x-ms-apimTemplateParameter.name": "queryParameterName",
            "x-ms-apimTemplateParameter.value": "queryParameterValue",
            "x-ms-apimTemplateParameter.existsAction": "override"
        }
      }
    ]    
  }
}

Aşağıda özelliklerin her biriyle ilgili ek bilgiler verilmiştir:

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.
capabilities: Bağlayıcının özelliklerini (örneğin, yalnızca bulut, şirket içi ağ geçidi vb.) açıklar.
policyTemplateInstances: Özel bağlayıcıda kullanılan 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.

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. Normal bir settings.json dosyası aşağıdaki örneğe benzer:

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

Ayarlar dosyasında aşağıdaki öğelerin bulunması beklenir. Bir seçenek eksikse ama gerekliyse, konsol eksik bilgileri isteyecektir.

connectorId: Özel bağlayıcı için bağlayıcı kimliği dizesi. Bu parametre, indirme ve güncelleştirme işlemleri için gereklidir ama oluşturma işlemi için gerekli değildir çünkü oluşturma işleminde yeni kimlikle yeni bir özel bağlayıcı oluşturulur. Aynı ayarlar dosyasını kullanılarak yeni oluşturulmuş bir özel bağlayıcıyı güncelleştirmeniz gerekiyorsa, ayarlar dosyasının oluşturma işlemindeki yeni bağlayıcı kimliğiyle düzgün bir şekilde güncelleştirildiğinden emin olun.
environment: Özel bağlayıcı için ortam kimliği dizesi. Bu parametre üç işlem için de gereklidir.
apiProperties: API özellikleri apiProperties.json dosyasının yolu. Oluşturma ve güncelleştirme işlemleri için gereklidir. İndirme sırasında bu seçenek sağlandığında, dosya verilen konuma indirilir.
apiDefinition: Swagger dosyasının yolu. Oluşturma ve güncelleştirme işlemleri için gereklidir. İndirme sırasında bu seçenek sağlandığında, verilen konumda yer alan dosyaya yazılır.
icon: Simge dosyasının yolu. Oluşturma ve güncelleştirme işlemleri için gereklidir. İndirme sırasında bu seçenek sağlandığında, verilen konumda yer alan dosyaya yazılır.
powerAppsApiVersion: Power Apps için kullanılacak API sürümü. Bu öğe isteğe bağlıdır ve varsayılan olarak 2016-11-01 değerine ayarlanır.
powerAppsUrl: Power Apps için API URL'si. Bu öğe isteğe bağlıdır ve varsayılan olarak https://preview.api.powerapps.com değerine ayarlanır.

Komut Satırı İşlemleri

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ı isteyecektir. Oturum açma isteğini izleyin.

Özel Bağlayıcı Dosyalarını İndirme

Bağlayıcı dosyaları her zaman dizin adı olarak bağlayıcı kimliğini kullanan bir alt dizine indirilir. Hedef dizin belirtildiğinde, alt dizin bu belirtilen dizinde oluşturulur. Aksi durumda, geçerli dizinde oluşturulur. Üç bağlayıcı dosyasına ek olarak, indirme işlemi dosyaları indirirken kullanılan parametreleri içeren settings.json adlı dördüncü bir dosya yazar.

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

paconn download

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

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

Daha önce tanıtılan üç dosyadan yeni bir özel bağlayıcı oluşturulabilir. Ş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] --icon [Path to icon.png]

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]

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

Ortam belirtilmediğinde komut bunun belirtilmesini ister. Ancak API tanımı, API özellikleri ve simge dosyası, komut satırı bağımsız değişkeninin veya bir ayarlar dosyasının parçası olarak sağlanmalıdır. OAuth2 kullanan bağlayıcılar için OAuth2 gizli dizisi sağlanmalıdır. Komut, başarıyla tamamlandığında yeni oluşturulan özel bağlayıcının bağlayıcı kimliğini yazdırır. Oluşturma komutu için bir settings.json dosyası kullanıyorsanız, yeni oluşturulan bağlayıcıyı güncelleştirmeden önce bu dosyayı yeni bağlayıcı kimliğiyle güncelleştirdiğinizden emin olun.

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

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.
   --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şleminde olduğu gibi, mevcut özel bağlayıcı da daha önce tanıtılan üç dosyadan güncelleştirilebilir. Ş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] --icon [Path to icon.png]

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]

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

Ortam veya bağlayıcı kimliği belirtilmediğinde, komut eksik bağımsız değişkenleri ister. Ancak API tanımı, API özellikleri ve simge dosyası, komut satırı bağımsız değişkeninin veya bir ayarlar dosyasının parçası olarak sağlanmalıdır. OAuth2 kullanan bağlayıcılar için OAuth2 gizli dizisi sağlanmalıdır. Komut, başarıyla tamamlandığında güncelleştirilmiş bağlayıcı kimliğini yazdırır. Güncelleştirme komutu için bir settings.json dosyası kullanıyorsanız doğru ortamın ve bağlayıcı kimliğinin belirtildiğinden emin olun.

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

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

En İyi 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 Power Automate ve Power Apps ortamında özel bağlayıcıyı oluşturma, güncelleştirme ve indirme işlemleriyle sınırlıdır. Ortam belirtilmediğinde, aralarından seçim yapabilmeniz için yalnızca Power Automate ortamları listelenir. Özel olmayan bir bağlayıcı için swagger dosyası döndürülmez.

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.

Microsoft Power Platform Bağlayıcı CLI'ları

Lütfen deneyiminizi değerlendirin

Yükleniyor

Özel Bağlayıcı Dizini ve Dosyaları

API Tanımı (Swagger) Dosyası

API Özellikleri Dosyası

Simge Dosyası

Ayarlar Dosyası

Komut Satırı İşlemleri

Oturum Açın

Özel Bağlayıcı Dosyalarını İndirme

Yeni Bir Özel Bağlayıcı Oluşturma

Mevcut Bir Özel Bağlayıcıyı Güncelleştirme

En İyi Uygulama

Sınırlamalar

Sorunlar ve geri bildirim bildirme