Fabricアプリで関数を使う

関数はFabricアプリ内のサーバー上で動作するTypeScript関数です。 ブラウザ上で動作してはならないロジック、例えば秘密の扱い、特権データへのアクセス、アプリのアイデンティティで下流サービスを呼び出す関数などを使いましょう。

各関数は名前で登録され、呼び出し可能なHTTPエンドポイントとして公開されます。 Reactのフロントエンドは型付けされたRayfinクライアントを通じて関数を呼び出すため、リクエストやルーティング、トークン処理を実装する必要はありません。

Note

この記事のコマンドはRayfin CLIのプレビュー版を使用しています。

関数を使うタイミング

レイフィン関数を使って:

  • アプリケーショントークンで外部APIを呼び出します。 例としては、Azure AI Foundry、Azure DevOps、Fabric、Azure Storage、Azure Key Vaultなどがあります。
  • サーバーが強制する行レベルのセキュリティでアプリのデータベースを読み書きします。
  • APIキーやモデル展開名、その他の秘密はクライアントコードから除外しましょう。
  • ファンアウトコール、集約、AIプロンプトなどのオーケストレーションをデータの近くで実行しましょう。

前提条件

始める前に、以下のリソースをインストールするか作成してください:

  • Node.js 20 以降と npm。
  • Rayfin CLIで作成されたFabricアプリのスキャフォールドです。
  • ローカル関数ホストがデバッグに使うAzure Functions Core Toolsです。

Azure Functions Core Tools バージョン 4 をインストールする:

npm install --global azure-functions-core-tools@4

機能付きのアプリを作成してください

アプリをスキャフォールドし、その関数プロジェクトを初期化する:

npm create @microsoft/rayfin@latest

cd my-app

npx rayfin functions init

rayfin functions initコマンドは、既存のアプリに関数プロジェクト、そのTypeScript設定、スターター関数ファイルを追加します。

GitHub Copilotでアプリを構築する

足場にはGitHub Copilotの指示やプロジェクトに必要なスキルが含まれています。 Visual Studio Codeでプロジェクトを開き、GitHub Copilot Chatで作りたいアプリを説明してください。

例えば、次のプロンプトを使ってAIプルリクエストレビューアシスタントを作成します:

Build an app that helps business analysts track sales performance across
regions. Show key metrics, let analysts ask questions about trends, and
use Functions to securely retrieve data from our sales API with application
authentication.

GitHub Copilotは必要なファイルやコンポーネントの生成と更新が可能です。 また、エージェントにアプリの実行、ローカルでのデバッグ、デプロイを依頼することもできます。

プロジェクトのレイアウトを理解する

デフォルトの blankapp スキャフォールドはUniversal App、すなわちnpmワークスペースになります。 関数の初期化は、 rayfin/rayfin.yml を更新し、パッケージの位置を次の順番で選択します: --path、既存の services.functions.path、既存の rayfin/functions ディレクトリ、検出されたワークスペースの場所、またはフラット rayfin/functions デフォルト。

