チュートリアル: トランスリティカルタスクフローを作成する (プレビュー)

2025-05-20

このエンド・ツー・エンドのチュートリアルでは、Fabric内のSQLデータベースにデータを書き戻すための、トランザクションと分析を兼ねたタスクフローの例を作成します。エンドツーエンドのステップアップエクスペリエンスを説明するために、データアノテーションシナリオのトランスライティカルタスクフローに重点を置きます。

このチュートリアルでは、以下の内容を学習します。

Fabric で SQL データベースを作成します。
SQL データベースに書き戻すユーザーデータ関数を構成します。
ユーザーデータ関数を Power BI レポートと統合します。

既存の Fabric 容量がない場合は、 Fabric 試用版を開始します。

注

現在、トランスリティカルタスクフロー機能は一般公開プレビュー中です。

[前提条件]

Power BI と Fabric で必要なプレビュー機能を有効にします。
管理ポータルのテナント設定を使用して、Fabric で SQL データベースを有効にします。
Power BI Desktop。デバイスに Power BI Desktop がインストールされていない場合は、「 Power BI Desktop を取得する」の手順に従います。

概要

変換タスクフローを作成するには、自動化されたシナリオを有効にするには、次の 3 つのタスクが必要です。

データを格納する

既存の Fabric データソースから始めます。このチュートリアルでは、サンプルデータを含む SQL データベースを使用します。
データを開発する

Power BI レポートから呼び出される Fabric ユーザーデータ関数を記述します。この関数は、レポートのデータソースの編集から通知の送信、承認パイプラインでの作業項目の作成まで、任意の数のアクションを実行できます。このチュートリアルでは、新しい製品の説明を受け取って SQL データベースに書き込むユーザーデータ関数を作成します。
データ の視覚化

ソースデータとデータ関数を呼び出す対話型要素を表示する Power BI レポートを作成します。このチュートリアルでは、テキストスライサーを使用してユーザーから製品の説明を収集し、ユーザーデータ関数に送信します。その後、レポートが更新され、更新されたテーブルが表示されます。

SQL Database の作成

このシナリオでは、SQL データベースのサンプル AdventureWorksLT データセットを使用します。

Fabric ポータルでの SQL データベースの作成に関する記事の手順に従います。

SQL データベースに付ける名前を書き留めます。この値は、チュートリアルの後半で使用します。
データベースを作成したら、[ サンプルデータ ] オプションを選択して 、AdventureWorksLT サンプルデータを空のデータベースに読み込みます。

ユーザーデータ関数を作成する

ワークスペースにユーザーデータ関数を作成します。

Power BI または Fabric で、選択したワークスペースに移動します。
[ 新しい項目] を選択します。
[データの開発] グループから [ユーザーデータ関数 (プレビュー)] を選択します。
新しいユーザーデータ関数の名前 ( sqlwriteback など) を指定し、[ 作成] を選択します。

使用する名前とワークスペース名を書き留めます。これらの値は、このチュートリアルの後半で使用します。
[ 新しい関数] を選択します。

SQL Database に接続する

ユーザーデータ関数を、前に作成した SQL データベースに接続します。続行する前に、SQL データベースへのアクセス許可があることを確認してください。

新しいユーザーデータ関数のページで [ 接続の管理 ] を選択します。
[ データ接続の追加] を選択します。
前に作成した AdventureWorksLT SQL データベースを選択し、[ 接続] を選択します。
接続が作成されると、接続のエイリアスが自動的に作成されます。チュートリアルの後半で使用する Alias 値を書き留めます。
[ 接続 ] ページを閉じて、ユーザーデータ関数に戻ります。

関数コードを追加する

SQL データベースの AdventureWorksLT サンプルの [SalesLT].[ProductDescription] テーブルにデータを書き込むためのコードをユーザーデータ関数に追加します。

ユーザーデータ関数は、SQL 接続に既定で pyodbc を使用するため、このシナリオではライブラリを使用することをお勧めします。

