Tworzenie łącznika niestandardowego za pomocą CLI

Narzędzie wiersza poleceń paconn zostało zaprojektowane, aby pomóc w tworzeniu niestandardowych łączników dla Copilot Studio i Power Platform.

Notatka

Ta funkcja może nie być jeszcze dostępna.
Aby się dowiedzieć, kiedy jest planowane zaimplementowanie danej funkcji, zobacz Nowe i planowane funkcje usług Common Data Model i Data Integration.
Terminy dostaw i przewidywane funkcje mogą ulec zmianie lub mogą nie zostać dostarczone (przejdź do zasady firmy Microsoft).

Instaluj

Zainstaluj środowisko Python 3.5+ z witryny [https://www.python.org/downloads](Python downloads). Wybierz link Pobierz odnoszący się do dowolnej wersji środowiska Python nowszej niż Python 3.5. W przypadku systemów Linux i Mac OS X użyj odpowiedniego linku na stronie. Instalację można także przeprowadzić za pomocą wybranego przez siebie menedżera pakietów systemu operacyjnego.
Uruchom instalatora, aby rozpocząć instalację. Upewnij się, że jest zaznaczone pole wyboru Add Python X.X to PATH (Dodaj środowisko Python X.X do zmiennej PATH).
Upewnij się, że ścieżka instalacji znajduje się w zmiennej PATH, uruchamiając następujące polecenie:

python --version
Po zainstalowaniu środowiska Python zainstaluj narzędzie paconn, uruchamiając poniższe polecenie:

pip install paconn

Jeśli pojawiają się błędy z napisem Odmowa dostępu, rozważ użycie opcji --user lub uruchomienie polecenia jako administrator (Windows).

Katalog i pliki łącznika niestandardowego

Niestandardowy łącznik składa się z dwóch do czterech plików:

otwarta definicja API/swagger
plik właściwości API
Opcjonalna ikona łącznika
Opcjonalny plik skryptu csharp

Pliki znajdują się w katalogu, którego nazwa brzmi tak samo jak identyfikator łącznika.

Czasami katalog łącznika niestandardowego może zawierać plik settings.json. Chociaż ten plik nie jest częścią definicji łącznika, może być używany jako magazyn argumentów dla interfejsu wiersza polecenia.

Plik definicji interfejsu API (Swagger)

Plik definicji interfejsu API opisuje interfejs API łącznika niestandardowego przy użyciu specyfikacji OpenAPI, znany również jako plik swagger. Aby uzyskać więcej informacji na temat tego, w jaki sposób plik definicji API pomaga w tworzeniu niestandardowych łączników, znajdziesz w temacie Tworzenie własnego łącznika z definicji OpenAPI. Zapoznaj się także z samouczkiem w artykule Rozszerzenie definicji OpenAPI dla niestandardowego łącznika.

Plik właściwości interfejsu API

Plik właściwości interfejsu API zawiera pewne właściwości łącznika niestandardowego, które nie są częścią definicji interfejsu API. Plik właściwości API zawiera informacje takie jak kolor marki, informacje dotyczące uwierzytelniania itp. Typowy plik właściwości interfejsu API wygląda podobnie jak w przykładzie:

{
  "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"
        }
      }
    ]    
  }
}

Oto więcej informacji na temat każdej z nieruchomości:

properties: Kontener informacji.
connectionParameters: Definiuje parametr połączenia dla usługi.
iconBrandColor: Kolor marki ikony w kodzie szesnastkowym HTML dla łącznika niestandardowego.
scriptOperations: Lista operacji wykonywanych przy użyciu pliku skryptu. Pusta lista Operacje skryptów oznacza, że wszystkie operacje są wykonywane za pomocą pliku skryptu.
capabilities: Opis możliwości łącznika. Na przykład brama działająca wyłącznie w chmurze i brama lokalna.
policyTemplateInstances: Opcjonalna lista instancji szablonów zasad i wartości używanych przez niestandardowy łącznik.

Plik ikony

Plik ikony to mały obraz reprezentujący ikonę łącznika niestandardowego.

Plik skryptu

Plik skryptu Visual C# Script (CSX) jest wdrażany dla łącznika niestandardowego i wykonywany przy każdym wywołaniu podzbioru operacji łącznika.

Plik ustawień

Zamiast podawania argumentów w wierszu polecenia można je określić przy użyciu pliku settings.json. Typowy plik settings.json wygląda podobnie jak w przykładzie:

