Condividi tramite

Esercitazione: Creare un flusso di attività translitica (anteprima)

In questa esercitazione end-to-end viene creato un flusso di attività translitico di esempio che scrive nuovamente in un database SQL in Fabric. Per illustrare l'esperienza passo per passo da un capo all'altro, ci concentriamo su un flusso di attività analitico interattivo per uno scenario di annotazione dei dati.

In questa esercitazione si apprenderà come:

  • Creare un database SQL in Fabric.
  • Configurare una funzione dati utente che scrive di nuovo in un database SQL.
  • Integrare una funzione dati utente con un report di Power BI.

Se non si ha una capacità di Fabric già esistente, iniziare una prova di Fabric.

Annotazioni

La funzionalità di flusso di attività translytical è attualmente disponibile in anteprima pubblica.

Prerequisiti

Informazioni generali

La creazione di un flusso di attività translitica richiede tre attività per abilitare gli scenari automatizzati:

  • Archiviare i dati

    Iniziare con un'origine dati di Fabric esistente. In questa esercitazione viene usato un database SQL con dati di esempio.

  • Sviluppare dati

    Scrivere una funzione dati utente di Fabric che viene chiamata da un report di Power BI. Questa funzione può eseguire un numero qualsiasi di azioni, dalla modifica dell'origine dati del report all'invio di una notifica alla creazione di un elemento di lavoro in una pipeline di approvazioni. In questa esercitazione viene creata una funzione dati utente che accetta una nuova descrizione del prodotto e la scrive nel database SQL.

  • Visualizzare i dati

    Creare un report di Power BI che visualizzi i dati di origine e gli elementi interattivi che richiamano la funzione dei dati. In questa esercitazione si usa un filtro dei dati di testo per raccogliere la descrizione del prodotto dall'utente e inviarla alla funzione dati utente. Il report viene quindi aggiornato per visualizzare la tabella aggiornata.

Creare un database SQL

Questo scenario usa il set di dati AdventureWorksLT di esempio nel database SQL.

  1. Seguire la procedura descritta in Creare un database SQL nel portale di Infrastruttura.

    Prendere nota del nome assegnato al database SQL. Questo valore verrà usato più avanti nell'esercitazione.

  2. Dopo aver creato il database, scegliere l'opzione Dati di esempio per caricare i dati di esempio AdventureWorksLT nel database vuoto.

Creare una funzione dati utente

Creare una funzione dati utente in un'area di lavoro.

  1. Accedere all'area di lavoro scelta in Power BI o Fabric.

  2. Selezionare Nuovo elemento.

  3. Selezionare Funzioni dati utente nel gruppo Sviluppa dati .

    Una schermata che mostra il riquadro delle funzioni relative ai dati utente nel menu delle nuove voci.

  4. Specificare un nome per la nuova funzione dati utente, ad esempio sqlwriteback, quindi selezionare Crea.

    Prendere nota del nome usato e del nome dell'area di lavoro. Entrambi questi valori verranno usati più avanti nell'esercitazione.

  5. Selezionare Nuova funzione.

Connetti al tuo database SQL

Connettere la funzione dati utente al database SQL creato in precedenza. Assicurarsi di disporre delle autorizzazioni di accesso al database SQL prima di continuare.

  1. Selezionare Gestisci connessioni nella pagina per la nuova funzione dati utente.

    Screenshot che mostra la selezione di

  2. Selezionare Aggiungi connessione dati.

  3. Selezionare il database SQL AdventureWorksLT creato in precedenza, quindi selezionare Connetti.

  4. Quando viene creata la connessione, viene creato automaticamente un alias per la connessione. Prendere nota del valore alias da usare più avanti nell'esercitazione.

    Screenshot che mostra dove trovare l'alias generato automaticamente per la connessione dati.

  5. Chiudere la pagina Connessioni per tornare alla funzione dati utente.

Aggiungere il codice della funzione

Aggiungere codice alla funzione dati utente in modo che scriva i dati nella tabella [SalesLT].[ProductDescription] dell'esempio AdventureWorksLT del database SQL.

Per impostazione predefinita, le funzioni dati utente usano pyodbc per le connessioni SQL ed è consigliabile usare la libreria per questo scenario.

Per connettere una funzione dati utente a un pulsante di Power BI, la funzione deve restituire una stringa.

  1. Sostituire il codice predefinito nella funzione dati utente con l'esempio seguente:

    import fabric.functions as fn
import uuid

udf = fn.UserDataFunctions()

@udf.connection(argName="sqlDB",alias="<REPLACE_WITH_CONNECTION_ALIAS>") 
@udf.function() 

