動的ドリル制御

動的ドリル制御の機能により、ビジュアルは API 呼び出しを使用してドリル機能を動的に有効または無効にすることができます。 ドリル機能を有効にすると、API 呼び出し、コンテキスト メニューのコマンド、ヘッダーのドリル ボタン、階層データのサポートなど、すべてのドリルダウン機能と展開/折りたたみ機能を使用できます。 無効にすると、これらの機能は使用できません。

次の図に、動的ドリル制御機能が有効および無効になっているビジュアルの例を示します。

動的ドリル制御機能には、次の API 要素が含まれています。

• DataRolesInfo の isDrillDisabled フラグ。

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

• IVisualHost インターフェイス内の setCanDrill メソッド。

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

ドリルが無効になっているかどうかを識別するには、update メソッドで 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 プロパティは、ドリル機能を既定で無効にするかどうかを示します。

既存のビジュアルの新しいバージョンへのドリルダウン サポートの追加

ドリルダウン機能の使うことは、破壊的変更を意味します。 そのため、最もスムーズな切り替えのために、新しいバージョンには新しいビジュアル GUID を使用することをお勧めします。

ただし、同じ GUID を保持する場合は、次の点に留意してください。

• ドリル可能でないバージョンから新しいドリル可能なバージョンに移行する場合、ドリル機能の一部として導入された階層データのサポートにより、dataView に一部のデータが提供されない場合があります。 動的ドリル制御機能では、この問題に対する自動的なサポートは提供されませんが、移行プロセスの管理に使用できます。

• ビジュアルの自己移行の場合、ビジュアルにより次のアクションが実行される必要があります。

  • 古いバージョンではなく新しいバージョンが初めて読み込まれた時点を特定し、persistProperties API を適用します。

  • setCanDrill API を使用して、ドリルを無効にしてすべてのデータを受信します。

次の例は、動的ドリル コントロールを使用するビジュアルに、古いビジュアルを自己移行する方法を示しています。

1. 次のコードを capabilities.json ファイルに追加してください。

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

2. 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 を使用して、ドリルが無効になっている場合にビジュアルが 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 } },
    ]