ユーザーデータ関数を Power BI ボタンに接続するには、関数が文字列を返す必要があります。

ユーザーデータ関数の既定のコードを次のサンプルに置き換えます。

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"

サンプルで次のコード行を見つけます。

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

エイリアス プレースホルダーを、前のセクションのエイリアス値に置き換えます。

[ 接続の管理 ] ページをもう一度開いて、接続のエイリアスを表示できます。

サンプルコードをテストする

これまでにサンプルコードをテストする場合は、このセクションの手順を使用します。

公開を選択します。
関数が発行されたら、Functions エクスプローラー メニューの write_one_to_sql_db 関数にカーソルを合わせ、[実行] アイコンを選択します。
[ 実行 ] ページで、2 つの必須パラメーターのサンプルデータを指定します。
- productDescription: string
- productModelId: 1 ~ 127 の整数
[実行] を選択します。
関数の出力と生成されたログを確認します。
テストが完了したら、[ 実行 ] ページを閉じます。

サンプルコードの実行時にエラーが発生した場合は、アカウントにデータベースへのアクセス許可があることを確認します。

ユーザーのアクセス許可を付与する (省略可能)

他のユーザーがこの関数を呼び出す Power BI レポートを操作する場合は、関数 の実行 アクセス許可を付与します。

[関数] ページで、[ 共有] を選択します。
[ 作成と送信] リンク ポップアップウィンドウの最初のボックスを選択します。
[追加のアクセス許可] ボックスの一覧から [関数の実行] と [関数ログの表示] を選択し、[適用] を選択します。
[ 名前または電子メールアドレスの入力 ] ボックスに、この関数のアクセス許可を持つユーザーまたはグループを指定します。
[Send] を選択します。

Power BI レポートを作成する

このセクションでは、前のセクションで作成した SQL データベースからデータをプルする Power BI レポートを作成します。

SQL データベースに接続する

レポートのデータソースとして SQL データベースに接続します。

Power BI Desktop で、新しいレポートを作成します。
OneLake Catalog>SQL データベースを選択します。
OneLake カタログ ウィンドウで、前のセクションで作成したデータベースを選択します。たとえば、 AdventureWorksLT です。次に、 [接続] を選択します。
プロンプトに従ってデータベースに対する認証を行います。
データベースに正常に接続すると、[ ナビゲーター ] ウィンドウが開きます。次のテーブルを選択し、[ 読み込み] を選択します。
- SalesLT.ProductDescription
- SalesLT.ProductModel
- SalesLT.ProductModelProductDescription
メッセージが表示されたら、接続モードとして DirectQuery を選択し、[ OK] を選択します。

DirectQuery モードは、レポートがデータを更新し、データの変更を反映できるようにするライブ接続です。詳細については、「 Power BI の DirectQuery」を参照してください。

Power BI レポートを作成する

このセクションでは、Power BI レポートに読み込んだデータを使用してビジュアルを作成します。

[ データ ] メニューで、次の列を選択します。
- SalesLT.ProductModel > Name
- SalesLT.ProductModelProductDescription > ProductModelID
レポートウィンドウに 2 列のテーブルが表示されます。
[視覚化] メニューで、[ テキストスライサー ] アイコンを選択します。

ヒント

テキストスライサーアイコンが表示されない場合は、Power BI Desktop で テキストスライサー プレビュー機能が有効になっていることを確認してください。詳細については、「必要なプレビュー機能」を参照してください。

レポートウィンドウにテキストスライサービジュアルが表示されます。
テキストスライサーを選択し、[ 書式設定] ビジュアル>General>Title オプションを使用して、テキストスライサーに次のタイトルを付けます: Write a new product description。
タスクバーの [ 挿入 ] メニューを選択し、 空白ボタンを レポートに追加します。テキストスライサーの下にボタンをドラッグします。
ボタンを選択し、[書式] ボタン ウィンドウの [アクション] オプションを展開します。 [アクション] ラジオボタンを [オン] にします。

