개발자 도구를 사용하여 사용자 지정 시각적 개체 만들기Use developer tools to create custom visuals

사용자 지정 시각적 개체를 사용하면 사용자 요구 사항과 앱 디자인에 맞출 수 있습니다.Custom visuals allow you to meet your users' needs and match your app's design. 개발자 도구로 Power BI용 사용자 지정 시각적 개체를 만드는 방법을 알아보세요.Learn how to create a custom visual for Power BI using the developer tools.

참고

이 문서를 사용하면 개발자 도구를 시작하고 실행할 수 있습니다.You can use this document to get up and running. 자세한 내용에 대해서는 Power BI 시각적 개체 Git 리포지토리에 있는 참조 정보를 검토하세요.For more in-depth information, see the reference information within the Power BI Visuals git repo.

요구 사항Requirements

NodeJS 및 Power BI 도구 설치Install NodeJS and the Power BI tools

사용자 지정 시각적 개체를 만들려면 NodeJS를 설치해야 합니다.In order to create a custom visual, you will need to install NodeJS. NodeJS는 명령줄 도구를 실행하기 위해 필요합니다.NodeJS is required to run the command line tools.

  1. NodeJS를 다운로드하고 설치합니다.Download and install NodeJS. 버전 4.0 이상이 필요하지만 5.0 이상을 권장합니다.Version 4.0 or later is required but it is recommended to have 5.0 or later.
  2. 명령줄 도구를 설치합니다.Install the command line tools. 명령 프롬프트에서 다음 명령을 실행합니다.Run the following command from a command prompt.

     npm install -g powerbi-visuals-tools
    
  3. 매개 변수 없이 다음 명령을 실행하여 도구가 설치되었는지 확인할 수 있습니다.You can confirm that the tools are installed by running the following command without any parameters.

     pbiviz
    

    도움말 출력이 표시됩니다.You should see the help output.

    
          +syyso+/
     oms/+osyhdhyso/
     ym/       /+oshddhys+/
     ym/              /+oyhddhyo+/
     ym/                     /osyhdho
     ym/                           sm+
     ym/               yddy        om+
     ym/         shho /mmmm/       om+
      /    oys/ +mmmm /mmmm/       om+
     oso  ommmh +mmmm /mmmm/       om+
    ymmmy smmmh +mmmm /mmmm/       om+
    ymmmy smmmh +mmmm /mmmm/       om+
    ymmmy smmmh +mmmm /mmmm/       om+
    +dmd+ smmmh +mmmm /mmmm/       om+
          /hmdo +mmmm /mmmm/ /so+//ym/
                /dmmh /mmmm/ /osyhhy/
                  //   dmmd
                        ++
    
        PowerBI Custom Visual Tool
    
     Usage: pbiviz [options] [command]
    
     Commands:
    
     new [name]        Create a new visual
     info              Display info about the current visual
     start             Start the current visual
     package           Package the current visual into a pbiviz file
     update [version]  Updates the api definitions and schemas in the current visual. Changes the version if specified
     help [cmd]        display help for [cmd]
    
     Options:
    
     -h, --help      output usage information
     -V, --version   output the version number
     --install-cert  Install localhost certificate
     

<a name"ssl-setup">

서버 인증서 설치Server Certificate setup

시각적 개체에 대한 실시간 미리 보기를 사용하려면 신뢰할 수 있는 https 서버가 필요합니다.To enable a live preview of your visual, a trusted https server is needed. 시작하기 전에 웹 브라우저에서 로드할 수 있도록 시각적 개체 자산을 허용하는 SSL 인증서를 설치해야 합니다.Before you can start, you will need to install an SSL certificate which will allow visual assets to load in your web browser.

참고

이 인증서는 개발자 워크스테이션에 한 번만 설치합니다.This is a one-time setup for your developer workstation.

인증서를 추가하려면 다음 명령을 실행합니다.To add a certificate, run the following command.

pbiviz --install-cert