# Take a product description and product model ID as input parameters and write them back to the SQL database
# Users will provide these parameters in the PowerBI report
def write_one_to_sql_db(sqlDB: fn.FabricSqlConnection, productDescription: str, productModelId:int) -> str: 

    # Error handling to ensure product description doesn't go above 200 characters
    if(len(productDescription) > 200):
        raise fn.UserThrownError("Descriptions have a 200 character limit. Please shorten your description.", {"Description:": productDescription})

    # Establish a connection to the SQL database  
    connection = sqlDB.connect() 
    cursor = connection.cursor() 

    # Insert data into the ProductDescription table  
    insert_description_query = "INSERT INTO [SalesLT].[ProductDescription] (Description) OUTPUT INSERTED.ProductDescriptionID VALUES (?)" 
    cursor.execute(insert_description_query, productDescription) 

    # Get the result from the previous query 
    results = cursor.fetchall() 

    # In real-world cases, call an API to retrieve the cultureId
    # For this example, generate a random Id instead
    cultureId = str(uuid.uuid4()) 

    # Insert data into the ProductModelProductDescription table 
    insert_model_description_query = "INSERT INTO [SalesLT].[ProductModelProductDescription] (ProductModelID, ProductDescriptionID, Culture) VALUES (?, ?, ?);" 
    cursor.execute(insert_model_description_query, (productModelId, results[0][0], cultureId[:6])) 

    # Commit the transaction 
    connection.commit() 
    cursor.close() 
    connection.close()  

    return "Product description was added"

  2. Trovare la riga di codice seguente nell'esempio:

    @udf.connection(argName="sqlDB",alias="<REPLACE_WITH_CONNECTION_ALIAS>")

  3. Sostituire il segnaposto alias con il valore alias della sezione precedente.

    È possibile aprire di nuovo la pagina Gestisci connessioni per visualizzare l'alias di connessione.

Testare il codice di esempio

Usare la procedura descritta in questa sezione se si vuole testare il codice di esempio finora.

  1. Seleziona Pubblica.

  2. Dopo la pubblicazione della funzione, passare il puntatore del mouse sulla funzione write_one_to_sql_db nel menu Esplora funzioni , quindi selezionare l'icona Esegui .

  3. Nella pagina Esegui specificare i dati di esempio per i due parametri obbligatori:

    • productDescription: stringa
    • productModelId: intero compreso tra 1 e 127

  4. Selezionare Esegui.

  5. Esaminare l'output della funzione e i log generati.

  6. Chiudere la pagina Esegui al termine del test.

Se si verificano errori durante l'esecuzione del codice di esempio, verificare che l'account disponga delle autorizzazioni di accesso al database.

Concedere le autorizzazioni utente (facoltativo)

Se altri utenti interagiscono con il report di Power BI che chiama questa funzione, concedere loro le autorizzazioni Di esecuzione delle funzioni .

  1. Nella pagina funzioni selezionare Condividi.

  2. Selezionare la prima casella della finestra popup Crea e invia collegamento .

  3. Selezionare Esegui funzioni e Visualizza log funzioni dall'elenco Autorizzazioni aggiuntive e quindi selezionare Applica.

    Screenshot che mostra l'aggiunta delle autorizzazioni

  4. Nella casella Immettere un nome o un indirizzo di posta elettronica specificare gli utenti o i gruppi che si desidera disporre delle autorizzazioni per questa funzione.

  5. Seleziona Invia.

Creare un report di Power BI

In questa sezione viene creato un report di Power BI che esegue il pull dei dati dal database SQL creato nella sezione precedente.

Connettersi al database SQL

Connettersi al database SQL come origine dati per il report.

  1. In Power BI Desktop creare un nuovo report.

  2. Selezionare Catalogo OneLake>database SQL.

    Screenshot che mostra la selezione del database SQL dal catalogo OneLake.

  3. Nella finestra del catalogo OneLake selezionare il database creato nella sezione precedente. Ad esempio, AdventureWorksLT. Selezionare quindi Connetti.

  4. Seguire le istruzioni per eseguire l'autenticazione al database.

  5. Dopo la connessione al database, viene visualizzata la finestra Strumento di navigazione. Selezionare le tabelle seguenti, quindi selezionare Carica:

    • SalesLT.ProductDescription
    • SalesLT.ProductModel
    • SalesLT.ProductModelProductDescription

    Screenshot che mostra il caricamento di tre tabelle dal set di dati di esempio nel report di Power BI.

  6. Quando richiesto, scegliere DirectQuery come modalità di connessione, quindi selezionare OK.

    La modalità DirectQuery è una connessione dinamica che consente al report di aggiornare i dati e riflettere eventuali modifiche ai dati. Per altre informazioni, vedere DirectQuery in Power BI.

Creare il report di Power BI

