Microsoft Power Platform커넥터 CLI

  • 아티클

참고

이러한 릴리스 정보에서는 아직 릴리스되지 않았을 수 있는 기능을 설명합니다. 이 기능의 출시 시기를 확인하려면 Common Data Model 및 데이터 통합의 새로운 기능 및 예정된 기능으로 이동하십시오. 배달 타임라인 및 예정된 기능이 변경되거나 제공되지 않을 수도 있습니다(Microsoft 정책 참고).

paconn 명령줄 도구는 Microsoft Power Platform 사용자 지정 커넥터의 개발을 지원하도록 설계되었습니다.

설치 중

  1. [https://www.python.org/downloads](Python downloads)에서 Python 3.5 이상을 설치합니다. Python 3.5보다 높은 모든 버전의 Python에서 다운로드 링크를 선택합니다. Linux 및 macOS X의 경우 페이지의 해당 링크를 따르세요. 선택한 OS 특정 패키지 관리자를 사용하여 설치할 수도 있습니다.

  2. 설치 관리자를 실행하여 설치를 시작하고 'PATH에 Python X.X 추가' 확인란을 선택해야 합니다.

  3. 다음을 실행하여 설치 경로가 PATH 변수에 있는지 확인합니다.

    python --version

  4. Python이 설치되면 다음을 실행하여 paconn을 설치합니다.

    pip install paconn

    '액세스가 거부되었습니다'라는 오류가 발생하면 --user 옵션을 사용하거나 관리자(Windows)로 명령을 실행하는 것이 좋습니다.

사용자 지정 커넥터 디렉터리 및 파일

사용자 지정 커넥터는 Open API swagger 정의, API 속성 파일, 커넥터에 대한 선택적 아이콘 및 선택적 csharp 스크립트 파일과 같은 2-4개의 파일로 구성됩니다. 파일은 일반적으로 커넥터 ID가 디렉터리 이름으로 있는 디렉터리에 있습니다.

경우에 따라 사용자 지정 커넥터 디렉터리에 settings.json 파일이 포함될 수 있습니다. 이 파일은 커넥터 정의의 일부가 아니지만 CLI의 인수 저장소로 사용할 수 있습니다.

API 정의(Swagger) 파일

API 정의 파일은 OpenAPI 사양을 사용하는 사용자 지정 커넥터에 대한 API를 설명합니다. Swagger 파일이라고도 합니다. 사용자 지정 커넥터를 작성하는 데 사용되는 API 정의에 대한 자세한 내용은 OpenAPI 정의에서 사용자 지정 커넥터 만들기를 참고하십시오. 또한 사용자 지정 커넥터에 대한 OpenAPI 정의 확장 문서의 자습서를 검토하십시오.

API 속성 파일

API 속성 파일에는 사용자 지정 커넥터에 대한 일부 속성이 포함되어 있습니다. 이러한 속성은 API 정의의 일부가 아닙니다. 브랜드 색, 인증 정보 등의 정보가 포함되어 있습니다. 일반적인 API 속성 파일은 다음 샘플과 같습니다.

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

각 속성에 대한 자세한 내용은 아래에 나와 있습니다.

  • properties: 정보의 컨테이너입니다.

  • connectionParameters: 서비스에 대한 연결 매개 변수를 정의합니다.

  • iconBrandColor: 사용자 지정 커넥터에 대한 HTML 16진수 코드의 아이콘 브랜드 색입니다.

  • scriptOperations: 스크립트 파일로 실행되는 작업의 목록입니다. 빈 scriptOperations 목록은 모든 작업이 스크립트 파일로 실행됨을 나타냅니다.

  • capabilities: 커넥터의 기능(예: 클라우드 전용, 온-프레미스 게이트웨이 등)을 설명합니다.

  • policyTemplateInstances: 사용자 지정 커넥터에 사용되는 정책 템플릿 인스턴스 및 값의 선택적 목록입니다.

아이콘 파일

아이콘 파일은 사용자 지정 커넥터 아이콘을 나타내는 작은 이미지입니다.

스크립트 파일

스크립트는 사용자 지정 커넥터에 대해 배포되고 커넥터 작업의 하위 집합에 대한 모든 호출에 대해 실행되는 CSX 스크립트 파일입니다.

설정 파일

명령줄에서 인수를 제공하는 대신 settings.json 파일을 사용하여 인수를 지정할 수 있습니다. 일반적인 settings.json 파일은 다음 샘플과 같습니다.

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

설정 파일에 필요한 항목은 다음과 같습니다. 옵션이 누락되었지만 필요한 경우 콘솔에서 누락된 정보를 입력하라는 메시지가 표시됩니다.

  • connectorId: 사용자 지정 커넥터의 커넥터 ID 문자열입니다. 이 매개 변수는 다운로드 및 업데이트 작업에 필요하지만 생성 또는 유효성 검사 작업에는 필요하지 않습니다. 생성 명령에 대해 새 ID를 가진 새 사용자 지정 커넥터가 생성됩니다. 동일한 설정 파일을 사용하여 방금 만든 사용자 지정 커넥터를 업데이트해야 하는 경우 만들기 작업에서 설정 파일이 새 커넥터 ID로 올바르게 업데이트되었는지 확인합니다.

  • environment: 사용자 지정 커넥터의 환경 ID 문자열입니다. 이 매개 변수는 유효성 검증 작업을 제외한 모든 작업에 필요합니다.

  • apiProperties: API 속성 apiProperties.json 파일의 경로입니다. 만들기 및 업데이트 작업에 필요합니다. 다운로드 중에 이 옵션이 있으면 파일이 지정된 위치에 다운로드되며 그렇지 않으면 apiProperties.json로 저장됩니다.

  • apiDefinition: Swagger 파일의 경로입니다. 생성, 업데이트 및 유효성 검사 작업에 필요합니다. 다운로드 작업 중에 이 옵션이 있으면 지정된 위치의 파일이 기록되며 그렇지 않으면 apiDefinition.swagger.json로 저장됩니다.

  • icon: 선택적 아이콘 파일의 경로입니다. 생성 및 업데이트 작업은 이 매개 변수가 지정되지 않은 경우 기본 아이콘을 사용합니다. 다운로드 작업 중에 이 옵션이 있으면 지정된 위치의 파일이 기록되며 그렇지 않으면 icon.png로 저장됩니다.

  • script: 선택적 스크립트 파일의 경로입니다. 생성 및 업데이트 작업은 지정된 매개 변수 내의 값만 사용합니다. 다운로드 작업 중에 이 옵션이 있으면 지정된 위치의 파일이 기록되며 그렇지 않으면 script.csx로 저장됩니다.

  • powerAppsUrl: Power Apps의 API URL입니다. 이 매개 변수는 선택사항이며 기본적으로 https://api.powerapps.com로 설정됩니다.

  • powerAppsApiVersion: Power Apps에 사용할 API 버전입니다. 이 매개 변수는 선택사항이며 기본적으로 2016-11-01로 설정됩니다.

명령줄 작업

로그인

다음을 실행하여 Power Platform에 로그인합니다.

paconn login

이 명령에서 디바이스 코드 로그인 프로세스를 사용하여 로그인하라는 메시지가 표시됩니다. 로그인 메시지를 따르세요. 서비스 원칙 인증은 현재 지원되지 않습니다.

로그아웃

다음을 실행하여 로그아웃합니다.

paconn logout

사용자 지정 커넥터 파일 다운로드

커넥터 파일은 항상 커넥터 ID가 디렉터리 이름으로 있는 하위 디렉터리에 다운로드됩니다. 대상 디렉터리가 지정되면 하위 디렉터리가 지정된 디렉터리에 만들어집니다. 그렇지 않으면 현재 디렉터리에 만들어집니다. 다운로드 작업에서는 세 개의 커넥터 파일 외에도 파일을 다운로드하는 데 사용되는 매개 변수가 포함된 settings.json이라는 네 번째 파일이 작성됩니다.

다음을 실행하여 사용자 지정 커넥터 파일을 다운로드합니다.

paconn download

or

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

or

paconn download -s [Path to settings.json]

환경 또는 커넥터 ID가 지정되지 않으면 명령에서 누락된 인수를 요구하는 메시지를 표시합니다. 커넥터가 성공적으로 다운로드되면 이 명령에서 해당 커넥터의 다운로드 위치를 출력합니다.

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

새 사용자 지정 커넥터 만들기

create 작업을 실행하여 커넥터 파일에서 새 사용자 지정 커넥터를 만들 수 있습니다. 다음을 실행하여 커넥터를 만듭니다.

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]