Windows OSWindows OS

  1. 인증서 설치...를 선택합니다.Select Install Certificate....

  2. 현재 사용자, 다음을 차례로 선택합니다.Select Current User and then select Next.

  3. 모든 인증서를 다음 저장소에 저장, 찾아보기...를 차례로 선택합니다.Select Place all certificate in the following store and select Browse....
  4. 신뢰할 수 있는 루트 인증 기관, 확인을 차례로 선택합니다.Select Trusted Root Certification Authorities and then select OK. 다음을 선택합니다.Select Next.

  5. 마침을 선택합니다.Select Finish.

  6. 보안 경고 대화 상자에서 를 선택합니다.Select Yes on the security warning dialog.

  7. 열려 있는 브라우저를 모두 닫습니다.Close any browsers that you have open.

참고

인증서가 인식되지 않으면 컴퓨터를 다시 시작해야 합니다.If the certificate is not recognized, you may need to restart your computer.

OSXOSX

  1. 왼쪽 위의 자물쇠가 잠겨 있으면 이 자물쇠를 선택하여 잠금을 해제합니다.If the lock in the upper left is locked, select it to unlock. localhost를 검색하고 해당 인증서를 두 번 클릭합니다.Search for localhost and double click on the certificate.

  2. 항상 신뢰를 선택하고 창을 닫습니다.Select Always Trust and close the window.

  3. 사용자 이름과 암호를 입력 합니다.Enter your username and password. 설정 업데이트를 선택합니다.Select Update Settings.

  4. 열려 있는 브라우저를 모두 닫습니다.Close any browsers that you have open.

참고

인증서가 인식되지 않으면 컴퓨터를 다시 시작해야 합니다.If the certificate is not recognized, you may need to restart your computer.

개발자 시각적 개체의 실시간 미리 보기 사용Enable live preview of developer visual

사용자 지정 시각적 개체에 대한 실시간 미리 보기를 사용하려면 다음 단계를 수행 합니다.To enable a live preview of your custom visual, follow these steps. 이렇게 하면 보고서를 편집할 때 Power BI 서비스에서 시각적 개체를 사용할 수 있습니다.This allows the visual to be used within the Power BI service when editing reports.

  1. app.powerbi.com을 찾아 로그인합니다.Browse and sign into app.powerbi.com.
  2. 기어 아이콘, 설정을 차례로 선택합니다.Select the gear icon and then select Settings.

  3. 개발자, 테스트를 위해 개발자 시각적 개체 사용하도록 설정을 차례로 선택합니다.Select Developer and then select Enable developer visual for testing.

  4. 시각화 창에서 개발자 시각적 개체를 선택합니다.Select the Developer Visual in the Visualization pane.

    참고

    이렇게 하려면 개발 컴퓨터의 시각적 개체 폴더에서 pbiviz start를 실행했어야 합니다.This requires that you have run pbiviz start from the visual folder on your development machine. 시각적 개체 만들기에 대한 자세한 내용은 이 문서의 새 시각적 개체 만들기를 참조하세요.For more information on creating your visual, see Create a new visual in this article.

  5. 보고서 캔버스에서 시각적 개체를 선택합니다.Select the visual in the report canvas. 다른 시각적 개체를 처리하는 것처럼 데이터를 바인딩할 수 있습니다.You can bind data in the same way you do other visuals.

이제 시각적 개체를 개발하기 위해 시작할 수 있습니다.You can now begin developing your visual.

새 시각적 개체 만들기Create a new visual

다음 명령을 실행하여 새로운 시각적 개체 프로젝트를 만들 수 있습니다.You can create a new visual project by running the following command.

pbiviz new My Visual name

내 시각적 개체 이름을 시각적 개체에 부여할 이름으로 바꿀 수 있습니다.You can replace My Visual Name with the name you want to give the visual. 나중에 이 이름은 생성된 pbiviz.json 파일의 namedisplayName 필드를 수정하여 변경할 수 있습니다.This can be changed later by modifying the name and displayName fields within the generated pbiviz.json file.

이 명령은 실행된 바로 그 위치에 새 폴더를 만듭니다.This command will create a new folder in the direct where the command was run. 시각적 개체를 위한 기본 시작 템플릿을 생성 합니다.It will generate a basic starter template for your visual. 명령이 완료되면 디렉터리를 열고 선호하는 편집기를 사용하여 새 시각적 개체에 대한 작업을 시작할 수 있습니다.Once the command completes, you can open the directory and use your favorite editor to start working on your new visual.