In questa sezione, crea oggetti visivi con i dati inseriti nel tuo report di Power BI.

  1. Nel menu Dati selezionare le colonne seguenti:

    • SalesLT.ProductModel > Name
    • SalesLT.ProductModelProductDescription > ProductModelID

    Screenshot che mostra la selezione delle colonne 'Name' e 'ProductModelID' da aggiungere al report.

    Nella finestra del report viene visualizzata una tabella a due colonne.

    Screenshot che mostra il report di Power BI con una tabella aggiunta.

  2. Nel menu Visualizzazioni, selezionare l'icona slicer di testo.

    Screenshot che mostra la selezione della visualizzazione

    Suggerimento

    Se l'icona del filtro testo non è visualizzata, assicurati che la funzionalità di anteprima del filtro testo sia abilitata in Power BI Desktop. Per altre informazioni, vedere Funzionalità di anteprima necessarie.

    Nella finestra del report viene visualizzato un oggetto visivo filtro dei dati di testo.

    Screenshot che mostra il report di Power BI con un filtro dei dati di testo aggiunto.

  3. Selezionare il slicer di testo e utilizzare le opzioni Formatta visuale>Titolo per assegnare al slicer di testo il titolo seguente: >.

  4. Sulla barra delle applicazioni selezionare il menu Inserisci e aggiungere un pulsante Vuoto al report. Trascinare il pulsante sotto il filtro testo.

    Screenshot che mostra il report di Power BI con un pulsante aggiunto.

  5. Selezionare il pulsante ed espandere le opzioni Azione nel pannello Formato. Impostare il pulsante di opzione Azione su On.

  6. Specificare i valori seguenti per il pulsante:

    Parametro Valore
    Tipo Selezionare la funzione Dati
    Area di lavoro Selezionare l'area di lavoro contenente la funzione dati utente creata nella sezione precedente.
    Set di funzioni Selezionare il set di funzioni che contiene la funzione di dati. Ad esempio, sqlwriteback.
    Funzione dati Seleziona la funzione dati. Ad esempio, write_one_to_sql_db.

    Suggerimento

    Se l'opzione Funzione dati non è visualizzata, assicurarsi che la funzionalità di anteprima flussi di attività Translytical sia abilitata in Power BI Desktop.

    Se viene visualizzata l'opzione Data function ma non viene visualizzata la funzione dati utente, assicurarsi che la funzione di dati restituisca una stringa.

  7. Dopo aver selezionato la funzione di dati, vengono visualizzati altri parametri per rappresentare i parametri accettati dalla funzione. Specificare i valori seguenti:

    Parametro Valore
    productDescription Selezionare il filtro dei dati di testo dal report, Scrivere una nuova descrizione del prodotto.
    productModelId Selezionare il pulsante Formattazione condizionale (fx). Si apre una nuova finestra.

    Per il parametro Stile formato mantenere il valore predefinito Valore campo .

    Per il parametro Su quale campo dovremmo basarci?, selezionare Tutti i dati>SalesLT.ProductModel>ProductModelID.
    Riepilogo Selezionare Massimo.

  8. Selezionare OK per completare la configurazione dell'azione. I dettagli dell'azione dovrebbero essere simili all'esempio seguente:

    Screenshot che mostra i dettagli della configurazione dell'azione finale.

  9. Selezionare il pulsante ed espandere le opzioni Stile nel riquadro pulsante Formato . Impostare il pulsante di opzione Testo su Attivo ed etichettarlo Enter.

  10. Nelle opzioni Stile modificare l'opzione Applica impostazioni aCaricamento.

    Lo stato di caricamento è uno stato univoco disponibile per i pulsanti della funzione dati che è possibile usare per definire le opzioni di stile visualizzate durante l'esecuzione della funzione di dati.

    Screenshot che mostra la selezione dello stato di caricamento per uno stile del pulsante.

  11. Espandere il menu Testo e sostituire il valore di testo del pulsante con Submitting.

  12. Espandere il menu Icona .

    Per impostazione predefinita, un pulsante della funzione dati ha un tipo di icona Spinner per lo stato di caricamento.

  13. Modificare lo stile dell'icona con le modifiche seguenti:

    Parametro Valore
    Imbottitura Modificare la spaziatura interna sinistra in 20 px.
    Dimensioni icona Sostituire il valore automatico predefinito con 20.

  14. Nel riquadro Visualizzazioni selezionare l'icona Tabella per inserire una nuova tabella.

  15. Nel riquadro Dati selezionare le colonne seguenti da aggiungere alla tabella:

    • SalesLT.ProductModel > Name
    • SalesLT.ProductDescription > Description
    • SalesLT.ProductDescription > ModifiedDate

    Screenshot che mostra il report di Power BI con una seconda tabella aggiunta.

Modifiche facoltative ai report

