동적 드릴 제어

아티클
06/25/2024

참고 항목

이 기능은 API 버전 5.7.0에서 사용할 수 있습니다.

동적 드릴 제어 기능을 사용하면 시각적으로 API 호출을 사용하여 드릴 기능을 동적으로 사용하거나 사용하지 않도록 설정할 수 있습니다. 드릴 기능이 사용하도록 설정되면 API 호출, 바로 가기 메뉴 명령, 헤더 드릴 단추, 계층 구조 데이터 지원을 포함한 모든 드릴다운 기능과 확장/축소 기능을 사용할 수 있습니다. 사용하지 않도록 설정되면 이러한 기능을 사용할 수 없습니다.

다음 이미지는 동적 드릴 제어 기능이 사용하거나 사용하지 않도록 설정된 시각적 개체의 예를 보여 줍니다.

드릴 사용
드릴 사용 안 함

드릴다운이 사용하지 않도록 설정되어 각 대륙과 그 아래에 해당 대륙의 모든 국가/지역이 표시되어 있는 시각적 개체 스크린샷.

동적 드릴 제어 기능에는 다음 API 요소가 포함됩니다.

DataRolesInfo의 isDrillDisabled 플래그:

export interface DataRolesInfo {
      //…
      isDrillDisabled?: boolean; // ----- NEW -----
  }

IVisualHost 인터페이스의 setCanDrill 메서드:

  export interface IVisualHost extends extensibility.IVisualHost {
      //…
      setCanDrill: (drillAllowed: boolean) => void; // ----- NEW -----
  }

드릴이 사용하지 않도록 설정되었는지 확인하려면 업데이트 메서드에서 isDrillDisabled 속성을 사용합니다.

    private update(options: VisualUpdateOptions) {
      //…
      const isDrillDisabled = options.dataViews[0].metadata.dataRoles.isDrillDisabled;
      //…
    }

그런 다음 API 호출을 사용하여 필요에 따라 드릴을 사용하거나 사용하지 않도록 설정합니다.

사용하도록 설정하려면: this.host.setCanDrill(true /* drillAllowed */);
사용하지 않도록 설정하려면: this.host.setCanDrill(false /* drillAllowed */);

동적 드릴 제어 요구 사항

드릴링은 기본적으로 사용하도록 설정되어 있지만 동적 드릴 제어 기능을 사용하면 시각적으로 API 호출을 사용하여 드릴링을 사용하거나 사용하지 않도록 설정할 수 있습니다.

동적 드릴 제어 기능이 포함된 시각적 개체는 capabilities.json 파일에 다음 코드를 포함합니다.

기본적으로 드릴이 사용하지 않도록 설정된 경우:

    "drilldown": {
        "roles": [
            "Rows",
            "Columns"
        ],
        "canDisableDrill": { 
            "disabledByDefault": true
        }
    },

기본적으로 드릴이 사용하도록 설정된 경우:

    "drilldown": {
        "roles": [
            "Rows",
            "Columns"
        ],
        "canDisableDrill": {}
    },

canDisableDrill 속성은 시각적 개체가 이 기능을 지원함을 나타냅니다. 이 속성이 없으면 API 호출이 적용되지 않습니다.
disabledByDefault 속성은 기본적으로 드릴 기능을 사용하지 않도록 설정할지 여부를 나타냅니다.

참고 항목

다음 작업 중 하나를 수행하면 disabledByDefault 속성이 적용됩니다.

캔버스에 새 시각적 개체 추가
이 기능을 지원하지 않는 시각적 개체를 변환합니다.

예를 들어, sourceVisual을 targetVisual로 변환하는 경우 targetVisual의 disabledByDefault 속성은 sourceVisual이 이 기능을 지원하지 않는 경우에만 고려됩니다. sourceVisual이 이 기능을 지원하는 경우 targetVisual은 기본값이 아닌 sourceVisual의 상태를 유지합니다.

기존 시각적 개체의 새 버전에 드릴다운 지원 추가

드릴다운 기능을 사용하는 것은 호환성이 손상되는 변경을 의미합니다. 따라서 가장 원활한 전환을 위해서는 새 버전에 대해 새 시각적 GUID를 사용하는 것이 좋습니다.

그러나 동일한 GUID를 유지하려면 다음 사항에 유의해야 합니다.