환경이 지정되지 않으면 명령에서 이를 요구하는 메시지를 표시합니다. 그러나 API 정의 및 API 속성 파일은 명령줄 인수 또는 설정 파일의 일부로 제공되어야 합니다. OAuth2 암호는 OAuth2를 사용하는 커넥터에 제공되어야 합니다. 성공적으로 완료되면 명령에서 새로 만든 사용자 지정 커넥터의 커넥터 ID를 출력합니다. create 명령에 settings.json 파일을 사용하는 경우 먼저 settings.json을 새 커넥터 ID로 업데이트한 후에 새로 만든 커넥터를 업데이트합니다.

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.

기존 사용자 지정 커넥터 업데이트

create 작업과 마찬가지로 기존 사용자 지정 커넥터는 update 작업을 사용하여 업데이트할 수 있습니다. 다음을 실행하여 커넥터를 업데이트합니다.

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]

환경 또는 커넥터 ID가 지정되지 않으면 명령에서 누락된 인수를 요구하는 메시지를 표시합니다. 그러나 API 정의 및 API 속성 파일은 명령줄 인수 또는 설정 파일의 일부로 제공되어야 합니다. OAuth2 암호는 OAuth2를 사용하는 커넥터에 제공되어야 합니다. 성공적으로 완료되면 명령에서 업데이트된 커넥터 ID를 출력합니다. update 명령에 settings.json 파일을 사용하는 경우 올바른 환경 및 커넥터 ID가 지정되어 있는지 확인합니다.

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 유효성 검사