packages/*ワークスペースを持つ新しいユニバーサルアプリでは、検出された場所はpackages/functionsです。 関数の初期化とデータへのオプト後、レイアウトは以下のようになります:

my-app/
├── rayfin/
│   ├── rayfin.yml
│   └── .env
└── packages/
    ├── frontend/
    │   └── src/
    ├── data/
    │   └── src/index.ts
    ├── shared/
    │   └── src/index.ts
    └── functions/
        ├── package.json
        ├── tsconfig.json
        └── src/
            ├── function_app.ts
            └── types.ts

これらのファイルは以下の目的を果たしています。

Path Purpose
rayfin/rayfin.yml 認証、データ、機能、静的ホスティングサービスの設定を行います。
packages/data/src/ 装飾されたランタイムエンティティとそれらのスキーマの登録を含みます。 データはオプトインです。
packages/shared/src/ フロントエンドと共有されるレコード定義およびスキーマタイプを含みます。
packages/functions/package.json 関数の依存関係とビルドスクリプトを定義します。
packages/functions/tsconfig.json 関数用のTypeScriptビルドを設定します。
packages/functions/src/function_app.ts 関数実装を含みます。
packages/functions/src/types.ts 生成されたAppFunctionsSchema型が含まれています。 このファイルは手動で編集しないでください。
packages/frontend/src/ フロントエンドおよび型付きのクライアントコールを含みます。

フラットテンプレートは有効であり、ルート src/、 rayfin/data/、 rayfin/functions/を使用できます。 重複するパッケージを作成するのではなく、設定済みのパスに従ってください。 関数の位置を明示的に選ぶには、npx rayfin functions init --path packages/functionsを使用します。

関数を有効にすると、 rayfin/rayfin.yml 関数サービスが含まれます:

services:
  functions:
    enabled: true
    path: packages/functions
    auth:
      type: application
    buildCommand: npm run build

アプリケーション認証

有効関数は rayfin/rayfin.ymlにおいて明示的なアプリケーション認証を必要とします:

services:
  functions:
    enabled: true
    auth:
      type: application
    buildCommand: npm run build

新しい機能 スキャフォールドセット auth.type: application。

無効関数は authを省略できます。 しかし、 authを提供する場合は以下を含める必要があります:

auth:
  type: application

フルnpx rayfin upと通常のnpx rayfin devフローでこの設定を検証し、その後FabricまたはDockerのバックエンドにプロジェクト設定を適用します。

既存のリモートアプリにYAML認証モードを適用するためにフルの npx rayfin up を実行してください。

デプロイされた関数で使用される認証パス

デプロイド関数は2つの別々の認証経路を使用します:

アクセス パス クレデンシャル ID とアクセス許可
ctx.Tokens.* を介した外部接続 プラットフォーム提供リソーストークン アプリケーション識別子とその外部リソースに対する権限
Rayfin DB 経由で ctx.getDataClient() インヴォケーションのレイフィントークン Rayfin DBにおける発信者の識別と権限

現在のFabricアプリでは、アプリケーション識別はBaaSアイテムの所有者です。

したがって、外部接続はアイテム所有者の権限を利用し、その機能を呼び出すアプリのユーザーの権限ではありません。 Functionsコードで呼び出されるすべての外部リソースとAPIに必要な権限をアプリのアイデンティティに付与します。

オーディエンスを宣言したりFunctionsをデプロイしたりしても、アプリに外部リソースへのアイデンティティ権限が与えられるわけではありません。

アプリのサインインや関数呼び出しの承認は、アプリIDの外部リソースへのアクセスとは別物です。

Rayfin DBアクセスは常にRayfinトークンを使用し、呼び出し元のアイデンティティとデータベース権限を保持します。 services.functions.auth.type: application設定してもRayfin DBへのアクセスはアプリケーションIDに切り替わりません。

オーディエンス宣言、リソーストークン、権限、ローカル開発動作については、「 外部リソースへの接続機能」を参照してください。

アプリをローカルで実行する

アプリのルートフォルダからサインインしてください:

cd my-app
npx rayfin login

フロントエンドを起動し、ローカル関数をホストします:

npm run dev

関数対応プロジェクトでは、 npm run dev が rayfin devにマッピングされます。 このコマンドはスキーマを適用し、ローカル関数ホストを起動し、Vite開発サーバーを起動します。 ターミナルに印刷されたローカルURLを開き、アプリの開発やデバッグを続ける間もターミナルを稼働させ続けてください。

例えばフロントエンドを別々に実行する場合、ホスト関数だけを起動する場合は、代わりに以下のコマンドを使います。

cd my-app
npx rayfin dev functions apply

Fabricにデプロイする

アプリのデータ、静的サイト、機能を展開する:


npx rayfin up --workspace <workspace-name>

<WORKSPACE> を対象の Fabric ワークスペースの名前に置き換えてください。

既存のアプリに機能を追加する

既存のFabricアプリのルートから、機能を有効にして関数プロジェクトを一度だけ初期化します:


npx rayfin functions init

初期化後、設定済みの Functions パッケージ内の src/function_app.ts に実装を追加します(新しいユニバーサルアプリなら packages/functions、フラットアプリなら rayfin/functions)。

Limitations

  • 関数の所有権:関数コードの修正および公開はユーザーデータ関数アイテムの所有者のみです。
  • 公開クールダウン:公開後少なくとも2分は待ってから再度公開してください。 このクールダウンは、ブラウザ内のFunctionsポータル、ユーザーデータ機能のVisual Studio Code拡張機能、Gitインポートアクション、またはデプロイパイプラインからの公開時に適用されます。
  • デプロイメントパッケージのサイズ:FunctionsのZIPファイルは30MBを超えてはなりません。
  • リクエストペイロードサイズ:ユーザーデータ機能は、すべてのリクエストパラメータを合わせて最大4MBと記録しています。 この制限はレイフィン関数にも適用されると予想されていますが、まだ検証されていません。
  • 実行タイムアウト:関数は最大240秒まで実行可能です。
  • 呼び出しログ保持:履歴呼び出しログはデフォルトで30日間保持されます。
  • アプリケーション識別子:アプリケーション識別子は現在、BaaSアイテムの所有者です。

地域ごとの可用性要件やユーザーデータ機能の制限の詳細については、「サービス詳細およびFabricユーザーデータ機能の制限」を参照してください。