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

Makale
04/24/2024

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

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

Yükle

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

"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 ile dört dosyadan oluşur: Open API Swagger tanımı, API özellikleri dosyası, bağlayıcı için isteğe bağlı bir simge ve isteğe bağlı bir csharp betik 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 bilgi için bkz. OpenAPI tanımından özel bağlayıcı oluşturma. 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ı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",
    "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"
        }
      }
    ]    
  }
}

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.
scriptOperations: Betik 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 ö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.

Betik dosyası

Betik dosyası, özel bağlayıcı için dağıtılan ve bağlayıcının işlemlerinin alt kümesine her çağrı için yürütülen bir CSX betik dosyasıdı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. 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",
  "script": "script.csx",
  "powerAppsApiVersion": "2016-11-01",
  "powerAppsUrl": "https://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 ancak oluşturma veya doğrulama işlemi için gerekmez. Oluştur komutu için yeni kimliğe sahip yeni bir özel bağlayıcı oluşturulacaktır. 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, doğrulama işlemi dışındaki tüm işlemler için 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; aksi durumda apiProperties.json olarak kaydedilir.
apiDefinition: Swagger dosyasının yolu. Oluşturma, güncelleştirme ve doğrulama işlemleri için gereklidir. İndirme işlemi sırasında bu seçenek sağlandığında, belirtilen konumdaki dosyaya yazılır; aksi durumda apiDefinition.swagger.json olarak kaydedilir.
icon: İsteğe bağlı simge dosyasının yolu. Oluşturma ve güncelleştirme işlemleri, bu parametre belirtilmediğinde varsayılan simgeyi kullanır. İndirme işlemi sırasında bu seçenek sağlandığında, belirtilen konumdaki dosyaya yazılır; aksi durumda 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 sağlandığında, belirtilen konumdaki dosyaya yazılır; aksi durumda 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

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. Bu aşamada Hizmet Sorumlusu kimlik doğrulaması desteklenmez.

Oturumu kapatma

Çalışırken oturumu kapatma:

paconn logout

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

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

Yeni bir özel bağlayıcı, create işlemi çalıştırılarak bağlayıcı dosyalarından 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]

veya

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]

veya

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

Ortam belirtilmediğinde komut bunun belirtilmesini ister. Öte yandan API tanımı ve API özellikleri 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.

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, mevcut bir özel bağlayıcı update işlemi kullanılarak 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]

veya

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]

veya

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. Öte yandan API tanımı ve API özellikleri 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.

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]

veya

paconn validate -s [Path to settings.json]

Komut, doğrulamanın sonucuna bağlı olarak hatayı, uyarıyı veya başarı iletisini yazdıracaktı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 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.

stackOwner özelliği ve apiProperties dosyası

Şu anda, stackOwner özelliği apiProperties.json 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 bir geçici çözümü olarak, bağlayıcı yapılarınızın iki sürümünü oluşturun: İlki, sertifikasyon için gönderilen sürümdür ve stackOwner özelliğini içerir. İkincisinde ortamınızda güncelleştirmeyi etkinleştirmek için stackOwner özelliği atlanmıştır. 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 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.

Aracılığıyla paylaş

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

Yükle

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

API tanımı (swagger) dosyası

API özellikleri dosyası

Simge dosyası

Betik dosyası

Ayarlar dosyası

Komut satırı işlemleri

Oturumu kapatma

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

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

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

Swagger JSON'u doğrulama

En iyi uygulama

Sınırlamalar

Sorunlar ve geri bildirim bildirme

Geri bildirimde bulunun

Ek kaynaklar

Aracılığıyla paylaş

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

Yükle

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

API tanımı (swagger) dosyası

API özellikleri dosyası

Simge dosyası

Betik dosyası

Ayarlar dosyası

Komut satırı işlemleri

Oturum Açın

Oturumu kapatma

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

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

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

Swagger JSON'u doğrulama

En iyi uygulama

Sınırlamalar

Sorunlar ve geri bildirim bildirme

Geri bildirimde bulunun

Ek kaynaklar