ボタンに次の値を指定します。

パラメーター	価値
タイプ	データ関数を選択
ワークスペース	前のセクションで作成したユーザーデータ関数を含むワークスペースを選択します。
関数セット	データ関数を含む関数セットを選択します。たとえば、 sqlwriteback です。
データ関数	データ関数を選択します。たとえば、 write_one_to_sql_db。

ヒント

[データ関数] オプションが表示されない場合は、Power BI Desktop で Translytical タスクフロープレビュー機能が有効になっていることを確認します。

[データ関数] オプションが表示されていても、ユーザーデータ関数が表示されない場合は、データ関数が文字列を返していることを確認します。

データ関数を選択すると、関数が受け取るパラメーターを表すパラメーターが増えます。次の値を指定します。

パラメーター	価値
productDescription	レポートからテキストスライサーを選択し、新しい製品の説明を記述します。
productModelId	[条件付き書式 (fx)] ボタンを選択します。新しいウィンドウが開きます。 [スタイルの書式設定] パラメーターの場合は、既定の Field 値をそのまま使用します。 [ このパラメーターをどのフィールドに基づかせますか？ ] のパラメーターで、[ All data>SalesLT.ProductModel>ProductModelID ] を選択します。
概要	[ 最大] を選択します。

[ OK] を 選択して、アクションの構成を完了します。 アクションの詳細は次の例のようになります。
ボタンを選択し、[書式] ボタン ウィンドウの [スタイル] オプションを展開します。 [テキスト] ラジオボタンを [オン] にして、ボタンにEnterラベルを付けます。
[ スタイル ] オプションで、[ 設定の適用 ] オプションを [読み込み] に切り替えます。

読み込み状態は、データ関数の実行中に表示されるスタイルオプションを定義するために使用できる、データ関数ボタンで使用できる一意の状態です。
[ テキスト ] メニューを展開し、ボタンのテキスト値を Submittingに置き換えます。
アイコン メニューを展開します。

既定では、データ関数ボタンには、読み込み状態の スピナー アイコンの種類があります。

アイコンのスタイルを次のように変更して調整します。

パラメーター	価値
パディング	左側のパディングを `20 px`に変更します。
アイコンのサイズ	既定の自動値を `20`に置き換えます。

[ 視覚化 ] ウィンドウで、[ テーブル ] アイコンを選択して新しいテーブルを挿入します。
[ データ ] ペインで、テーブルに追加する次の列を選択します。
- SalesLT.ProductModel > Name
- SalesLT.ProductDescription > Description
- SalesLT.ProductDescription > ModifiedDate

レポート変更のオプション

Power BI レポートと同様に、外観をカスタマイズし、このレポートの機能を向上させる方法は多数あります。次のオプションのいくつかを検討してください。

2 つのテーブルにタイトルを追加します。たとえば、製品と製品の説明を選択します。
新しい製品の説明を送信した後、テキストスライサーを自動クリアに設定します。これを行うには、ユーザーデータ関数をトリガーするボタンを選択します。 [ 書式] ボタン>[アクション ] メニューで、[ 自動クリア ] トグルを [オン] に設定します。
ユーザーデータ関数をトリガーした後、レポートの自動参照をオプトアウトします。このシナリオでは、データを更新し、新しい製品の説明が表に表示されるのを確認すると便利です。その他のシナリオでは、レポートを更新する必要がない、または更新したくない場合があります。この設定をオフにするには、ユーザーデータ関数をトリガーするボタンを選択します。 [ 書式] ボタン>[アクション ] メニューで、[ 結果が成功した後にレポートを更新 する] トグルを [オフ] に設定します。

トランスリティカルタスクフローを実行する

Power BI Desktop でトランスリティカルタスクフローの機能をテストできます。ただし、最も正確なエンドユーザーエクスペリエンスを表示する場合は、Power BI サービスにレポートを発行し、Web でテストします。

レポートを発行する