Power BI에서 시각적 개체 테스트Testing your visual in Power BI

보고서와 대시보드의 Power BI 서비스에서 시각적 개체를 테스트할 수 있습니다.You can test your visual within the Power BI service within reports and dashboards.

시각적 개체 실행Running your visual

다음을 수행하면 시각적 개체를 실행할 수 있습니다.You can run your visual by doing the following.

  1. 프롬프트를 엽니다.Open a prompt.
  2. 시각적 개체 폴더가 있는 디렉터리로 이동합니다.Change your directory to be your visual folder. 이 폴더에는 pbiviz.json 파일이 있습니다.This is the folder that contains the pbiviz.json file.
  3. 다음 명령을 실행합니다.Run the following command.

    pbiviz start
    

잘못된 위치에 있으면 다음과 비슷한 오류 메시지가 표시됩니다.If you are in the wrong location, you will see an error similar to the following.

    error  LOAD ERROR Error: pbiviz.json not found. You must be in the root of a visual project to run this command.
        at e (C:\Users\[user]\AppData\Roaming\npm\node_modules\powerbi-visuals-tools\lib\VisualPackage.js:67:35)
        at Function.loadVisualPackage (C:\Users\[user]\AppData\Roaming\npm\node_modules\powerbi-visuals-tools\lib\VisualPackage.js:62:16)
        at Object.<anonymous> (C:\Users\[user]\AppData\Roaming\npm\node_modules\powerbi-visuals-tools\bin\pbiviz-start.js:43:15)
        at Module._compile (module.js:556:32)
        at Object.Module._extensions..js (module.js:565:10)
        at Module.load (module.js:473:32)
        at tryModuleLoad (module.js:432:12)
        at Function.Module._load (module.js:424:3)
        at Module.runMain (module.js:590:10)
        at run (bootstrap_node.js:394:7)

Power BI에서 시각적 개체 보기Viewing your visual in Power BI

보고서에서 시각적 개체를 보려면 해당 보고서로 이동하고 시각화 창에서 시각적 개체를 선택합니다.To view your visual in a report, go to that report and select the visual within the Visualizations pane.

참고

시각적 개체 실행 섹션에서 설명한 대로 먼저 pbiviz start 명령을 실행해야 이 작업을 수행할 수 있습니다.You must run the pbiviz start command before doing this as discribed in the Running your visual section.

이제 시각적 개체에 대한 시작 템플릿이 표시됩니다.You will then see the starter template for the visual.

도구 모음 항목Toolbar item 설명Description
시각적 개체 새로 고침Refresh visual 자동 다시 로드를 사용할 수 없으면 시각적 개체를 수동으로 새로 고칩니다.Manually refresh the visual if auto reload is disabled.
자동 다시 로드 토글Toggle auto reload 작동 시 시각적 개체 파일을 저장할 때마다 시각적 개체가 자동으로 업데이트됩니다.When turned on, the visual will automatically update every time you save your visual file.
데이터 보기 표시Show dataview 디버깅할 수 있도록 시각적 개체의 기본 데이터 보기를 보여 줍니다.Shows the visual's underlying data view for debugging
도움말 보기Get help GitHub에 있는 문서입니다.Documentation within GitHub
피드백 보내기Send feedback 환경을 개선할 수 있는 귀중한 경험이 있으면 알려 주십시오!Let us know if there is anyway we can improve the experience! (GitHub 계정 필요)(Requires GitHub account)

Power BI Desktop 및 배포에 사용할 시각적 개체 패키징Package your visual for use in Power BI Desktop and distribution

시각적 개체를 Power BI Desktop에 로드하거나 Power BI 시각적 개체 갤러리의 커뮤니티와 공유하려면 먼저 pbiviz 파일을 생성해야 합니다.Before you can load your visual into Power BI Desktop, or share it with the community in the Power BI Visual gallery, you'll need to generate a pbiviz file.

다음을 수행하면 시각적 개체를 패키징할 수 있습니다.You can package your visual by doing the following.

  1. 프롬프트를 엽니다.Open a prompt.
  2. 시각적 개체 폴더가 있는 디렉터리로 이동합니다.Change your directory to be your visual folder. 이 폴더에는 pbiviz.json 파일이 있습니다.This is the folder that contains the pbiviz.json file.
  3. 다음 명령을 실행합니다.Run the following command.

    pbiviz package
    

