Recuperare altri dati da Power BIFetch more data from Power BI

L'API fetchMoreData consente agli oggetti visivi di Power BI di ignorare il limite rigido di 30.000 righe per vista dati.The fetchMoreData API enables Power BI visuals to bypass the hard limit of a 30K rows data view. Con la nuova versione 3.4 dell'API, le funzionalità dell'API fetchMoreData sono state estese per supportare un nuovo approccio di caricamento di blocchi di dati.With the new 3.4 API release, the fetchMoreData API’s functionality is extended to support a new approach of loading data chunks. Oltre all'approccio esistente, che aggrega tutti i blocchi richiesti, l'API supporterà il caricamento dei soli blocchi di dati incrementali.In addition to the existing approach, which aggregates all the chunks requested, the API will support loading only the incremental data chunks.

Il nuovo approccio consente una maggiore flessibilità nella modalità di caricamento di blocchi di dati aggiuntivi nell'oggetto visivo.The new approach allows more flexibility in the way additional data chunks are loaded to the visual. Per migliorare le prestazioni, è possibile configurare le dimensioni dei blocchi in base al caso d'uso.To improve performance, you can configure the chunk size to accommodate your use case.

Limitazioni di fetchMoreDataLimitations of fetchMoreData

  • Le dimensioni della finestra sono limitate a un intervallo compreso tra 2 e 30.000.Window size is limited to a range of 2 to 30,000.
  • Il numero totale di righe della vista dati è limitato a 1.048.576 righe.Dataview total row count is limitd to 1,048,576 rows.
  • Nella modalità di aggregazione dei segmenti, le dimensioni della memoria della vista dati sono limitate a 100 MB.In segments aggregation mode, dataview memory size is limited to 100 MB.

Abilitare un recupero segmentato di set di dati di grandi dimensioniEnable a segmented fetch of large datasets

Per la modalità di segmentazione dataview, definire le dimensioni della finestra per dataReductionAlgorithm nel file capabilities.json dell'oggetto visivo per l'oggetto dataViewMapping necessario.For the dataview segment mode, you define a window size for dataReductionAlgorithm in the visual's capabilities.json file for the required dataViewMapping. count determina le dimensioni della finestra, che limita il numero di nuove righe di dati che possono essere accodate a dataview in ogni aggiornamento.The count determines the window size, which limits the number of new data rows that can be appended to the dataview in each update.

Aggiungere il codice seguente nel file capabilities.json:Add the following code in the capabilities.json file:

"dataViewMappings": [
    {
        "table": {
            "rows": {
                "for": {
                    "in": "values"
                },
                "dataReductionAlgorithm": {
                    "window": {
                        "count": 100
                    }
                }
            }
    }
]

I nuovi segmenti vengono accodati all'oggetto dataview esistente e forniti all'oggetto visivo come chiamata update.New segments are appended to the existing dataview and provided to the visual as an update call.

Uso nell'oggetto visivo di Power BIUsage in the Power BI visual

In Power BI è possibile usare fetchMoreData nella modalità di aggregazione dei segmenti predefinita o nella modalità di aggiornamento incrementale.In Power BI, you can use fetchMoreData in the default segments aggregation mode or in incremental updates mode.

Uso della modalità di aggregazione dei segmenti (predefinita)Using segments aggregation mode (default)

Con questa modalità, la vista dati fornita all'oggetto visivo contiene i dati accumulati per tutte le fetchMoreData requests precedenti.With this mode, the dataview provided to the visual contain the accumulated data for all the previous fetchMoreData requests. Per questo motivo, è previsto che le dimensioni della vista dati aumentino a ogni aggiornamento.Therefore, dataview size is expected to grow with each update. Ad esempio, se sono previste in totale 100.000 righe e le dimensioni della finestra sono impostate su 10.000, la prima vista dati di aggiornamento dovrebbe includere 10.000 righe, la seconda 20.000 righe e così via.For example, if a total of 100,000 rows are expected and the window size is set to 10,000, the first update dataview should include 10,000 rows, the second update dataview should include 20,000 rows, and so on.

Questa modalità viene selezionata chiamando fetchMoreData con aggregateSegments = true.This mode is selected by calling fetchMoreData with aggregateSegments = true.

È possibile determinare se i dati sono presenti verificando l'esistenza di dataView.metadata.segment:You can determine whether data exists by checking for the existence of dataView.metadata.segment:

    public update(options: VisualUpdateOptions) {
        const dataView = options.dataViews[0];
        console.log(dataView.metadata.segment);
        // output: __proto__: Object
    }

È anche possibile verificare se si tratta del primo aggiornamento o di uno successivo controllando options.operationKind.You also can check to see whether it's the first update or a subsequent update by checking options.operationKind. Nel codice seguente, VisualDataChangeOperationKind.Create fa riferimento al primo segmento e VisualDataChangeOperationKind.Append fa riferimento ai segmenti successivi.In the following code, VisualDataChangeOperationKind.Create refers to the first segment and VisualDataChangeOperationKind.Append refers to subsequent segments.

Per un'implementazione di esempio, vedere il frammento di codice seguente:For a sample implementation, see the following code snippet:

// CV update implementation
public update(options: VisualUpdateOptions) {
    // indicates this is the first segment of new data.
    if (options.operationKind == VisualDataChangeOperationKind.Create) {

    }

    // on second or subsequent segments:
    if (options.operationKind == VisualDataChangeOperationKind.Append) {

    }

    // complete update implementation
}

È anche possibile richiamare il metodo fetchMoreData da un gestore eventi dell'interfaccia utente, come illustrato di seguito:You also can invoke the fetchMoreData method from a UI event handler, as shown here:

btn_click(){
{
    // check if more data is expected for the current data view
    if (dataView.metadata.segment) {
        //request for more data if available; as a response, Power BI will call update method
        let request_accepted: bool = this.host.fetchMoreData(true);
        // handle rejection
        if (!request_accepted) {
            // for example, when the 100 MB limit has been reached
        }
    }
}

Come risposta alla chiamata del metodo this.host.fetchMoreData, Power BI chiama il metodo update dell'oggetto visivo con un nuovo segmento di dati.As a response to calling the this.host.fetchMoreData method, Power BI calls the update method of the visual with a new segment of data.

Nota

Per evitare vincoli di memoria del client, Power BI attualmente limita i dati recuperati totali a 100 MB.To avoid client memory constraints, Power BI currently limits the fetched data total to 100 MB. È possibile rilevare il raggiungimento del limite quando fetchMoreData() restituisce false.You can see that the limit has been reached when fetchMoreData() returns false.

Uso della modalità di aggiornamento incrementaleUsing incremental updates mode

Con questa modalità, la vista dati fornita all'oggetto visivo contiene solo dati incrementali.With this mode, the dataview provided to the visual contains just incremental data. Pertanto, le dimensioni della vista dati non supereranno le dimensioni definite per la finestra.Therefore, dataview size would not pass the defined window size. Ad esempio, se è previsto un totale di 101.000 righe e le dimensioni della finestra sono impostate su 10.000, l'oggetto visivo riceverà 10 aggiornamenti con una dimensione della vista dati pari a 10.000 e un aggiornamento con una vista dati di dimensioni pari a 1.000.For example, if a total of 101,000 rows are expected and the window size is set to 10,000, the visual would get 10 updates with a dataview size of 10,000 and one update with a dataview of size 1,000.

Questa modalità viene selezionata chiamando fetchMoreData con aggregateSegments = false.This mode is selected by calling fetchMoreData with aggregateSegments = false.

È possibile determinare se i dati sono presenti verificando l'esistenza di dataView.metadata.segment:You can determine whether data exists by checking for the existence of dataView.metadata.segment:

    public update(options: VisualUpdateOptions) {
        const dataView = options.dataViews[0];
        console.log(dataView.metadata.segment);
        // output: __proto__: Object
    }

È anche possibile verificare se si tratta del primo aggiornamento o di uno successivo controllando options.operationKind.You also can check to see whether it's the first update or a subsequent update by checking options.operationKind. Nel codice seguente, VisualDataChangeOperationKind.Create fa riferimento al primo segmento e VisualDataChangeOperationKind.Segment fa riferimento ai segmenti successivi.In the following code, VisualDataChangeOperationKind.Create refers to the first segment, and VisualDataChangeOperationKind.Segment refers to subsequent segments.

Per un'implementazione di esempio, vedere il frammento di codice seguente:For a sample implementation, see the following code snippet:

// CV update implementation
public update(options: VisualUpdateOptions) {
    // indicates this is the first segment of new data.
    if (options.operationKind == VisualDataChangeOperationKind.Create) {

    }

    // on second or subsequent segments:
    if (options.operationKind == VisualDataChangeOperationKind.Segment) {
        
    }

    // skip overlapping rows 
    const rowOffset = (dataView.table['lastMergeIndex'] === undefined) ? 0 : dataView.table['lastMergeIndex'] + 1;

    // Process incoming data
    for (var i = rowOffset; i < dataView.table.rows.length; i++) {
        var val = <number>(dataView.table.rows[i][0]); // Pick first column               
            
     }
     
    // complete update implementation
}

È anche possibile richiamare il metodo fetchMoreData da un gestore eventi dell'interfaccia utente, come illustrato di seguito:You also can invoke the fetchMoreData method from a UI event handler, as shown here:

btn_click(){
{
    // check if more data is expected for the current data view
    if (dataView.metadata.segment) {
        //request for more data if available; as a response, Power BI will call update method
        let request_accepted: bool = this.host.fetchMoreData(false);
        // handle rejection
        if (!request_accepted) {
            // for example, when the 100 MB limit has been reached
        }
    }
}

Come risposta alla chiamata del metodo this.host.fetchMoreData, Power BI chiama il metodo update dell'oggetto visivo con un nuovo segmento di dati.As a response to calling the this.host.fetchMoreData method, Power BI calls the update method of the visual with a new segment of data.

Nota

Sebbene i dati delle viste dati tra i diversi aggiornamenti siano in gran parte esclusivi, esisteranno alcune sovrapposizioni tra le viste dati successive.Although the dataviews data between the different updates is mostly exclusive, there will be some overlap between subsequent dataviews. Per il mapping dei dati categorico e delle tabelle, è previsto che le prime N righe della vista dati contengano i dati copiati dalla vista dati precedente.For table and categorical data mapping, it is expected the the first N dataview rows will contain data copied from the previous dataview. N può essere determinato in questo modo: (dataView.table['lastMergeIndex'] === undefined) ? 0 : dataView.table['lastMergeIndex'] + 1N can be determined by: (dataView.table['lastMergeIndex'] === undefined) ? 0 : dataView.table['lastMergeIndex'] + 1