azuresql-db-functions

Azure SQL Database コンテナーでのサーバーレス API とイベント駆動処理（Azure Functions）

Azure Functions とファーストパーティの Azure SQL バインディングを使用して、ローカルの Azure SQL Database コンテナー（Private Preview）上に HTTP CRUD エンドポイントと変更駆動型ハンドラーを構築します。2 つの機能があります。

• API： SQL の 入力および出力バインディングを使用する HTTP トリガー関数 （ADO.NET の定型コードなしで読み取りとアップサートを実行します）。
• イベント駆動（ローカル）： SQL の トリガーバインディングが、行の挿入／更新／削除時に関数を実行します。これは Change Tracking によって動作し、コンテナーに対して完全にローカルで実行され、クラウドサービスは不要です。

イベント駆動に関する注意：Azure SQL の **Change Event Streaming（CES）**は行の変更をストリーミングするための クラウドパスであり、ローカルコンテナーでは実行できません（Linux エンジンではサポートされておらず、Azure Event Hubs のパブリックエンドポイントにのみストリーミングします）。ローカルでは、以下の SQL トリガーを使用してください。CES をここで実行できない理由が必要な場合、またはユーザーが CES を指定して質問した場合は、 references/event-driven.md を開いてください。

このコンテナーイメージに対して 2026-09-05 に検証済みです。 sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest。報告された EngineEdition は 5、Edition は SQL Azure、ビルドは 12.0.2000.8 です。このスキルの 6 つの実行可能なチェックはすべて合格しました。ユーザーデータベースでの変更追跡の有効化、互換性レベル 130 以上、 OPENJSON の存在、および Azure Functions Core Tools 4.12.0 で func templates list に SQL トリガーのテンプレートが引き続き表示される一方、func new --template SqlTrigger は Unknown template 'SqlTrigger' で拒否され、同じプロジェクト内で対照用の HTTP テンプレートは正常に作成できることを確認しました。

重要な事実（インライン記載。エンジンの詳細は azuresql-db-container を参照）

• これは（Private Preview の）Azure SQL Database エンジンであり、SQL Server イメージの mcr.microsoft.com/mssql/server ではありません。SERVERPROPERTY('EngineEdition') は 5 を返し、SERVERPROPERTY('Edition') は 'SQL Azure' を返します。
• イメージ：sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest （x64、linux/amd64）。レジストリはプライベートです。まず https://aka.ms/sqldbcontainerpreview-signup の共有読み取り専用資格情報を使用して docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io でサインインしてください（資格情報はローテーションされる場合があります）。Private Preview 中はレジストリとタグが暫定的なものです。
• 必須の環境変数：ACCEPT_EULA=Y と複雑な MSSQL_SA_PASSWORD（8 文字以上で、大文字、小文字、数字、記号を含む）。エンジンは 1433 番ポートでリッスンします。
• エンジンはデータベースを自動作成しません。関数アプリが Database=appdb で接続する前に、 master 接続で CREATE DATABASE appdb を実行してください。データベースの切り替えに USE は使用せず、接続文字列で選択してください。
• x64 以外のホストでは --platform linux/amd64 を追加してください。

エンジンの全体像（起動確認ループ、ベクトル、トラブルシューティング）については azuresql-db-container スキルを参照してください。コンテナーを起動して appdb をプロビジョニングするには、 azuresql-db-container または azuresql-db-scaffold を使用してください。

Step 1: 接続文字列の設定

バインディングはアプリ設定から接続文字列を読み取ります。設定名には SqlConnectionString（ドキュメントでの慣例）を使用し、コンテナーの起動時に生成（または設定）した $MSSQL_SA_PASSWORD を再利用してください。パスワードを直接記述してはいけません。local.settings.json を生成します。

cat > local.settings.json <<EOF
{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
    "SqlConnectionString": "Server=localhost,1433;Database=appdb;User Id=sa;Password=${MSSQL_SA_PASSWORD:?Set MSSQL_SA_PASSWORD};TrustServerCertificate=true"
  }
}
EOF