이 명령은 dist/ 디렉터리에 시각적 개체 프로젝트의 pbiviz 파일을 만듭니다.This command will create a pbiviz in the dist/ directory of your visual project. 이미 pbiviz 파일이 있으면 이 파일을 덮어씁니다.If there is already a pbiviz file present, it will be overwritten.

시각적 개체 API 버전 업데이트Updating the visuals API version

pbiviz new를 사용하여 시각적 개체를 만드는 경우 해당 API type 정의 및 json 스키마의 복사본이 시각적 개체의 디렉터리로 복사됩니다.When you create a visual using pbiviz new, a copy of the appropriate API type definitions and json schemas are copied into your visual's directory. 필요한 경우 pbiviz update 명령을 사용하여 이러한 파일을 업데이트할 수 있습니다.You can use the pbiviz update command to update these files if needed. 이렇게 하면 이전 API 버전에 대한 수정이 릴리스되거나 최신 API 버전으로 업데이트하려는 경우에 유용합니다.This can be useful if we release a fix for a past API version or if you want to update to the latest API version.

기존 API 버전 업데이트Updating your existing API version

기존 API에 대한 업데이트가 릴리스되는 경우 다음을 수행하여 최신 버전을 가져올 수 있습니다.If we release an update to an existing API, you can get the latest version by doing the following.

#Update your version of pbiviz
npm install -g powerbi-visuals-tools

#Run update from the root of your visual project, where pbiviz.json is located
pbiviz update

이렇게 하면 npm에서 업데이트된 type 정의와 스키마를 포함한 최신 도구를 다운로드합니다.This will download the latest tools from npm which include the updated type definitions and schemas. pbiviz update를 사용하는 경우 pbiviz.json 파일의 apiVersion 속성을 최신 버전으로 덮어씁니다.Using pbiviz update will overwrite the apiVersion property in your pbiviz.json fiel with the latest version.

다른 API 버전으로 업그레이드Upgrading to a different API version

위에서 설명한 대로 동일한 단계를 사용하여 다른 API 버전으로 업데이트할 수 있습니다.You can update to a different API version by using the same steps as mentioned above. 사용할 API 버전을 명시적으로 지정할 수 있습니다.You can explicitly specify the API version you want to use.

#Update your version of pbiviz
npm install -g powerbi-visuals-tools

#Run update from the root of your visual project, where pbiviz.json is located
pbiviz update 1.2.0

이렇게 하면 시각적 개체를 API 버전 1.2.0으로 업데이트합니다.This would update yoru visual to API version 1.2.0. 1.2.0은 어떤 버전으로도 바꿔 사용할 수 있습니다.You can replace 1.2.0 with whatever version your wanting to use.

경고

도구에서 사용하는 기본 API 버전은 항상 안정적인 API 버전입니다.The default API version used by the tools will always be the stable version of the API. 기본 API 버전 이후의 버전은 안정적이지 못하며 조금 후에 바로 바뀔 수도 있습니다.Any versions later than the default API version are unstable and subject to change. 예기치 않은 동작이 발생하거나 Power BI 서비스와 Power BI Desktop 간에 다르게 작동할 수 있습니다.They may have unexpected behaviors and behave differently between the Power BI service and Power BI Desktop. 현재 안정적인 API 버전에 대해서는 변경 로그를 참조하세요.For the current stable API version, see the change log. 시험판 버전에 대한 자세한 내용은 로드맵을 참조하세요.For more information about pre-release versions, see the roadmap.

시각적 개체 프로젝트 내부 구조Inside the visual project

시각적 개체 프로젝트는 pbiviz new 명령을 실행할 때 만들어지는 폴더입니다.Your visual project is the folder that gets created when you run the pbiviz new command.

파일 구조File structure

