Power BI 시각적 개체의 기능 및 속성

모든 시각적 개체에는 pbiviz new <visual project name> 명령을 실행하여 새 시각적 개체 만들기를 실행할 때 자동으로 만들어지는 capabilities.json 파일이 있습니다. capabilities.json 파일은 호스트에 시각적 개체를 설명합니다.

capabilities.json 파일은 시각적 개체가 허용하는 데이터 종류, 속성 창에 배치할 사용자 지정 가능한 특성 및 시각적 개체를 만드는 데 필요한 기타 정보를 호스트에 알려줍니다. API v4.6.0부터 기능 모델의 모든 속성은 필수인 privileges을 제외하고 선택 사항입니다.

capabilities.json 파일은 루트 개체를 다음 형식으로 나열합니다.

{
    "privileges": [ ... ],
    "dataRoles": [ ... ],
    "dataViewMappings": [ ... ],
    "objects":  { ... },
    "supportsHighlight": true|false,
    "advancedEditModeSupport": 0|1|2,
    "sorting": { ... }
    ...
}

새 시각적 개체를 만들 때 기본 capabilities.json 파일에는 다음과 같은 루트 개체가 포함됩니다.

• 권한
• dataRoles
• dataViewMappings
• objects

위의 개체는 데이터 바인딩에 필요한 개체입니다. 이러한 개체는 시각적 개체에 필요한 대로 편집할 수 있습니다.

다음과 같은 다른 루트 개체는 선택 사항이며 필요에 따라 추가할 수 있습니다.

• tooltips
• supportsHighlight
• sorting
• 드릴다운
• expandCollapse
• supportsKeyboardFocus
• supportsSynchronizingFilterState
• advancedEditModeSupport
• supportsLandingPage
• supportsEmptyDataView
• supportsMultiVisualSelection
• subtotals
• keepAllMetadataColumns
• migration

이러한 모든 개체 및 해당 매개 변수는 capabilities.json 스키마에서 찾을 수 있습니다.

권한: 시각적 개체에 필요한 특수 권한 정의

권한은 시각적 개체가 작동하기 위해 액세스해야 하는 특수 작업입니다. 권한은 모든 권한 속성을 정의하는 privilege 개체 배열을 사용합니다. 다음 섹션에서는 Power BI에서 사용할 수 있는 권한에 대해 설명합니다.

참고 항목

API v4.6.0부터 capabilities.json 파일에 권한을 지정해야 합니다. 이전 버전에서는 원격 액세스가 자동으로 부여되며 파일에 다운로드할 수 없습니다. 사용 중인 버전을 확인하려면 pbiviz.json 파일에서 apiVersion을 확인합니다.

권한 정의

JSON 권한 정의에는 다음 구성 요소가 포함됩니다.

• name - (문자열) 권한의 이름입니다.
• essential - (부울) 시각적 기능에 이 권한이 필요한지 여부를 나타냅니다. true 값은 권한이 필요함을 의미합니다. false는 권한이 필수가 아님을 의미합니다.
• parameters - (문자열 배열)(선택 사항) 인수입니다. parameters가 누락된 경우 빈 배열로 간주됩니다.

다음은 정의해야 하는 권한 형식입니다.

• 외부 리소스 액세스
• 파일에 다운로드
• 로컬 스토리지 권한

참고 항목

시각적 개체에서 이러한 권한이 부여된 경우에도 관리자는 조직의 사용자가 이러한 설정을 활용할 수 있도록 관리자 설정의 스위치를 사용하도록 설정해야 합니다.

웹 액세스 허용

시각적 개체가 외부 리소스 또는 웹 사이트에 액세스할 수 있도록 하려면 기능 섹션에서 해당 정보를 권한으로 추가합니다. 권한 정의에는 시각적 개체가 http://xyz.com 또는 https://xyz.com 형식으로 액세스할 수 있는 선택적 URL 목록이 포함됩니다. 각 URL에는 하위 도메인을 지정하는 와일드카드가 포함될 수도 있습니다.

다음 코드는 외부 리소스에 대한 액세스를 허용하는 권한 설정의 예입니다.

{
    "name": "WebAccess",
    "essential": true,
    "parameters": [ "https://*.microsoft.com", "http://example.com" ]
}

위의 WebAccess 권한은 시각적 개체가 HTTP 프로토콜을 통해서만 microsoft.com 도메인의 하위 도메인에 액세스하고 HTTPS 통해 하위 도메인 없이 example.com에 액세스해야 하며 이 액세스 권한이 시각적 개체가 작동하는 데 필수적임을 의미합니다.

파일로 다운로드

사용자가 시각적 개체에서 파일로 데이터를 내보낼 수 있도록 하려면 ExportContent를 true로 설정합니다.

이 ExportContent 설정을 사용하면 시각적 개체에서 다음 형식의 파일로 데이터를 내보낼 수 있습니다.

• .txt
• .csv
• json.
• .tmplt
• .xml
• .pdf
• .xlsx

이 설정은 조직의 내보내기 및 공유 테넌트 설정에 적용되는 다운로드 제한 사항과 별개이며 이로 인한 영향을 받지 않습니다.