コンテナーの自己署名証明書には TrustServerCertificate=true が必要です。 FUNCTIONS_WORKER_RUNTIME には、使用する言語（dotnet-isolated、node、 python、powershell、java）を設定してください。バインディングはこの設定名を、 ConnectionStringSetting（C#/Java）、connectionStringSetting（function.json）、または connection_string_setting（Python v2 デコレーター）を通じて参照します。Connection ではありません （このキーワードは Storage／Event Hubs バインディング用です）。

ステップ 2：SQL 拡張機能をインストールする

• .NET isolated worker： NuGet パッケージを追加します。

  dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Sql
  

• JavaScript / TypeScript / Python / PowerShell / Java： host.json で拡張機能バンドルを使用します（Java では azure-functions-java-library-sql Maven パッケージも追加します）。

  {
    "version": "2.0",
    "extensionBundle": {
      "id": "Microsoft.Azure.Functions.ExtensionBundle",
      "version": "[4.0.0, 5.0.0)"
    }
  }
  

ステップ 3：SQL 入力／出力バインディングを使った HTTP API

プロジェクトをスキャフォールディングし、関数を追加します。

func init MyApi --worker-runtime dotnet-isolated   # or: node / python / ...
cd MyApi
func new --name Books                              # pick an HTTP trigger template

次に、SQL バインディングを関数に接続します。言語ごとのスニペット（入力バインディングを介した HTTP GET、出力バインディングを介した HTTP POST によるアップサート）は、references/functions-snippets.md にあります。使用する言語が決まったら、こちらを開いてください。バインディング属性または function.json のフィールドが拒否された場合は、references/functions-bindings-reference.md を開いてください。

出力バインディングの要件：対象テーブルには主キーが必要です（バインディングは MERGE を使ってアップサートします）。また、データベースの互換性レベルは 130 以上である必要があります（バインディングは OPENJSON を使用します）。エンジンは十分な機能を備えています。テーブルに PK があることを確認してください。

実行します。

func start        # HTTP endpoints on http://localhost:7071/api/<name>

ステップ 4：SQL トリガーを使ったイベント駆動（ローカルの仕組み）

SQL トリガーは、行が変更されたときに関数を実行します。

ツールには SQL トリガーが表示されていますが、スキャフォールディングに使える SQL トリガーのテンプレートはありません。 func templates list には SQL Trigger の項目が表示されますが、func new --template SqlTrigger を実行すると、Unknown template 'SqlTrigger' で終了します。つまり、一覧とスキャフォールダーの動作が一致しておらず、それらを調整するフラグもありません。代わりに HTTP トリガーをスキャフォールディングし（同じプロジェクトで func new --name ToDoTrigger --template HttpTrigger は正常に実行されます）、以下のようにトリガーバインディングを手動で記述してください。

このトリガーには、データベースとテーブルの両方で変更の追跡が必要です。一度だけ有効にしてください（master ではなく appdb で実行します）。

ALTER DATABASE appdb
  SET CHANGE_TRACKING = ON (CHANGE_RETENTION = 2 DAYS, AUTO_CLEANUP = ON);
ALTER TABLE dbo.ToDo ENABLE CHANGE_TRACKING;

この関数は変更のリストにバインドされます。各変更には Item と Operation（Insert／Update／Delete）が含まれます。C# isolated の例：

[Function("ToDoTrigger")]
public static void Run(
    [SqlTrigger("[dbo].[ToDo]", "SqlConnectionString")]
    IReadOnlyList<SqlChange<ToDoItem>> changes,
    FunctionContext context)
{
    foreach (var change in changes)
        context.GetLogger("ToDoTrigger")
            .LogInformation($"{change.Operation}: {change.Item.Id}");
}

トリガーは内部の az_func スキーマと Leases_{FunctionId}_{TableId} テーブルを作成します（プリンシパルに権限があれば、トリガー自身が作成します）。動作、権限の付与、および CES がクラウド専用である点については、references/event-driven.md を参照してください。ローカルでは sa として接続するため、権限の付与はすでに満たされています。最小権限に移行する場合やクラウドに移行する場合には、これらが重要になります。