드릴할 수 없는 버전에서 드릴할 수 있는 새 버전으로 마이그레이션하는 경우 드릴 기능의 일부로 도입된 계층적 데이터 지원으로 인해 일부 데이터가 dataView에 제공되지 않을 수 있습니다. 동적 드릴 제어 기능은 이 문제에 대한 자동 지원을 제공하지 않지만 마이그레이션 프로세스를 관리하는 데 사용할 수 있습니다.
시각적 개체의 자체 마이그레이션을 위해 시각적 개체는 다음 작업을 수행해야 합니다.
- 이전 버전 대신 새 버전이 처음 로드되는 시간을 식별하고 persistProperties API를 적용합니다.
- setCanDrill API를 사용하여 모든 데이터를 수신하려면 드릴을 사용하지 않도록 설정합니다.

다음 예에서는 이전 시각적 개체를 동적 드릴 제어를 사용하는 시각적 개체로 자체 마이그레이션하는 방법을 보여 줍니다.

capabilities.json 파일에 다음 개체를 추가합니다.

"DrillMigration": {
  "displayName": "Drill Migration",
  "properties": {
      "isMigrated": {
          "displayName": "Is Drill Migrated",
          "type": {
              "bool": true
          }
      }
  }
},

visual.ts 파일에 다음을 추가합니다.

export class Visual implements IVisual {
    //...
      private isCalledToDisableDrillInMigrationScenario = false;
      private drillMigration = { disabledByDefault: true };
      constructor(options: VisualConstructorOptions) {
       //...
       this.host = options.host;
       //...
      }
      private update(options: VisualUpdateOptions) {
         this.handleSelfDrillMigration(options);
          //...
      }
      private handleSelfDrillMigration(options: VisualUpdateOptions): void {
          if (options && options.dataViews && options.dataViews[0] && options.dataViews[0].metadata) {
              const metadata = options.dataViews[0].metadata;
              if (metadata && metadata.dataRoles) {
                  const isDrillDisabled = metadata.dataRoles.isDrillDisabled;
                  if (isDrillDisabled === undefined) {
                      return;
                  }
                  // Continue in case the visual is already migrated
                  if (!metadata.objects?.DrillMigration?.isMigrated) {
                      // Persist the isMigrated property when the drill has the correct state
                      if (this.drillMigration.disabledByDefault === isDrillDisabled) {
                          this.persistMigrationProperty();
                      } else if (!this.isCalledToDisableDrillInMigrationScenario) {
                          // Use the API call only once
                          this.host.setCanDrill(!this.drillMigration.disabledByDefault);
                          this.isCalledToDisableDrillInMigrationScenario = true;
                      }
                  }
              }
          }
      }
      private persistMigrationProperty(): void {
          let property = {
              merge: [{
                  objectName: "DrillMigration",
                  properties: {
                      isMigrated: true
                  },
                  selector: null
              }]
          };
          this.host.persistProperties(property);
      }
  }

이 코드를 추가한 후 처음으로 시각적 개체가 열리면 DrillMigration 변수가 true로 설정되고 시각적 개체가 기본 상태로 열립니다.

고려 사항 및 제한 사항

드릴을 사용하지 않도록 설정한 후에는 드릴 상태가 저장되지 않습니다. 드릴을 사용하지 않도록 설정한 후 다시 사용하도록 설정하면 사용하지 않도록 설정되기 전에 표시되었던 내용에 관계없이 첫 번째 수준만 표시됩니다.
드릴을 사용하지 않도록 설정한 후에는 확장/축소 상태가 저장되지 않습니다. 드릴이 다시 사용하도록 설정되면 모든 행이 축소됩니다.
대시보드에는 API 호출이 지원되지 않습니다.

데이터 뷰 매핑 조건: 드릴이 사용하지 않도록 설정되었을 때 하나의 필드만 표시하도록 시각적 개체를 제한하려면 드릴 가능한 역할의 모든 조건에 대해 "max": 1을 사용합니다. 예시:

범주형 데이터 뷰의 경우:

"conditions": [
     { "category": { "min": 1 }, "measure": { "max": 1 }}
]

행렬 데이터 뷰의 경우:

"conditions": [
    { "Rows": { "max": 0 }, "Columns": { "max": 0 }, "Value": { "min": 1 } },
    { "Rows": { "min": 1 }, "Columns": { "min": 0 }, "Value": { "min": 0 } },
    { "Rows": { "min": 0 }, "Columns": { "min": 1 }, "Value": { "min": 0 } },
]

다음을 통해 공유

동적 드릴 제어

동적 드릴 제어 요구 사항

기존 시각적 개체의 새 버전에 드릴다운 지원 추가

고려 사항 및 제한 사항

피드백

피드백

추가 리소스