Tworzenie łącznika niestandardowego za pomocą CLI

Artykuł
04/24/2024

Narzędzie wiersza polecenia paconn zostało zaprojektowane w celu ułatwienia opracowywania łączników niestandardowych Microsoft Power Platform.

Uwaga

W tych informacjach o wersji opisano funkcje, które mogły nie zostać jeszcze zaimplementowane.
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 w wersji nowszej niż 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: definicji Open API swagger, pliku właściwości API, opcjonalnej ikony łącznika oraz opcjonalnego pliku skryptu csharp. Pliki znajdują się zwykle 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. Jest on również znany jako plik struktury Swagger. Więcej informacji o definicjach API używanych do pisania własnych łączników znajdziesz w rozdziale 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 niektóre właściwości łącznika niestandardowego. Te właściwości nie są częścią definicji interfejsu API. W tym pliku znajdują się informacje takie jak kolor marki, informacje 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"
        }
      }
    ]    
  }
}

Poniżej przedstawiono więcej informacji na temat każdej z właściwoś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: Opisuje możliwości łącznika, np. tylko w chmurze, brama lokalna itp.
policyTemplateInstances: Opcjonalna lista wystąpień i wartości szablonów zasad używanych w łączniku niestandardowym.

Plik ikony

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

Plik skryptu

Skrypt jest plikiem skryptu CSX, który 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"
}

W pliku ustawień powinny znajdować się następujące elementy. Jeśli brakuje wymaganej opcji, w konsoli zostanie wyświetlony monit o podanie brakujących informacji.

connectorId: Ciąg identyfikatora łącznika niestandardowego. Ten parametr jest wymagany dla operacji pobierania i aktualizacji, ale nie dla operacji tworzenia i zatwierdzania. Dla polecenia create zostanie utworzony nowy łącznik niestandardowy z nowym ID. 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 dla wszystkich operacji, z wyjątkiem operacji sprawdzania poprawności.
apiProperties: Ścieżka do pliku właściwości interfejsu API apiProperties.json. Ten parametr jest wymagany w przypadku operacji tworzenia i aktualizowania. Gdy ta opcja jest obecna podczas pobierania, plik zostanie pobrany do określonej lokalizacji, w przeciwnym razie zostanie zapisane jako apiProperties.json.
apiDefinition: Ścieżka do pliku struktury Swagger. Jest wymagana przy operacjach tworzenia, aktualizacji i zatwierdzania. Gdy ta opcja jest obecna podczas operacji pobierania, plik w podanej lokalizacji zostanie zapisany; w przeciwnym razie zostanie zapisany jako apiDefinition.swagger.json.
icon: Ścieżka do opcjonalnego pliku ikony. Operacje tworzenia i aktualizacji użyją domyślnej ikony, jeśli ten parametr nie zostanie określony. Gdy ta opcja jest obecna podczas operacji pobierania, plik w podanej lokalizacji zostanie zapisany; w przeciwnym razie 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. Gdy ta opcja jest obecna podczas operacji pobierania, plik w podanej lokalizacji zostanie zapisany; w przeciwnym razie 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 jest obsługiwane uwierzytelnianie głównej nazwy usługi.

Wyloguj

Wylogowanie z uruchomienia:

paconn logout

Pobieranie plików łączników niestandardowych

Pliki łącznika są zawsze pobierane do podkatalogu o nazwie takiej samej jak identyfikator łącznika. Jeśli zostanie podany katalog docelowy, podkatalog zostanie utworzony w tym 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]

lub

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]

lub

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

Jeśli nie zostanie określone środowisko, 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ń. Jeśli łącznik ma korzystać z uwierzytelniania OAuth2, należy również podać wpis tajny 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 umieścić w nim identyfikator nowego łącznika przed zaktualizowaniem nowo utworzonego łą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]

lub

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]

lub

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ń. Jeśli łącznik ma korzystać z uwierzytelniania OAuth2, należy również podać wpis tajny 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]

lub

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 środowisku Power Automate i Power Apps. Jeśli środowisko nie zostanie podane, wybór będzie ograniczony tylko do środowisk Power Automate. W przypadku łączników innych niż niestandardowe plik struktury Swagger nie jest zwracany.

Plik właściwości stackOwner i apiProperties

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 apiProperties.json. Aby obejść ten problem, utwórz dwie wersje artefaktów łącznika: Pierwsza to wersja, która jest przekazywana do certyfikacji i zawiera właściwość stackOwner. W drugim pominięto właściwość stackOwner, aby umożliwić aktualizację w twoim ś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.

Udostępnij za pośrednictwem

Tworzenie łącznika niestandardowego za pomocą CLI

Instaluj

Katalog i pliki łącznika niestandardowego

Plik definicji interfejsu API (Swagger)

Plik właściwości interfejsu API

Plik ikony

Plik skryptu

Plik ustawień

Operacje wiersza polecenia

Wyloguj

Pobieranie plików łączników niestandardowych

Tworzenie nowego łącznika niestandardowego

Aktualizowanie istniejącego łącznika niestandardowego

Walidacja Swagger JSON

Najlepsze rozwiązanie

Ograniczenia

Zgłaszanie problemów i opinii

Przekazywanie opinii

Dodatkowe zasoby

Udostępnij za pośrednictwem

Tworzenie łącznika niestandardowego za pomocą CLI

Instaluj

Katalog i pliki łącznika niestandardowego

Plik definicji interfejsu API (Swagger)

Plik właściwości interfejsu API

Plik ikony

Plik skryptu

Plik ustawień

Operacje wiersza polecenia

Logowanie

Wyloguj

Pobieranie plików łączników niestandardowych

Tworzenie nowego łącznika niestandardowego

Aktualizowanie istniejącego łącznika niestandardowego

Walidacja Swagger JSON

Najlepsze rozwiązanie

Ograniczenia

Zgłaszanie problemów i opinii

Przekazywanie opinii

Dodatkowe zasoby