Power BI 시각적 개체 시스템 통합Power BI visuals system integration

이 문서에서는 시각적 개체가 Power BI와 통합되는 방법과 사용자가 Power BI의 시각적 개체와 상호 작용하는 방법을 설명합니다.The article describes how visuals integrate with Power BI and how a user can interact with a visual in Power BI.

다음 그림은 책갈피 선택과 같이 사용자가 수행하는 일반적인 시각적 개체 기반 작업이 Power BI에서 처리되는 방법을 보여 줍니다.The following figure depicts how common visual-based actions that a user takes, like selecting a bookmark, are processed in Power BI.

Power BI 시각적 개체 작업 다이어그램

Power BI에서 시각적 개체 업데이트 가져오기Visuals get updates from Power BI

시각적 개체는 update 메서드를 호출하여 Power BI에서 업데이트를 가져옵니다.A visual calls an update method to get updates from Power BI. update 메서드는 일반적으로 시각적 개체의 기본 논리를 포함하며, 차트를 렌더링하거나 데이터를 시각화합니다.The update method usually contains the main logic of the visual and is responsible for rendering a chart or visualizing data.

시각적 개체가 update 메서드를 호출하면 업데이트가 트리거됩니다.Updates are triggered when the visual calls the update method.

작업 및 업데이트 패턴Action and update patterns

Power BI에서의 작업 및 후속 업데이트는 다음 세 가지 패턴 중 하나로 이루어집니다.Actions and subsequent updates in Power BI visuals occur in one of these three patterns:

  • 사용자가 Power BI를 통해 시각적 개체와 상호 작용.User interacts with a visual through Power BI.
  • 사용자가 시각적 개체와 직접 상호 작용.User interacts with the visual directly.
  • 시각적 개체가 Power BI와 상호 작용.Visual interacts with Power BI.