Come per qualsiasi report di Power BI, esistono molti modi per personalizzare l'aspetto e migliorare le funzionalità di questo report. Considerare alcune di queste opzioni:

  • Aggiungere titoli alle due tabelle. Ad esempio, selezionare un prodotto e unadescrizione del prodotto.
  • Impostare il selettore di testo su cancellazione automatica dopo aver inviato una nuova descrizione del prodotto. A tale scopo, selezionare il pulsante che attiva la funzione dati utente. Nel menu Azione, impostare l'interruttore > del pulsante Formato su Attivato.
  • Rifiutare esplicitamente l'autorefresh per il report dopo aver attivato la funzione dati utente. In questo scenario è utile aggiornare i dati e visualizzare la nuova descrizione del prodotto nella tabella. In altri scenari, potrebbe non essere necessario o voler aggiornare il report. Per disattivare questa impostazione, selezionare il pulsante che attiva la funzione dati utente. Nel menu Azione del >, impostare Aggiorna il report dopo l'attivazione di un esito positivo su Disattivato.

Esegui il flusso di attività translitica

È possibile testare la funzionalità del flusso di attività translitica in Power BI Desktop. Tuttavia, se si vuole visualizzare l'esperienza utente finale più accurata, pubblicare il report nel servizio Power BI e testarlo nel Web.

Pubblicare il report

Il report è stato compilato in Power BI Desktop. In questa sezione si pubblica il report in modo che gli utenti possano interagire con esso nel portale Web.

  1. Nel menu della barra degli strumenti Home selezionare Pubblica.

  2. Selezionare l'area di lavoro di Power BI in cui si vuole pubblicare il report e quindi selezionare Seleziona.

  3. Al termine della pubblicazione del report, selezionare il collegamento Apri <REPORT_NAME.pbix> in Power BI.

    Suggerimento

    Quando si apre il report nel portale Web di Power BI, è possibile che venga visualizzato un errore che indica che l'origine dati manca le credenziali e non è accessibile. Per risolvere questo errore, seguire questa procedura:

    1. Aprire il modello semantico per il report e passare aImpostazioni>.
    2. Espandi l'impostazione Credenziali origine dati se non lo è già espansa.
    3. Selezionare Modifica credenziali.
    4. Scegliere il metodo di autenticazione dal menu a discesa. Ad esempio, Basic accetta un nome utente e una password e OAuth2 abilita l'accesso Single Sign-On con l'account corrente.
    5. Specificare le informazioni necessarie, se presenti, quindi selezionare Accedi.

È ora disponibile un flusso di attività translitica in un report di Power BI disponibile nel servizio Power BI.

Esegui il flusso di attività translitica

In questa sezione si interagisce con il report nel portale Web di Power BI per testare il flusso di attività translitica creato.

Solo gli utenti autorizzati a attivare le funzioni dati possono usare questa funzionalità. Qualunque utente non autorizzato riceve una risposta Qualcosa è andato storto.

  1. Apri il report in Power BI.
  2. Selezionare un prodotto dalla tabella del prodotto che elenca il nome e l'ID. Questa selezione passa il contesto al sezionatore di testi per il prodotto che desideri aggiornare. Si noterà anche che la tabella descrizione prodotto filtra per visualizzare tutte le descrizioni correnti per il prodotto selezionato.
  3. Scrivere una nuova descrizione del prodotto nella casella di testo di input.
  4. Selezionare l'icona della freccia o usare il tasto TAB per inviare l'input. Una volta selezionato un prodotto e viene fornita una descrizione, si noterà che il pulsante passa a uno stato abilitato.
  5. Selezionare il pulsante per eseguire la funzione dati utente.

Se il flusso dell'attività translytical ha funzionato correttamente, viene visualizzato un messaggio che indica l'azione sul report è stata inviata correttamente. La tabella della descrizione del prodotto viene aggiornata per visualizzare la nuova descrizione.

In caso di problemi con il flusso dell'attività translitica, viene visualizzato un messaggio che indica che Si è verificato un errore. Selezionare Visualizza dettagli per ottenere altre informazioni sul motivo dell'errore. Alcuni motivi comuni per un'esecuzione di funzione non riuscita includono:

  • Convalida dei dati: i valori di input non soddisfano le regole di convalida dei dati definite nella funzione dati utente.
  • Errore di timeout: una funzione o un processo richiede più tempo del tempo consentito per il completamento.
  • Configurazione non corretta: gli errori nella configurazione degli elementi del report, in genere il pulsante, possono causare un errore del flusso di attività o risultati imprevisti del prodotto.
  • Utente non autorizzato: l'utente non dispone delle autorizzazioni per attivare la funzione dati.

Passaggi successivi

  • Last updated on