動的ドリル制御

[アーティクル]
06/06/2024

Note

この機能は API バージョン 5.7.0 から使用できます。

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

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

ドリルが有効
ドリルが無効

Screenshot of a visual with drilldown disabled displaying each continent with all the countries/regions in that continent displayed under it.

動的ドリル制御機能には、次の 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 プロパティは、ドリル機能を既定で無効にするかどうかを示します。

Note

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

次の方法で共有

動的ドリル制御

動的ドリル制御の要件

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

考慮事項と制限事項

フィードバック

その他のリソース

次の方法で共有

動的ドリル制御

動的ドリル制御の要件

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

考慮事項と制限事項

フィードバック

その他のリソース

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