Data API Builder の構成ファイルを作成する

完了済み

Data API Builder (DAB) は、カスタム コードを記述しなくても、データベース用の最新の REST エンドポイントと GraphQL エンドポイントを作成するクロスプラットフォームのオープンソース エンジンです。 1 つの構成ファイルを使用すると、認証、承認、キャッシュをサポートするセキュリティで保護されたスケーラブルな API を使用して、データベース オブジェクトを公開できます。

Microsoft Fabric で Azure SQL または SQL データベースを使用する場合、アプリケーション開発者がデータにアクセスできるようにする要求に直面している可能性があります。 カスタム API レイヤーの構築には時間がかかり、メンテナンスのオーバーヘッドが増えます。 Data API Builder では、データベース スキーマから直接 API を生成することで、その作業を排除できます。

Data API Builder 構成ファイルについて

Data API Builder のすべてが構成ファイルで始まります。 この JSON ファイルは、DAB にデータベースへの接続方法、公開するオブジェクト、認証の処理方法、実行時の動作方法を示します。 DAB が起動すると、この構成が読み取られ、REST エンドポイントと GraphQL エンドポイントが自動的に生成されます。

一般的な構成ファイルには、次の 4 つの主要なセクションがあります。

  • $schema - 検証と IntelliSense のサポートのために JSON スキーマを参照します
  • データ ソース - データベース接続文字列と種類を定義します
  • runtime - ホスト設定、認証、キャッシュなどのランタイム動作を制御します
  • entities - 公開するデータベース オブジェクトとその構成方法を指定します

基本的な構成ファイルの構造を次に示します。

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/download/v1.1.7/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('DATABASE_CONNECTION_STRING')"
  },
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/api"
    },
    "graphql": {
      "enabled": true,
      "path": "/graphql"
    },
    "host": {
      "cors": {
        "origins": ["http://localhost:3000"],
        "allow-credentials": false
      },
      "authentication": {
        "provider": "StaticWebApps"
      }
    }
  },
  "entities": {}
}

上部の $schema プロパティに注目してください。 これで、入力時にエディターのオートコンプリートと検証が行えます。 DAB のインストールに一致するスキーマ バージョンを常に使用してください。

データ ソース接続を構成する

data-sourceセクションでは、DAB にデータベースへの接続方法を指示します。 Microsoft Fabric の SQL Server、Azure SQL Database、および SQL データベースの場合、データベースの種類として mssql を使用します。

"data-source": {
  "database-type": "mssql",
  "connection-string": "@env('DATABASE_CONNECTION_STRING')",
  "options": {
    "set-session-context": true
  }
}

接続文字列を構成ファイルに直接配置することはできますが、配置しないでください。 環境変数を参照するには、代わりに @env() 構文を使用してください。 これにより、資格情報が構成ファイルとソース管理から除外されます。

set-session-contextオプションは注目に値します。 有効にすると、DAB はセッション コンテキストを介してユーザー ID 情報を SQL Server に渡します。 その後、ストアド プロシージャと関数は、 SESSION_CONTEXT()を使用してこの情報を読み取ることができます。これは、行レベルのセキュリティまたは監査ログの実装に役立ちます。

ヒント

ローカル開発では、 dab init コマンドを --connection-string パラメーターと共に使用して、初期構成ファイルをすばやく設定できます。

ランタイム オプションを設定する

runtime セクションでは、要求を処理するときの DAB の動作を制御します。 ここでは、REST エンドポイントと GraphQL エンドポイントを、CORS やキャッシュなどのグローバル ホスト設定と共に個別に構成します。

"runtime": {
  "rest": {
    "enabled": true,
    "path": "/api",
    "request-body-strict": true
  },
  "graphql": {
    "enabled": true,
    "path": "/graphql",
    "allow-introspection": true
  },
  "host": {
    "cors": {
      "origins": ["https://myapp.azurewebsites.net"],
      "allow-credentials": true
    },
    "mode": "production"
  },
  "cache": {
    "enabled": true,
    "ttl-seconds": 5
  }
}

pathプロパティは、各 API の種類のベース URL パスを定義します。 REST エンドポイントは /api/EntityNameの下に表示され、GraphQL クエリは /graphqlに移動します。 GraphQL の allow-introspection 設定は、クライアントがスキーマ自体にクエリを実行できるかどうかを決定します。これは開発中に役立ちますが、セキュリティのために運用環境では無効にする必要があることがよくあります。

host セクションの CORS (クロスオリジン リソース共有) 設定では、ブラウザー ベースのアプリケーションから API を呼び出すことができるドメインを指定します。 modeプロパティは、developmentとproduction動作を切り替え、詳細なエラー メッセージなどの機能に影響を与えます。

構成管理に DAB CLI を使用する

Data API Builder CLI には、JSON を手動で編集せずに構成ファイルを作成および変更するためのコマンドが用意されています。 この方法では、エラーが軽減され、有効な構成構文が保証されます。

新しい構成ファイルを作成するには:

dab init --database-type mssql --connection-string "@env('DATABASE_CONNECTION_STRING')" --host-mode development

このコマンドは、ベースライン設定を使用して、現在のディレクトリに dab-config.json ファイルを作成します。 そこから、CLI コマンドを使用してエンティティを追加したり、ファイルを直接編集したりできます。

テーブルのエンティティを追加するには:

dab add Product --source dbo.Products --permissions "anonymous:read"

CLI は JSON の書式設定を処理し、スキーマに対して構成を自動的に検証します。 チームで作業している場合、CLI コマンドを使用すると、書式設定の一貫性が維持されるため、pull request レビューも簡単になります。

Important

構成ファイルは常にソース管理に格納しますが、実際の接続文字列はコミットしないでください。 Azure Key Vault やデプロイ パイプライン シークレットなどのセキュリティで保護されたメカニズムを使用して、環境変数参照を使用し、資格情報を管理します。

複数の環境の構成を整理する

ほとんどのプロジェクトでは、開発、ステージング、運用に異なる設定が必要です。 開発中にイントロスペクションを有効にしたが、運用環境では無効にするか、環境ごとに異なる CORS オリジンが必要になる場合があります。

DAB では、構成のマージを通じてこれをサポートしています。 共有設定を含む基本 dab-config.json ファイルから始めて、環境固有のオーバーライドを作成します。

  • dab-config.development.json - 開発固有の設定
  • dab-config.staging.json - ステージング環境の設定
  • dab-config.production.json - 運用設定

--config パラメーターを使用して DAB を起動すると、そのファイルの設定が基本構成とマージされます。

dab start --config dab-config.production.json

環境固有のファイルには、ベースとは異なる設定のみを含める必要があります。 DAB はマージを自動的に処理し、環境固有の値は基本設定よりも優先されます。