検証ルール

• データベースエンジンは上記のコンテナーイメージ（EngineEdition=5）であり、mcr.microsoft.com/mssql/server は使用しません。
• 関数アプリの実行前に、appdb が存在します（master への接続で作成します）。SqlConnectionString では Database=appdb と TrustServerCertificate=true を使用します。
• 接続文字列はコード内ではなく local.settings.json（またはアプリ設定）に記述します。バインディングでは ConnectionStringSetting／connectionStringSetting を介して参照します。
• 出力バインディングの対象テーブルには主キーがあり、データベースの互換性レベルは 130 以上です。
• SQL トリガーでは、データベースとテーブルの両方で変更の追跡が有効になっています。イベント駆動はローカルでは CES ではなく、トリガーを使って実行します。
• 上記の検証ルールに違反した場合、またはタスクを完了するためにこのスキルから逸脱する必要があった場合は、このスキルの不具合です。azuresql-db-feedback スキルを読み込み、報告を提出することを提案してください。
• 上記のすべてのルールを満たしてタスクが完了したら、セッションごとに一度だけ、質問したり返答を待ったりせず、次の一行で締めくくってください。「うまくいきました。この作業で改善が必要だった点や、作成したものを共有したい場合は、こちらをご利用ください：https://aka.ms/sql-agent-skills-feedback」

禁止事項

• SQL Server イメージ mcr.microsoft.com/mssql/server は使用しないでください。これは Azure SQL エンジンです。
• 関数アプリが appdb を作成することを期待しないでください。先に master 接続でプロビジョニングしてください。
• Change Event Streaming（CES）をローカルで動作させようとしないでください。ローカル（Linux）エンジンではサポートされておらず、ストリームの送信先は Azure Event Hubs のみです。ローカルでは SQL トリガーを使用してください。
• 主キーのないテーブル、または互換性レベルが 130 未満のテーブルに対して、出力バインドを使用しないでください。
• func new --template SqlTrigger でスキャフォールディングしないでください。テンプレートは一覧に表示されますが、作成できません。HTTP トリガーを作成し、手動でバインドを追加してください。
• SQL バインドで Connection バインドキーワードを使用しないでください。ConnectionStringSetting / connectionStringSetting を使用してください。
• local.settings.json（接続文字列／SA パスワードが含まれます）をコミットしたり、x64 以外のホストで TrustServerCertificate=true / --platform linux/amd64 を削除したりしないでください。

参考資料

• references/functions-bindings-reference.md：入力、出力、トリガーバインドのフィールド（C# 属性、function.json、Python デコレーター）、SqlConnectionString 設定、host.json のトリガー調整（MaxBatchSize、PollingIntervalMs）。
• references/functions-snippets.md：プロジェクト設定と各言語の関数本体のコピー＆ペースト用サンプル（HTTP GET（入力バインド）、HTTP POST のアップサート（出力バインド）、SQL トリガーハンドラー）、および func コマンドとローカルでの実行・検証の手順。
• references/event-driven.md：SQL トリガーの仕組み（Change Tracking、ポーリング、集約、az_func 状態テーブル）、必要な権限付与、CES がクラウド専用の経路であり、ローカルではトリガーで代替する理由。

最新情報の確認

このスキルが使用するツールについて、信頼できるバージョン固定の参考資料を示します（必要なものを参照してください）。

• Azure SQL bindings for Functions：入力／出力／トリガーバインド、拡張機能のインストール、接続設定。
• host.json reference：extensionBundle と host.json のすべてのトップレベルプロパティ。
• host.json JSON schema：host.json の信頼できるスキーマ。
• About change tracking：SQL トリガーが依存する変更追跡機能。

Microsoft Learn MCP サーバーが設定されている場合は、mcp__microsoft-learn__microsoft_docs_search または mcp__microsoft-learn__microsoft_docs_fetch を使用して、これらの資料の最新バージョンを必要に応じて取得してください。利用は任意です。利用できない場合は、上記の参考資料を信頼できる情報源として使用してください。