Tworzenie łącznika niestandardowego za pomocą CLI

paconn Narzędzie wiersza polecenia ułatwia tworzenie łączników niestandardowych dla Copilot Studio i platformy Power Platform.

Zainstaluj Python i paconn

1. Zainstaluj Pythona 3.5 lub nowszą wersję z witryny [https://www.python.org/downloads](Pobieranie Pythona). Wybierz link Pobierz dla dowolnej wersji Python wyższej niż Python 3.5. W przypadku systemów Linux i macOS postępuj zgodnie z odpowiednim linkiem na stronie. Możesz również zainstalować Python przy użyciu wybranego menedżera pakietów specyficznego dla systemu operacyjnego.

2. Uruchom instalatora, aby rozpocząć instalację i zaznacz pole wyboru Dodaj Python X.X do ŚCIEŻKI.

3. Upewnij się, że ścieżka instalacji znajduje się w zmiennej PATH , uruchamiając polecenie:

   python --version

4. Po zainstalowaniu Pythona zainstaluj paconn uruchamiając:

   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

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

• Definicja OpenAPI lub Swaggera
• plik właściwości API
• Opcjonalna ikona konektora
• opcjonalny plik skryptu języka C#

Pliki znajdziesz w katalogu, który używa identyfikatora łącznika jako nazwy.

Czasami katalog łącznika niestandardowego może zawierać plik settings.json. Mimo że ten plik nie jest częścią definicji łącznika, można go użyć jako magazynu argumentów dla CLI.

Plik definicji interfejsu API (Swagger)

Plik definicji interfejsu API opisuje interfejs API konektora niestandardowego przy użyciu specyfikacji interfejsu OpenAPI. Ta specyfikacja jest również znana jako plik Swagger. Aby uzyskać więcej informacji na temat tego, jak plik definicji interfejsu API pomaga tworzyć łącznik niestandardowy, zobacz Tworzenie łącznika niestandardowego na podstawie definicji interfejsu OpenAPI. Zapoznaj się również z samouczkiem w artykule Rozszerzanie definicji interfejsu OpenAPI dla łącznika niestandardowego .

Plik właściwości interfejsu API

Plik właściwości interfejsu API zawiera właściwości łącznika niestandardowego, które nie są częścią definicji interfejsu API. Zawiera informacje, takie jak kolor marki i informacje o uwierzytelnianiu. 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 właściwości:

• properties: Kontener informacji.

• connectionParameters: Definiuje parametr połączenia dla usługi.

• iconBrandColor: Kolor marki ikony w kodzie szesnastkowym HTML dla niestandardowego łącznika.

• scriptOperations: Lista operacji wykonywanych przy użyciu pliku skryptu. Pusta scriptOperations lista wskazuje, że wszystkie operacje są wykonywane za pomocą pliku skryptu.

• capabilities: Opis możliwości łącznika, takich jak działanie tylko w chmurze i brama lokalna.

• policyTemplateInstances: Opcjonalna lista instancji szablonów zasad i wartości, których używa 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 każdej operacji z podzbioru operacji łącznika.

Plik ustawień

Zamiast podawać argumenty w wierszu polecenia, użyj pliku settings.json, aby je określić. 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"
}

Możesz znaleźć te elementy 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 pobierania i aktualizacji wymagają parametru identyfikatora łącznika, a operacje tworzenia i walidacji nie wymagają. Polecenie create tworzy nowy łącznik niestandardowy z nowym identyfikatorem. Jeśli musisz zaktualizować istniejący łącznik niestandardowy przy użyciu tego samego pliku ustawień, upewnij się, że plik ustawień został zaktualizowany przy użyciu nowego identyfikatora łącznika na podstawie 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 Aktualizuj wymagają pliku właściwości API. Jeśli ta opcja jest zaznaczona podczas pobierania, plik zostanie pobrany do swojej docelowej lokalizacji; w przeciwnym razie plik zostanie zapisany jako apiProperties.json.