Power BI Desktop でレポートを作成しました。このセクションでは、ユーザーが Web ポータルでレポートを操作できるようにレポートを発行します。

[ホーム] ツールバーメニューの [発行] を選択します。
このレポートを発行する Power BI ワークスペースを選択し、[選択] を 選択します。
レポートの発行が完了したら、 Power BI で [ <REPORT_NAME>.pbix を開く] へのリンクを選択します。
ヒント

Power BI Web ポータルでレポートを開くと、 データソースに資格情報がないためアクセスできないというエラーが表示されることがあります。このエラーを解決するには、次の手順に従います。
1. レポートのセマンティックモデルを開き、 File>Settings に移動します。
2. データソースの資格情報の設定をまだ展開していない場合は、展開してください。
3. [ 資格情報の編集] を選択します。
4. ドロップダウンメニューから 認証方法 を選択します。たとえば、 Basic はユーザー名とパスワードを受け取り、 OAuth2 では現在のアカウントでシングルサインオンを有効にします。
5. 必要な情報があれば入力し、[ サインイン] を選択します。

これで、Power BI サービスで使用できる Power BI レポートにトランスリティカルタスクフローが作成されました。

トランズリティカル・タスクフローを実行する

このセクションでは、Power BI Web ポータルでレポートを操作して、作成したトランスリティカルタスクフローをテストします。

この機能を使用できるのは、データ関数をトリガーする権限を持つユーザーだけです。承認されていないユーザーは 何かがうまくいかなかった という応答を受け取ります。

Power BI でレポートを開きます。
名前と ID を一覧表示する製品テーブルから製品を選択します。この選択は、更新する製品のテキストスライサーにコンテキストを渡します。また、製品の説明テーブルがフィルター処理され、選択した製品の現在の説明がすべて表示されます。
入力テキストボックスに新しい製品の説明を書き込みます。
矢印アイコンを選択するか 、Tab キーを使用して入力を送信します。製品を選択して説明を入力すると、ボタンが有効な状態に切り替わります。
ボタンを選択してユーザーデータ関数を実行します。

トランスリティカルタスクフローが正常に機能した場合 は、レポートに対するアクションが正常に送信されたことを示すメッセージが表示されます。製品の説明テーブルが更新され、新しい説明が表示されます。

変換タスクフローで問題が発生した場合は、問題が発生したことを示すメッセージが表示されます。 [ 詳細の表示] を選択すると、エラーの理由に関する詳細情報が表示されます。関数の実行が失敗する一般的な理由には、次のようなものがあります。

データ検証: 入力値が、ユーザーデータ関数で定義されているデータ検証規則を満たしていません。
タイムアウトエラー: 関数またはプロセスの完了に許容される時間より長い時間がかかります。
不適切なセットアップ: レポート要素 (通常はボタン) の構成中にエラーが発生すると、タスクフローが失敗したり、予期しない結果が発生したりする可能性があります。
承認されていないユーザー: ユーザーには、データ関数をトリガーするアクセス許可がありません。

次のステップ

ワークフローに組み込むことができるトランスリティカルタスクフローのアイデアを得るには、トランスリティカルタスクフローの例を参照してください。
データ関数ボタンを Power BI レポートに統合するためのオプションの詳細については、「 Power BI でデータ関数ボタンを作成する」を参照してください。

次の方法で共有

チュートリアル: トランスリティカルタスクフローを作成する (プレビュー)

[前提条件]

概要

SQL Database の作成

ユーザー データ関数を作成する

SQL Database に接続する

関数コードを追加する

サンプル コードをテストする

ユーザーのアクセス許可を付与する (省略可能)

Power BI レポートを作成する

SQL データベースに接続する

Power BI レポートを作成する

レポート変更のオプション

トランスリティカルタスクフローを実行する

レポートを発行する

トランズリティカル・タスクフローを実行する

次のステップ

フィードバック

その他のリソース

ユーザーデータ関数を作成する

サンプルコードをテストする