다음 코드는 파일 다운로드를 허용하는 권한 설정의 예입니다.

"privileges": [
    {
        "name": "ExportContent",
        "essential": true
    }
]

로컬 스토리지 권한

이 권한을 통해 사용자 지정 시각적 개체가 사용자의 로컬 브라우저에 정보를 저장할 수 있습니다.

다음은 로컬 스토리지 사용을 허용하는 권한 설정의 예입니다.

"privileges": [
    {
        "name": "LocalStorage",
        "essential": true
    }
]

필요한 권한이 없음

시각적 개체에 특별한 권한이 필요하지 않은 경우 privileges 배열은 비어 있어야 합니다.

  "privileges": []

다양한 권한

다음 예에서는 사용자 지정 시각적 개체에 대한 여러 권한을 설정하는 방법을 보여 줍니다.

"privileges": [
    {
        "name": "WebAccess",
        "essential": true,
        "parameters": [ "https://*.virtualearth.net" ]
    },
    {
        "name": "ExportContent",
        "essential": false
    }
]

dataroles: 시각적 개체에 필요한 데이터 필드 정의

데이터에 바인딩할 수 있는 필드를 정의하려면 dataRoles를 사용합니다. dataRoles는 모든 필수 속성을 정의하는 DataViewRole 개체의 배열입니다. dataRoles 개체는 속성 창에 표시되는 필드입니다.

사용자가 데이터 필드를 끌어와 데이터 필드를 개체에 바인딩합니다.

DataRole 속성

다음 속성을 사용하여 DataRoles를 정의합니다.

• name: 이 데이터 필드의 내부 이름(고유해야 함)
• displayName: 속성 창에서 사용자에게 표시되는 이름
• kind: 필드 종류:
  • Grouping: 측정값 필드의 그룹화에 사용되는 불연속 값 세트
  • Measure: 단일 숫자 값
  • GroupingOrMeasure: 그룹화 또는 측정값으로 사용할 수 있는 값
• description: 필드에 대한 간략한 설명입니다(선택 사항)
• requiredTypes: 이 데이터 역할에 필요한 데이터 형식 일치하지 않는 값은 null로 설정됩니다(선택 사항).
• preferredTypes: 이 데이터 역할의 기본 데이터 형식(선택 사항)

requiredTypes 및 preferredTypes의 유효한 데이터 형식

• bool: 부울 값
• integer: 정수 값
• numeric: 숫자 값
• text: 텍스트 값
• geography: 지리 데이터

dataRoles 예제

"dataRoles": [
    {
        "displayName": "My Category Data",
        "name": "myCategory",
        "kind": "Grouping",
        "requiredTypes": [
            {
                "text": true
            },
            {
                "numeric": true
            },
            {
                "integer": true
            }
        ],
        "preferredTypes": [
            {
                "text": true
            }
        ]
    },
    {
        "displayName": "My Measure Data",
        "name": "myMeasure",
        "kind": "Measure",
        "requiredTypes": [
            {
                "integer": true
            },
            {
                "numeric": true
            }
        ],
        "preferredTypes": [
            {
                "integer": true
            }
        ]
    }
]
...
}

위의 데이터 역할은 다음 이미지에 표시된 필드를 만듭니다.

dataViewMappings: 원하는 데이터 매핑 방법

dataViewMappings 개체는 데이터 역할이 서로 어떻게 관련되는지 설명하고 데이터 뷰 표시에 대한 조건부 요구 사항을 지정할 수 있도록 합니다.

대부분의 시각적 개체는 단일 매핑을 제공하지만, 여러 개의 dataViewMappings를 제공할 수 있습니다. 유효한 매핑마다 하나의 데이터 뷰를 생성합니다.

"dataViewMappings": [
    {
        "conditions": [ ... ],
        "categorical": { ... },
        "table": { ... },
        "single": { ... },
        "matrix": { ... }
    }
]

자세한 내용은 Power BI 시각적 개체의 데이터 뷰 매핑 이해를 참조하세요.

objects: 속성 창 옵션 정의

개체는 시각적 개체와 연결된 사용자 지정 가능한 속성을 설명합니다. 이 섹션에 정의된 개체는 서식 창에 표시되는 개체입니다. 각 개체에 여러 개의 속성이 있을 수 있으며, 속성마다 연결된 형식이 있습니다.

"objects": {
    "myCustomObject": {
        "properties": { ... }
    }
}

예를 들어 사용자 지정 시각적 개체에서 동적 형식 문자열을 지원하려면 다음 개체를 정의합니다.

"objects": {
        "general": {
            "properties": {
                "formatString": {
                    "type": {
                        "formatting": {
                            "formatString": true
                        }
                    }
                }
            }
        },

자세한 내용은 Power BI 시각적 개체의 개체 및 속성을 참조하세요.

관련 콘텐츠

• Power BI 시각적 개체의 데이터 뷰 매핑 이해
• Power BI 시각적 개체의 개체 및 속성
• Power BI 시각적 개체의 정렬 옵션