{
  "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"
}

Spodziewaj się tych elementów w pliku ustawień. Jeśli brakuje wymaganej opcji, w konsoli zostanie wyświetlony monit o podanie brakujących informacji.

connectorId: Ciąg identyfikatora łącznika niestandardowego. Operacje Pobierz i Aktualizuj wymagają podania parametru identyfikatora łącznika, natomiast operacje Utwórz i Zatwierdź nie wymagają tego parametru. Polecenie Utwórz tworzy nowy niestandardowy łącznik z nowym identyfikatorem. Jeśli występuje potrzeba zaktualizowania łącznika niestandardowego, który właśnie został utworzony, przy użyciu tego samego pliku ustawień, należy się upewnić, że plik ustawień został poprawnie zaktualizowany z uwzględnieniem nowego identyfikatora łącznika z operacji tworzenia.
environment: Ciąg identyfikatora środowiska dla łącznika niestandardowego. Ten parametr jest wymagany we wszystkich operacjach z wyjątkiem operacji weryfikacji.
apiProperties: Ścieżka do pliku właściwości interfejsu API. Operacje Utwórz i Zatwierdź wymagają pliku właściwości API. Jeśli ta opcja jest zaznaczona podczas pobierania, plik zostanie pobrany do swojej lokalizacji; w przeciwnym razie plik zostanie zapisany jako apiProperties.json.
apiDefinition: Ścieżka do pliku struktury Swagger. Operacje Utwórz, Aktualizuj i Zatwierdź wymagają pliku definicji API. Jeśli ta opcja jest zaznaczona podczas pobierania, plik zostanie pobrany do swojej lokalizacji; w przeciwnym razie plik zostanie zapisany jako apiDefinition.swagger.json.
icon: Ścieżka do opcjonalnego pliku ikony. Jeśli nie ma specyfikacji dla tego parametru, operacje Utwórz i Aktualizuj używają domyślnej ikony. Jeśli ta opcja jest zaznaczona podczas pobierania, plik zostanie pobrany do swojej lokalizacji; w przeciwnym razie plik zostanie zapisany jako icon.png.
script: Ścieżka do opcjonalnego pliku skryptu. Operacje tworzenia i aktualizacji używają tylko wartości zawartych w określonym parametrze. Jeśli ta opcja jest zaznaczona podczas pobierania, plik zostanie pobrany do swojej lokalizacji; w przeciwnym razie plik zostanie zapisany jako script.csx.
powerAppsUrl: Adres URL interfejsu API dla usługi Power Apps. Ten parametr jest opcjonalny i domyślnie ustawiony na https://api.powerapps.com.
powerAppsApiVersion: Wersja interfejsu API, która ma być używana dla usługi Power Apps. Ten parametr jest opcjonalny i domyślnie ustawiony na 2016-11-01.

Operacje wiersza polecenia

Zaloguj się do Power Platform, uruchamiając polecenie:

paconn login

Spowoduje to wyświetlenie żądania zalogowania się przy użyciu kodu urządzenia. W czasie logowania postępuj zgodnie z wyświetlanymi instrukcjami. W tej chwili nie ma obsługi uwierzytelniania opartego na zasadach usługi.

Wyloguj

Wylogowanie z uruchomienia:

paconn logout

Pobieranie plików łączników niestandardowych

Pliki łącznika należy zawsze pobierać do podkatalogu o nazwie zgodnej z identyfikatorem łącznika. Po określeniu katalogu docelowego zostanie utworzony podkatalog w określonym katalogu. W przeciwnym razie zostanie on utworzony w bieżącym katalogu. Oprócz zapisania tych trzech plików łącznika operacja pobierania spowoduje również zapisanie czwartego pliku o nazwie settings.json zawierającego parametry użyte do pobrania plików.

Pobierz pliki łącznika niestandardowego, uruchamiając polecenie:

paconn download

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

paconn download -s [Path to settings.json]

Jeśli identyfikator środowiska lub łącznika nie zostanie podany, polecenie wyświetli monit o brakujące argumenty. Jeśli pobieranie zakończy się powodzeniem, polecenie wyświetli lokalizację, do której został pobrany łącznik.

Wszystkie argumenty można również określić przy użyciu pliku settings.json.

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.

Tworzenie nowego łącznika niestandardowego

Nowe złącze niestandardowe można utworzyć z plików złączy, wykonując operację create. Utwórz łącznik, uruchamiając następujące polecenie:

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

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]