항목Item 설명Description
assets/assets/ 아이콘, 스크린샷 등 시각적 개체 자산을 저장 하기 위해 사용됩니다.Used to store visual assets (icon, screenshots, etc).
dist/dist/ pbiviz package를 실행할 때 pbiviz 파일이 생성되는 위치입니다.When you run pbiviz package, the pbiviz file will be generated here.
src/src/ 시각적 개체에 대한 TypeScript 코드입니다.Typescript code for your visual.
style/style/ 시각적 개체에 대한 Less 스타일입니다.Less styles for your visual.
.gitignore.gitignore 리포지토리에서 추적되지 않는 파일을 무시하도록 Git에 알립니다.Tells git to ignore files that shouldn't be tracked in the repository.
capabilities.jsoncapabilities.json 시각적 개체의 capabilities를 정의하기 위해 사용됩니다.Used to define the capabilities of your visual.
package.jsonpackage.json npm에서 모듈을 관리하기 위해 사용됩니다.Used by npm to manage modules.
pbiviz.jsonpbiviz.json 기본 구성 파일입니다.Main configuration file.
tsconfig.jsontsconfig.json TypeScript 컴파일러 설정입니다.Typescript compiler settings. tsconfig.json에서 자세히 알아보세요.Learn more about tsconfig.json.

pbiviz.jsonpbiviz.json

시각적 개체에 대한 기본 구성 파일입니다.This file is the main configuration file for your visual. 여기에는 시각적 개체를 빌드하는 데 필요한 파일 관련 정보와 함께 메타 데이터도 포함되어 있습니다.It contains metadata, as well as information about your files, needed to build your visual.

{
    "visual": {
        "name": "myVisual", // internal visual name (should not contain spaces)
        "displayName": "My Visual!", // visual name displayed to user (used in gallery)
        "guid": "PBI_CV_xxxxxxx", // a unique id for this visual MUST BE UNIQUE
        "visualClassName": "Visual" // the entry class for your visual
        "version": "1.0.0", // visual version. Should be semantic version (increment if you update the visual)
        "description": "", // description used in gallery
        "supportUrl": "", // url to where users can get support for this visual
        "gitHubUrl": "" // url to the source in github (if applicable)
    },
    "apiVersion": "1.0.0", //API version this visual was created with
    "author": {
        "name": "", // your name
        "email": "" // your e-mail
    },
    "assets": {
        "icon": "assets/icon.png" // relative path to your icon file (20x20 png)
    },
    "style": "style/visual.less", // relative path to your less file
    "capabilities": "capabilities.json" // relative path to your capabilities definition 
}

시각적 개체 원본(TypeScript)Visual source (TypeScript)

시각적 개체는 더 많은 고급 기능과 ES6/ES7 기능에 대한 초기 액세스를 지원하는 JavaScript의 상위 집합인 TypeScript로 작성해야 합니다.Visual code should be written in TypeScript, which is a superset of JavaScript that support more advanced features and early access to ES6/ES7 functionality.

모든 TypeScript 파일은 src/ 디렉터리에 저장되고 tsconfig.jsonfiles 배열에 추가되어야 합니다.All TypeScript files should be stored in the src/ directory and added to the files array in tsconfig.json. 이렇게 하면 TypeScript 컴파일러에서 특정 순서로 이 파일들을 로드할 수 있습니다.This allows the TypeScript compiler to load them and in what order.

시각적 개체를 빌드할 때 모든 TypeScript가 하나의 JavaScript 파일로 컴파일됩니다.When your visual is built, all of the TypeScript will be compiled into a single JavaScript file. 이렇게 하면 두 파일이 tsconfig에 나열되어 있는 동안에는 수동으로 require를 수행할 필요 없이 다른 파일에서 내보낸 요소를 참조할 수 있습니다.This allows you to reference exported elements from other files without needing to manually require them as long as both files are listed in the tsconfig.

시각적 개체를 만들어야 하는 만큼 많은 개수의 파일과 클래스를 만들 수 있습니다.You can create as many files and classes as you need to create your visual.

TypeScript에서 자세히 알아보세요.Learn more about TypeScript.

시각적 개체 스타일(Less)Visual style (Less)