사용자가 Power BI를 통해 시각적 개체와 상호 작용User interacts with a visual through Power BI

  • 사용자가 시각적 개체의 속성 패널을 엽니다.A user opens the visual's properties panel.

    사용자가 시각적 개체의 속성 패널을 열면 Power BI는 시각적 개체의 capabilities.json 파일에서 지원되는 개체와 속성을 가져옵니다.When a user opens the visual's properties panel, Power BI fetches supported objects and properties from the visual's capabilities.json file. Power BI는 실제 속성 값을 받기 위해 시각적 개체의 enumerateObjectInstances 메서드를 호출합니다.To receive actual values of properties, Power BI calls the enumerateObjectInstances method of the visual. 시각적 개체는 속성의 실제 값을 반환합니다.The visual returns actual values of properties.

    자세한 내용은 Power BI 시각적 개체의 기능 및 속성을 참조하세요.For more information, see Capabilities and properties of Power BI visuals.

  • 사용자가 서식 패널에서 시각적 개체의 속성을 변경합니다.A user changes a property of the visual in the format panel.

    사용자가 서식 패널에서 속성의 값을 변경하면 Power BI는 시각적 개체의 update 메서드를 호출합니다.When a user changes the value of a property in the format panel, Power BI calls the update method of the visual. Power BI는 새 options 개체를 update 메서드로 전달합니다.Power BI passes in the new options object to the update method. 개체에는 새 값이 포함되어 있습니다.The objects contain the new values.

    자세한 내용은 Power BI 시각적 개체의 개체 및 속성을 참조하세요.For more information, see Objects and properties of Power BI visuals.

  • 사용자가 시각적 개체의 크기를 조정합니다.A user resizes the visual.

    사용자가 시각적 개체의 크기를 변경하면 Power BI는 새 options 개체를 사용하여 update 메서드를 호출합니다.When a user changes the size of a visual, Power BI calls the update method with the new options object. options 개체에는 시각적 개체의 새 너비와 높이를 포함하는 중첩된 viewport 개체가 있습니다.The options objects have nested viewport objects that contain the new width and height of the visual.

  • 사용자가 보고서, 페이지 또는 시각적 개체 수준에서 필터를 적용합니다.A user applies a filter at the report, page, or visual level.

    Power BI는 필터 조건에 따라 데이터를 필터링합니다.Power BI filters data based on filter conditions. Power BI는 시각적 개체의 update 메서드를 호출하여 새 데이터로 시각적 개체를 업데이트합니다.Power BI calls the update method of the visual to update the visual with new data.

    시각적 개체는 중첩된 개체 중 하나에 새 데이터가 있으면 options 개체의 새 업데이트를 가져옵니다.The visual gets a new update of the options objects when there's new data in one of the nested objects. 업데이트가 이루어지는 방법은 시각적 개체의 데이터 뷰 매핑 구성에 따라 달라집니다.How the update occurs depends on the data view mapping configuration of the visual.

    자세한 내용은 Power BI 시각적 개체의 데이터 뷰 매핑 이해를 참조하세요.For more information, see Understand data view mapping in Power BI visuals.

  • 사용자가 보고서의 다른 시각적 개체에서 데이터 요소를 선택합니다.A user selects a data point in another visual in the report.

    사용자가 보고서의 다른 시각적 개체에서 데이터 요소를 선택하면 Power BI는 선택된 데이터 요소를 필터링하거나 강조 표시하고 시각적 개체의 update 메서드를 호출합니다.When a user selects a data point in another visual in the report, Power BI filters or highlights the selected data points and calls the visual's update method. 시각적 개체는 필터링된 새 데이터를 가져오거나 강조 표시의 배열이 있는 동일한 데이터를 가져옵니다.The visual gets new filtered data, or it gets the same data with an array of highlights.

    자세한 내용은 Power BI 시각적 개체에서 데이터 요소 강조 표시를 참조하세요.For more information, see Highlight data points in Power BI visuals.

  • 사용자가 보고서의 책갈피 패널에서 책갈피를 선택합니다.A user selects a bookmark in the bookmarks panel of the report.

    사용자가 보고서의 책갈피 패널에서 책갈피를 선택하면 다음 두 가지 작업 중 하나가 발생할 수 있습니다.When a user selects a bookmark in the report's bookmarks panel, one of two actions can occur:

    • Power BI가 registerOnSelectionCallback 메서드에 의해 전달 및 등록된 함수를 호출 합니다.Power BI calls a function that's passed and registered by the registerOnSelectionCallback method. 콜백 함수가 해당 책갈피에 대한 선택 항목의 배열을 가져옵니다.The callback function gets arrays of selections for the corresponding bookmark.

    • Power BI는 options 개체 내의 해당 filter 개체를 사용하여 update 메서드를 호출합니다.Power BI calls the update method with a corresponding filter object inside the options object.

    어느 경우든 시각적 개체는 받은 선택 항목 또는 filter 개체에 따라 상태를 변경해야 합니다.In either case, the visual must change its state according to the received selections or filter object.

    책갈피와 필터에 대한 자세한 내용은 Power BI 시각적 개체의 시각적 개체 필터 API를 참조하세요.For more information about bookmarks and filters, see Visual Filters API in Power BI visuals.