Jeśli nie określisz środowiska, polecenie wyświetli monit o jego podanie. Definicja API i plik właściwości API muszą być jednak dostarczone jako część argumentu wiersza poleceń lub pliku ustawień. Podaj sekret OAuth2 dla łącznika korzystającego z OAuth2. Po pomyślnym zakończeniu polecenie wyświetli identyfikator nowo utworzonego łącznika niestandardowego. Jeśli na potrzeby polecenia tworzenia używasz pliku settings.json, pamiętaj, aby przed zaktualizowaniem nowo utworzonego łącznika umieścić w tym pliku identyfikator nowego łącznika.

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.

Aktualizowanie istniejącego łącznika niestandardowego

Podobnie jak w przypadku operacji create, istniejące złącze niestandardowe można zaktualizować za pomocą operacji update. Zaktualizuj łącznik, uruchamiając następujące polecenie:

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

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]

Jeśli identyfikator środowiska lub łącznika nie zostanie podany, polecenie wyświetli monit o brakujące argumenty. Definicja API i plik właściwości API muszą być jednak dostarczone jako część argumentu wiersza poleceń lub pliku ustawień. Podaj sekret OAuth2 dla łącznika korzystającego z OAuth2. Po pomyślnym zakończeniu polecenie wyświetli zaktualizowany identyfikator łącznika. Jeśli używasz pliku settings.json dla polecenia aktualizacji, upewnij się, że określono w nim poprawne identyfikatory środowiska i łącznika.

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.

Walidacja Swagger JSON

Operacja sprawdzania poprawności bierze plik swagger i sprawdza, czy spełnia on wszystkie zalecane reguły. Sprawdź poprawność pliku swagger , uruchamiając:

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

paconn validate -s [Path to settings.json]

Polecenie wydrukuje komunikat o błędzie, ostrzeżeniu lub sukcesie w zależności od wyniku walidacji.

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.

Najlepsze rozwiązanie

Pobierz wszystkie łączniki niestandardowe i zapisz ich pliki przy użyciu narzędzia Git lub innego systemu kontroli źródła. W przypadku nieprawidłowej aktualizacji ponownie wdróż łącznik przez ponowne uruchomienie polecenia aktualizacji z prawidłowym zestawem plików z systemu kontroli źródła.

Przetestuj łącznik niestandardowy i plik ustawień w środowisku testowym przed ich wdrożeniem w środowisku produkcyjnym. Zawsze pamiętaj o sprawdzeniu, czy identyfikatory środowiska i łącznika są poprawne.

Ograniczenia

Ten projekt jest ograniczony do tworzenia, aktualizowania i pobierania łącznika niestandardowego w środowiskach Copilot Studio, Power Automate i Power Apps. Jeśli środowisko nie jest określone, możesz wybrać tylko środowisko Power Automate. W przypadku łączników innych niż niestandardowe plik struktury Swagger nie jest zwracany.

Notatka

Właściwość stackOwner i plik właściwości API

Obecnie istnieje ograniczenie, które uniemożliwia aktualizację artefaktów łącznika w środowisku za pomocą Paconn, gdy właściwość stackOwner jest obecna w pliku Właściwości API. Aby obejść ten problem, utwórz dwie wersje artefaktów łącznika:

Utwórz jedną wersję zawierającą właściwość stackOwner i prześlij ją do certyfikacji.
Utwórz drugą wersję, pomijając stackOwner, aby umożliwić wprowadzanie aktualizacji we własnym środowisku.

Pracujemy nad usunięciem tego ograniczenia i po zakończeniu prac zaktualizujemy tę sekcję.

Zgłaszanie problemów i opinii

Jeśli występują jakiekolwiek problemy związane z narzędziem, prześlij zgłoszenie do sekcji Problemy repozytorium GitHub.

W przypadku wykrycia luki w zabezpieczeniach, która spełnia wymogi definicji luki w zabezpieczeniach firmy Microsoft, prześlij raport do centrum MSRC. Więcej informacji można znaleźć w artykule Często zadawane pytania dotyczące raportowania w centrum MSRC.

Przekazywanie opinii

Jesteśmy wdzięczni za opinie na temat problemów z platformą łączników oraz pomysły na nowe funkcje. Aby przekazać opinię, przejdź na stronę Przesyłanie problemów lub uzyskiwanie pomocy dotyczącej łączników i wybierz typ opinii.

Last updated on 2025-06-24

Udostępnij przez