유효성 검사 작업은 swagger 파일을 가져와서 모든 권장 규칙을 따르는지 확인합니다. 다음을 실행하여 swagger 파일의 유효성을 검사합니다.

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

또는

paconn validate -s [Path to settings.json]

이 명령은 유효성 검사 결과에 따라 오류, 경고 또는 성공 메시지를 인쇄합니다.

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.

유용한 방법

모든 사용자 지정 커넥터를 다운로드하고, git 또는 다른 원본 제어 시스템을 사용하여 파일을 저장합니다. 잘못된 업데이트가 있는 경우 원본 제어 시스템에서 올바른 파일 세트로 업데이트 명령을 다시 실행하여 커넥터를 다시 배포합니다.

먼저 테스트 환경에서 사용자 지정 커넥터와 설정 파일을 테스트한 후에 프로덕션 환경에 배포합니다. 항상 환경 및 커넥터 ID가 올바른지 다시 확인합니다.

제한 사항

프로젝트는 Power Automate 및 Power Apps 환경에서 사용자 지정 커넥터를 만들고, 업데이트하고, 다운로드하도록 제한됩니다. 환경이 지정되지 않으면 Power Automate 환경만 선택할 수 있도록 나열됩니다. 사용자 지정되지 않은 커넥터의 경우 Swagger 파일이 반환되지 않습니다.

스택 담당자 속성 및 apiProperties 파일:

현재 apiProperties.json 파일에 stackOwner 속성이 있을 때 Paconn을 사용하여 환경에서 커넥터의 아티팩트를 업데이트할 수 없도록 하는 제한 사항이 있습니다. 이에 대한 해결 방법으로 커넥터 아티팩트의 두 가지 버전을 만듭니다. 첫 번째 버전은 인증에 제출되고 stackOwner 속성을 포함하는 버전입니다. 두 번째는 환경 내에서 업데이트할 수 있도록 생략된 stackOwner 속성이 있습니다. 제한 사항을 제거하기 위해 노력하고 있으며 완료되면 이 섹션을 업데이트할 것입니다.

문제점 및 의견 보고

도구에서 버그가 발생하면 GitHub 리포지토리의 문제 섹션에서 문제를 제출하세요.

Microsoft의 보안 취약성 정의를 충족하는 보안 취약성이 있다고 생각되면 보고서를 MSRC에 제출하세요. 자세한 내용은 보고에 대한 MSRC 질문과 대답에서 확인할 수 있습니다.

피드백 제공

커넥터 플랫폼 관련 문제 또는 새로운 기능 아이디어에 대한 피드백을 주셔서 정말 감사합니다. 피드백을 제공하려면 문제 제출 또는 커넥터 관련 도움말 보기로 이동하여 피드백 유형을 선택하십시오.