시각적 개체 스타일 지정은 CSS 스타일 시트로 처리됩니다.Visual styling is handled using cascading style sheets (CSS). 편의상 중첩, 변수, mixin, 조건, 루프 등 몇 가지 고급 기능을 지원하는 Less 사전 컴파일러를 사용합니다. 이러한 기능 중 하나를 사용하지 않을 경우 Less 파일에 일반 CSS만 작성할 수 있습니다.For your convience, we use the Less pre-compiler which supports some advanced features such as nesting, variables, mixins, conditions, loops, etc. If you don't want to use any of these features, you can just write plain CSS in the Less file.

모든 Less 파일은 style/ 디렉터리에 저장됩니다.All Less files should be stored in the style/ directory. pbiviz.json 파일의 style 필드에 지정된 파일이 로드됩니다.The file specified under the style field within your pbiviz.json file will be loaded. 추가되는 파일은 모두 @import를 사용하여 로드됩니다.Any additional files should be loaded using @import.

Less에서 자세히 알아보세요.Learn more about Less.

디버깅Debugging

사용자 지정 시각적 개체의 디버깅에 대한 팁은 디버깅 가이드를 을 참조하세요.For tips about debugging your custom visual, see the debugging guide.

AppSource에 시각적 개체 제출Submit your visual to AppSource

다른 사람들이 사용할 시각적 개체를 나열하고 AppSource에 제출할 수 있습니다.You can list your visual for others to use but submitting it to AppSource. 이 과정에 대한 자세한 내용은 사용자 지정 시각적 개체를 AppSource에 게시를 참조하세요.For more information on this process, see publish custom visuals to AppSource.

문제 해결Troubleshooting

Pbiviz 명령어가 없습니다(또는 유사한 오류)Pbiviz command not found (or similar errors)

pbiviz를 터미널/명령줄에서 실행하는 경우에는 도움말 화면이 표시됩니다.If you run pbiviz in your terminal / command line, you should see the help screen. 그렇지 않은 경우 개발자 도구가 올바르게 설치되지 않았습니다.If not, it is not installed correctly. 4.0 버전 이상의 NodeJS를 설치했는지 확인합니다.Make sure you have at least the 4.0 version of NodeJS installed.

자세한 내용은 NodeJS 및 Power BI 도구 설치를 참조하세요.For more information, see Install NodeJS and the Power BI tools...

시각화 탭에 디버그 시각적 개체가 없습니다Cannot find the debug visual in the Visualizations tab

시각화 탭에는 프롬프트 아이콘처럼 보이는 디버그 시각적 개체가 있습니다.The debug visual looks like a prompt icon within the Visualizations tab.

디버그 시각적 개체가 보이지 않으면 Power BI 설정에서 사용할 수 있도록 설정되었는지 확인합니다.If you don't see it, make sure you have enabled it within the Power BI settings.

참고

디버그 시각적 개체는 현재 Power BI 서비스에서만 제공되며, Power BI Desktop이나 모바일 앱에는 제공되지 않습니다.The debug visual is currently only available in the Power BI service and not in Power BI Desktop or the mobile app. 패키징된 시각적 개체는 어디서나 변함 없이 작동됩니다.The packaged visual will still work everywhere.

자세한 내용은 개발자 시각적 개체의 실시간 미리 보기 사용을 참조하세요.For more information, see Enable live preview of developer visual...

시각적 개체 서버에 연결할 수 없습니다Can't contact visual server

시각적 개체 프로젝트의 루트에 있는 터미널/명령줄의 pbiviz start 명령으로 서버를 실행합니다.Run the visual server with the command pbiviz start in your terminal / command line from the root of your visual project. 서버가 실행 중인 경우 SSL 인증서가 올바르게 설치되지 않았을 수도 있습니다.If the server is running, it is likely that your SSL vertificates weren't installed correctly.

자세한 내용은 시각적 개체 실행 또는 서버 인증서 설치를 참조하세요.For more information, see Running your visual or Server certificate setup.

다음 단계Next steps

Power BI의 시각화Visualizations in Power BI
Power BI의 사용자 지정 시각화Custom Visualizations in Power BI
사용자 지정 시각적 개체를 Office 스토어에 게시Publish custom visuals to the Office store
TypeScriptTypeScript
Less CSSLess CSS

궁금한 점이 더 있나요?More questions? Power BI 커뮤니티에 질문합니다.Try asking the Power BI Community