• apiDefinition: Ścieżka do pliku Swagger. Operacje Utwórz, Aktualizuj i Weryfikuj wymagają pliku definicji API. Jeśli ta opcja jest zaznaczona podczas pobierania, plik zostanie pobrany w oryginalnej lokalizacji; w przeciwnym razie plik zostanie zapisany jako apiDefinition.swagger.json.

• icon: Ścieżka do opcjonalnego pliku ikony. Jeśli nie ma specyfikacji tego parametru, operacje tworzenia i aktualizacji używają ikony domyślnej. Jeśli ta opcja jest zaznaczona podczas pobierania, plik zostanie pobrany w 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 w określonym parametrze. Jeśli ta opcja jest obecna podczas pobierania, plik zostanie pobrany do tej 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ę

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

paconn login

To polecenie wyświetla monit o zalogowanie się przy użyciu procesu uwierzytelniania kodu urządzenia. Postępuj zgodnie z komunikatem uwierzytelniania. To polecenie nie obsługuje uwierzytelniania nazwy głównej usługi.

Wyloguj się

Wyloguj się, uruchamiając polecenie:

paconn logout

Pobierz pliki niestandardowych łączników

Pliki łącznika należy zawsze pobierać do podkatalogu o nazwie zgodnej z identyfikatorem łącznika. Po określeniu katalogu docelowego ten katalog staje się katalogiem nadrzędnym dla nowego podkatalogu. Jeśli nie określisz katalogu docelowego, podkatalog zostanie utworzony w bieżącym katalogu. Oprócz trzech plików łącznika operacja pobierania tworzy czwarty plik o nazwie settings.json zawierający parametry używane do pobierania plików.

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

paconn download

or

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

or

paconn download -s [Path to settings.json]

Jeśli nie określisz identyfikatora środowiska lub łącznika, polecenie wyświetli monit o brakujące argumenty. Jeśli pobieranie zakończy się pomyślnie, polecenie wyświetli lokalizację pobierania konektora.

Można również określić wszystkie argumenty 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.

Utwórz nowy łącznik niestandardowy

Nowy niestandardowy łącznik można utworzyć na podstawie plików łącznika, uruchamiają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]

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]

Jeśli nie określisz środowiska, polecenie wyświetli monit o jego podanie. Jednak musisz podać definicję API i plik właściwości interfejsu API jako część argumentu wiersza poleceń lub pliku ustawień. Podaj sekret OAuth2 dla łącznika przy użyciu protokołu OAuth2. Po pomyślnym zakończeniu polecenie wyświetli identyfikator nowo utworzonego łącznika niestandardowego. Jeśli używasz nowego pliku settings.json dla polecenia create, upewnij się, że zaktualizujesz go nowym identyfikatorem łą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 konektora niestandardowego

Podobnie jak w operacji create, możesz zaktualizować istniejący łącznik niestandardowy przy użyciu 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]

or

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

Jeśli środowiska lub identyfikatora łą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 klucz tajny OAuth2 dla łącznika przy użyciu protokołu 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ślisz prawidłowe środowisko i identyfikator łą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.

Zweryfikuj plik Swagger JSON

Operacja validate przyjmuje plik Swagger i sprawdza, czy jest zgodny ze wszystkimi zalecanymi regułami. Zweryfikuj plik swagger, uruchamiając:

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

or

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.

Dobra praktyka

Pobierz wszystkie konektory niestandardowe i użyj narzędzia Git lub dowolnego innego systemu kontroli źródła, aby zapisać pliki. 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 identyfikator środowiska i łącznika są poprawne.

Ograniczenia

Interfejs paconn wiersza polecenia jest ograniczony do tworzenia, aktualizowania i pobierania łącznika niestandardowego w środowiskach Copilot Studio, Power Automate i Power Apps. Jeśli nie określisz środowiska, możesz wybrać tylko środowisko Power Automate. W przypadku łącznika innego niż niestandardowy plik struktury Swagger nie jest zwracany.

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.

Jeśli uważasz, że znalazłeś lukę w zabezpieczeniach, która spełnia definicję luki w zabezpieczeniach firmy Microsoft, prześlij raport do MSRC. Aby uzyskać więcej informacji, zobacz MSRC — często zadawane pytania dotyczące raportowania.

Przekaż opinię

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