Fabric ユーザー データ関数プログラミング モデルの概要 (プレビュー)

Fabric ユーザー データ関数プログラミング モデルは、Fabric で実行可能な関数を作成して発行するために必要な機能を提供する SDK です。 SDK を使用すると、Fabric データ ソースなど、Fabric エコシステム内の他の項目とシームレスに統合することもできます。 このライブラリは PyPI で一般に公開されており、ユーザー データ関数項目にプレインストールされています。

ユーザーデータ機能 SDK

ユーザー データ関数項目には、Fabric ポータル、別の Fabric 項目、または指定された REST エンドポイントを使用して外部アプリケーションから呼び出すことができる 1 つまたは複数の関数が含まれています。 各関数は Python スクリプト内のメソッドであり、パラメーターを渡して呼び出し側に出力を返すことができます。 ユーザー データ関数プログラミング モデルには、次のコンポーネントが含まれています。

• fabric.functions ライブラリには、Python でユーザー データ関数を作成するために必要なコードが用意されています。 新しいユーザー データ関数項目を作成すると、このライブラリが最初の関数テンプレートにインポートされていることがわかります。

• fn.UserDataFunctions() メソッドでは実行コンテキストが提供されます。 これは、すべての新しいユーザー データ関数項目のコード ファイルの先頭で、関数定義の前に追加されます。

  例:

  import datetime
  import fabric.functions as fn
  import logging
  
  udf = fn.UserDataFunctions()
  

• すべての関数は、@udf.function() デコレーターで識別されます。 このデコレーターでは、ポータルまたは外部呼び出し側から関数を個別に呼び出すことができるかどうかを定義します。

  呼び出し可能な関数の例

  # This is a hello fabric function sample that can be invoked from the Fabric portal, another Fabric item, or an external application.
  
  @udf.function()
  def hello_fabric(name: str) -> str:
      logging.info('Python UDF trigger function processed a request.')
      logging.info('Executing hello fabric function.')
  
      return f"Welcome to Fabric Functions, {name}, at {datetime.datetime.now()}!"
  

• @udf.function() デコレーターのない Python メソッドは、直接呼び出すことはできません。 これらは、デコレーターを含む関数からのみ呼び出すことができ、ヘルパー関数として使用できます。

  ヘルパー関数の例

  # This is a helper function that can be invoked from other functions, but can't be invoked or run directly because it doesn't have the @udf.function() decorator
  
  def uppercase_name(name: str) -> str:
      return name.upper()
  

サポートされている入力の種類

str、int、float のようなプリミティブ データ型などの関数の入力パラメーターを定義できます。サポートされている入力データ型は次のとおりです。

サポートされている出力の種類

サポートされている出力データ型は次のとおりです。

Fabric データ ソースへのデータ接続

このモジュールを使用すると、コードに接続文字列を記述することなくデータ接続を参照できます。 fabric.functions ライブラリには、データ接続を処理する 2 つの方法が用意されています。

• fabric.functions.FabricSqlConnection: SQL 分析エンドポイントや Fabric ウェアハウスなど、Fabric の SQL データベースを操作できます。
• fabric.functions.FabricLakehouseClient: レイクハウスを使用して、レイクハウス テーブルとレイクハウス ファイルの両方に接続できます。

データ ソースへの接続を参照するには、@udf.connection デコレーターを使用する必要があります。 次のいずれかの形式で適用できます。

• @udf.connection(alias="<alias for data connection>", argName="sqlDB")
• @udf.connection("<alias for data connection>", "<argName>")
• @udf.connection("<alias for data connection>")

@udf.connection の引数は次のとおりです。

• argName: 接続で関数に使用される変数の名前。
• alias: [接続の管理] メニューで追加した接続のエイリアス。
• argName と alias の値が同じである場合は、@udf.connection("<alias and argName for the data connection>") を使用できます。

例

# Where demosqldatabase is the argument name and the alias for my data connection used for this function
@udf.connection("demosqldatabase")
@udf.function()
def read_from_sql_db(demosqldatabase: fn.FabricSqlConnection)-> list:
  # Replace with the query you want to run
  query = "SELECT * FROM (VALUES ('John Smith', 31), ('Kayla Jones', 33)) AS Employee(EmpName, DepID);"

  # [...] Here is where the rest of your SqlConnection code would be.

  return results

UserDataFunctionContext を使用して呼び出しプロパティを取得する

プログラミング モデルには、UserDataFunctionContext オブジェクトも含まれています。 このオブジェクトには関数呼び出しメタデータが含まれており、特定の呼び出しメカニズム用の特定のアプリ ロジックを作成するために使用できます。

次の表に、UserDataFunctionContext オブジェクトのプロパティを示します。

ExecutingUser オブジェクトには次の情報が含まれています。

UserDataFunctionContext パラメーターにアクセスするには、関数定義の先頭で次のデコレーターを使用する必要があります。@udf.context(argName="<parameter name>")

例

@udf.context(argName="myContext")
@udf.function()
def getContext(myContext: fabric.functions.UserDataFunctionContext)-> str:
    logging.info('Python UDF trigger function processed a request.')
    return f"Hello oid = {context.executing_user['Oid']}, TenantId = {context.executing_user['TenantId']}, PreferredUsername = {context.executing_user['PreferredUsername']}, InvocationId = {context.invocation_id}"

UserThrownError で処理されたエラーをスローする

関数を開発するときに、Python プログラミング モデルで使用できる UserThrownError メソッドを使って、予期されるエラー応答をスローできます。 このメソッドの 1 つの用途は、ユーザーが指定した入力がビジネス検証規則に合格しないケースを管理することです。

例

import datetime

@udf.function()
def raise_userthrownerror(age: int)-> str:
    if age < 18:
        raise fn.UserThrownError("You must be 18 years or older to use this service.", {"age": age})

    return f"Welcome to Fabric Functions at {datetime.datetime.now()}!"

この UserThrownError メソッドは次の 2 つのパラメーターを受け取ります。

• Message: この文字列は、この関数を呼び出しているアプリケーションにエラー メッセージとして返されます。
• この関数を呼び出しているアプリケーションに返されるプロパティのディクショナリ。

次のステップ

• リファレンス API のドキュメント
• Fabric ユーザー データ関数項目を作成する
• ユーザー データ関数のサンプル