사용자가 시각적 개체와 직접 상호 작용User interacts with the visual directly

  • 사용자가 마우스로 데이터 요소를 가리킵니다.A user hovers the mouse over a data element.

    시각적 개체는 Power BI 도구 설명 API를 통해 데이터 요소에 대한 추가 정보를 표시할 수 있습니다.A visual can display more information about a data point through the Power BI Tooltips API. 사용자가 시각적 개체 요소를 마우스로 가리키면 시각적 개체는 이벤트를 처리하고 연결된 도구 설명 요소에 대한 데이터를 표시할 수 있습니다.When a user hovers the mouse over a visual element, the visual can handle the event and display data about the associated tooltip element. 시각적 개체는 표준 도구 설명 또는 보고서 페이지 도구 설명을 표시할 수 있습니다.The visual can display either a standard tooltip or a report page tooltip.

    자세한 내용은 Power BI 시각적 개체의 도구 설명을 참조하세요.For more information, see Tooltips in Power BI visuals.

  • 사용자가 시각적 개체 속성을 변경합니다.A user changes visual properties. (예를 들어 사용자가 트리를 확장하고 시각적 개체가 시각적 개체 속성의 상태를 저장합니다.)(For example, a user expands a tree and the visual saves state in the visual properties.)

    시각적 개체는 Power BI API를 통해 속성 값을 저장할 수 있습니다.A visual can save properties values through the Power BI API. 예를 들어 사용자가 시각적 개체와 상호 작용하고 시각적 개체가 속성 값을 저장하거나 업데이트해야 하는 경우, 시각적 개체는 presistProperties 메서드를 호출할 수 있습니다.For example, when a user interacts with the visual and the visual needs to save or update properties values, the visual can call the presistProperties method.

  • 사용자가 URL을 선택합니다.A user selects a URL.

    기본적으로 시각적 개체는 URL을 직접 열 수 없습니다.By default, a visual can't open a URL directly. 대신 시각적 개체는 launchUrl 메서드를 호출하고 URL을 매개 변수로 전달하여 새 탭에서 URL을 열 수 있습니다.Instead, to open a URL in a new tab, the visual can call the launchUrl method and pass the URL as a parameter.

    자세한 내용은 시작 URL 만들기를 참조하세요.For more information, see Create a launch URL.

  • 사용자가 시각적 개체를 통해 필터를 적용합니다.A user applies a filter through the visual.

    시각적 개체는 applyJsonFilter 메서드를 호출하고 다른 시각적 개체의 데이터를 위한 필터에 조건을 전달할 수 있습니다.A visual can call the applyJsonFilter method and pass conditions to filter for data in other visuals. 기본, 고급, 튜플 필터를 비롯한 여러 가지 유형의 필터를 사용할 수 있습니다.Several types of filters are available, including Basic, Advanced, and Tuple filters.

    자세한 내용은 Power BI 시각적 개체의 시각적 개체 필터 API를 참조하세요.For more information, see Visual Filters API in Power BI visuals.

  • 사용자가 시각적 개체의 요소를 선택합니다.A user selects elements in the visual.

    Power BI 시각적 개체에서의 선택에 대한 자세한 내용은 Power BI 시각적 개체 선택을 사용하여 대화형 작업 추가를 참조하세요.For more information about selections in a Power BI visual, see Add interactivity by using Power BI visual selections.

시각적 개체의 Power BI와의 상호 작용Visual interacts with Power BI

  • 시각적 개체가 Power BI에서 더 많은 데이터를 요청합니다.A visual requests more data from Power BI.

    시각적 개체가 데이터를 파트별로 처리합니다.A visual processes data part by part. fetchMoreData API 메서드는 데이터 세트의 다음 데이터 조각을 요청합니다.The fetchMoreData API method requests the next fragment of data in the dataset.

    자세한 내용은 Power BI에서 더 많은 데이터 가져오기를 참조하세요.For more information, see Fetch more data from Power BI.

  • 이벤트 서비스가 트리거됩니다.The event service triggers.

    Power BI는 보고서를 PDF로 내보내거나 전자 메일을 통해 보고서를 보낼 수 있습니다(인증된 시각적 개체에만 적용).Power BI can export a report to PDF or send a report by e-mail (applies only to certified visuals). 렌더링이 완료되고 시각적 개체가 PDF 또는 전자 메일로 캡처될 준비가 되었다고 Power BI에 알리려면 시각적 개체가 렌더링 이벤트 API를 호출해야 합니다.To notify Power BI that rendering is finished and that the visual is ready to be captured as PDF or e-mail, the visual should call the Rendering Events API.

    자세한 내용은 Power BI에서 PDF로 보고서 내보내기를 참조하세요.For more information, see Export reports from Power BI to PDF.

    이벤트 서비스에 대해 알아보려면 Power BI 시각적 개체에서 이벤트 렌더링을 참조하세요.To learn about the event service, see Render events in Power BI visuals.

다음 단계Next steps

시각화를 만들어 Microsoft AppSource에 추가하는 데 관심이 있으신가요?Interested in creating visualizations and adding them to Microsoft AppSource? 아래 문서를 참조하세요.See these articles: