次の方法で共有

データ API ビルダー構成スキーマ リファレンス

  • [アーティクル]

データ API ビルダーのエンジンには構成ファイルが必要です。 Data API Builder 構成ファイルには、API を設定するための構造化された包括的なアプローチが用意されており、環境変数からエンティティ固有の構成まで、すべてを詳しく説明します。 この JSON 形式のドキュメントは、$schema プロパティで始まります。 このセットアップでは、ドキュメントが検証されます。

プロパティ database-type および connection-string により、Azure SQL Database から Cosmos DB NoSQL API へのデータベース システムとのシームレスな統合が保証されます。

構成ファイルには、次のようなオプションを含めることができます。

  • データベース サービスと接続情報
  • グローバル構成オプションとランタイム構成オプション
  • 公開されたエンティティのセット
  • 認証方法
  • ID にアクセスするために必要なセキュリティ規則
  • API とデータベース間の名前マッピング規則
  • 推論できないエンティティ間のリレーションシップ
  • 特定のデータベース サービスに固有の機能

構文の概要

構成ファイルのプライマリ "セクション" の簡単な内訳を次に示します。

{
  "$schema": "...",
  "data-source": { ... },
  "data-source-files": [ ... ],
  "runtime": {
    "rest": { ... },
    "graphql": { .. },
    "host": { ... },
    "cache": { ... },
    "telemetry": { ... },
    "pagination": { ... }
  }
  "entities": [ ... ]
}

最上位のプロパティ

テーブル形式の最上位のプロパティの説明を次に示します。

財産 形容
$schema 検証用の JSON スキーマを指定し、構成が必要な形式に準拠していることを確認します。
データ ソース を する データベース接続の確立に必要な データベースの種類 と 接続文字列に関する詳細が含まれます。
データ ソース ファイル を する 他のデータ ソースを定義する可能性がある他の構成ファイルを指定する省略可能な配列。
ランタイム の REST、GraphQL、ホスト、キャッシュ、および テレメトリのサブプロパティなど、ランタイムの動作と設定を構成します。
エンティティ を する API を介して公開されるエンティティ (データベース テーブル、ビューなど) のセットを定義します。これには、マッピング、アクセス許可、リレーションシップ含まれます。

構成のサンプル

1 つの単純なエンティティに必要なプロパティのみを含むサンプル構成ファイルを次に示します。 このサンプルは、最小限のシナリオを示すことを目的としています。

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('sql-connection-string')"
  },
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [{
          "actions": ["*"],
          "role": "anonymous"
      }]
    }
  }
}

より複雑なシナリオの例については、エンド ツー エンドのサンプル構成を参照してください。

環境

データ API ビルダーの構成ファイルは、ASP.NET Core の appSettings.json ファイルと同様に、複数の環境をサポートする必要があるシナリオをサポートできます。 フレームワークは、3 つの 共通の環境値を提供します。、、および ;ただし、選択した任意の環境値を使用することもできます。 データ API ビルダーが使用する環境は、DAB_ENVIRONMENT 環境変数を使用して構成する必要があります。

ベースライン構成と開発固有の構成が必要な例を考えてみましょう。 この例では、次の 2 つの構成ファイルが必要です。

環境
dab-config.json 基
dab-config.Development.json 発達

開発固有の構成を使用するには、DAB_ENVIRONMENT 環境変数を Developmentに設定する必要があります。

環境固有の構成ファイルは、基本構成ファイルのプロパティ値をオーバーライドします。 この例では、両方のファイルで connection-string 値が設定されている場合、*.Development.json ファイルの値が使用されます。

どちらのファイルでどの値が指定されているか (指定されていないか) に応じて、どの値が使用されるかを理解するには、このマトリックスを参照してください。

基本構成 で指定された 基本構成 で指定されていません
現在の環境構成で指定 現在の環境 現在の環境
現在の環境構成 では指定されていません 基 何一つ

複数の構成ファイルを使用する例については、環境でデータ API ビルダー 使用する方法に関するページを参照してください。

構成プロパティ

このセクションには、構成ファイルで使用できるすべての構成プロパティが含まれています。

スキーマ

親 財産 種類 必須 デフォルト
$root $schema 糸 ✔️ はい 何一つ

各構成ファイルは プロパティで始まり、検証に JSON スキーマを指定します。

形式

{
  "$schema": <string>
}

例

スキーマ ファイルは、特定の URL 0.3.7-alpha 以降のバージョンで使用でき、正しいバージョンまたは使用可能な最新のスキーマを使用していることを確認します。

https://github.com/Azure/data-api-builder/releases/download/<VERSION>-<suffix>/dab.draft.schema.json

VERSION-suffix を目的のバージョンに置き換えます。

https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json

スキーマの最新バージョンは常に https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.jsonで使用できます。

有効なスキーマ値の例をいくつか次に示します。

バージョン URI 形容
0.3.7-alpha https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json アルファ バージョンのツールの構成スキーマを使用します。
0.10.23 https://github.com/Azure/data-api-builder/releases/download/v0.10.23/dab.draft.schema.json ツールの安定したリリースに構成スキーマを使用します。
最新 https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json 最新バージョンの構成スキーマを使用します。

手記

0.3.7-alpha より前のバージョンのデータ API ビルダーでは、スキーマ URI が異なる場合があります。

データ ソース

親 財産 種類 必須 デフォルト
$root data-source 糸 ✔️ はい 何一つ

data-source セクションでは、接続文字列を使用してデータベースとデータベースへのアクセスを定義します。 また、データベース オプションも定義します。 data-source プロパティは、バッキング データベースに接続するために必要な資格情報を構成します。 data-source セクションでは、database-type と connection-stringの両方を指定して、バックエンド データベース接続の概要を示します。

形式

{
  "data-source": {
    "database-type": <string>,
    "connection-string": <string>,
    
    // mssql-only
    "options": {
      "set-session-context": <true> (default) | <false>
    },
    
    // cosmosdb_nosql-only
    "options": {
      "database": <string>,
      "container": <string>,
      "schema": <string>
    }
  }
}

プロパティ

必須 種類
database-type ✔️ はい enum 文字列
connection-string ✔️ はい 糸
options ❌ いいえ オブジェクト

データベースの種類

親 財産 種類 必須 デフォルト
data-source database-type enum-string ✔️ はい 何一つ

データ ソースとして使用するデータベースの種類を指定するために使用される列挙型文字列。

形式

{
  "data-source": {
    "database-type": <string>
  }
}

型の値

type プロパティは、バックエンド データベースの種類を示します。

種類 形容 最小バージョン
mssql Azure SQL Database 何一つ
mssql Azure SQL MI 何一つ
mssql SQL Server SQL 2016
sqldw Azure SQL Data Warehouse 何一つ
postgresql PostgreSQL v11
mysql MySQL v8
cosmosdb_nosql Azure Cosmos DB for NoSQL 何一つ
cosmosdb_postgresql Azure Cosmos DB for PostgreSQL 何一つ

接続文字列

親 財産 種類 必須 デフォルト
data-source connection-string 糸 ✔️ はい 何一つ

ターゲット データベース サービスに接続するための有効な接続文字列を含む 文字列 値です。 バックエンド データベースに接続する ADO.NET 接続文字列。 詳細については、「接続文字列ADO.NET する」を参照してください。

形式

{
  "data-source": {
    "connection-string": <string>
  }
}

接続の回復性

データ API ビルダーは、一時的なエラーを検出した後、データベース要求を自動的に再試行します。 再試行ロジックは、再試行の最大数が 5指数バックオフ 戦略に従います。 後続の要求後の再試行バックオフ期間は、この数式を使用して計算されます (現在の再試行が rであると仮定): $r^2$

この数式を使用すると、再試行の各時間を秒単位で計算できます。

お代わり
First 2
Second 4
Third 8
4 番目の 16
5 番目の 32

Azure SQL と SQL Server

データ API ビルダーは、SqlClient ライブラリを使用して、構成ファイルに指定した接続文字列を使用して Azure SQL または SQL Server に接続します。 サポートされているすべての接続文字列オプションの一覧は、SqlConnection.ConnectionString プロパティです。

データ API ビルダーは、マネージド サービス ID (MSI) を使用してターゲット データベースに接続することもできます。 Azure.Identity ライブラリで定義されている DefaultAzureCredential は、接続文字列でユーザー名またはパスワードを指定しない場合に、既知の ID を使用して接続するために使用されます。 詳細については、 例を参照してください。

例

接続文字列に使用される値は、シナリオで使用されるデータベース サービスによって大きく異なります。 接続文字列はいつでも環境変数に格納し、@env() 関数を使用してアクセスできます。

価値 形容
Azure SQL Database 文字列値を使用する Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>; Azure SQL Database アカウントへの接続文字列。 詳細については、「Azure SQL Database 接続文字列の」を参照してください。
Azure Database for PostgreSQL 文字列値を使用する Server=<server-address>;Database=<name-of-database>;Port=5432;User Id=<username>;Password=<password>;Ssl Mode=Require; Azure Database for PostgreSQL アカウントへの接続文字列。 詳細については、「azure Database for PostgreSQL 接続文字列する」を参照してください。
Azure Cosmos DB for NoSQL 文字列値を使用する AccountEndpoint=<endpoint>;AccountKey=<key>; Azure Cosmos DB for NoSQL アカウントへの接続文字列。 詳細については、「Azure Cosmos DB for NoSQL 接続文字列の」を参照してください。
Azure Database for MySQL 文字列値を使用する Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;Sslmode=Required;SslCa=<path-to-certificate>; Azure Database for MySQL アカウントへの接続文字列。 詳細については、「azure Database for MySQL 接続文字列する」を参照してください。
Access 環境変数の @env('database-connection-string') ローカル コンピューターから環境変数にアクセスします。 この例では、database-connection-string 環境変数が参照されています。

先端

ベスト プラクティスとして、構成ファイルに機密情報を格納しないようにします。 可能な場合は、@env() を使用して環境変数を参照します。 詳細については、@env() 関数を参照してください。

これらのサンプルは、各データベースの種類の構成方法を示しています。 シナリオは一意である可能性がありますが、このサンプルは出発点として適しています。 myserver、myDataBase、mylogin、myPassword などのプレースホルダーを、実際の環境に固有の値に置き換えます。

  • mssql

    "data-source": {
  "database-type": "mssql",
  "connection-string": "$env('my-connection-string')",
  "options": {
    "set-session-context": true
  }
}
    • 一般的な接続文字列形式の: "Server=tcp:myserver.database.windows.net,1433;Initial Catalog=myDataBase;Persist Security Info=False;User ID=mylogin;Password=myPassword;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

  • postgresql

    "data-source": {
  "database-type": "postgresql",
  "connection-string": "$env('my-connection-string')"
}
    • 一般的な接続文字列形式の: "Host=myserver.postgres.database.azure.com;Database=myDataBase;Username=mylogin@myserver;Password=myPassword;"

  • mysql

    "data-source": {
  "database-type": "mysql",
  "connection-string": "$env('my-connection-string')"
}
    • 一般的な接続文字列形式の: "Server=myserver.mysql.database.azure.com;Database=myDataBase;Uid=mylogin@myserver;Pwd=myPassword;"

  • cosmosdb_nosql

    "data-source": {
  "database-type": "cosmosdb_nosql",
  "connection-string": "$env('my-connection-string')",
  "options": {
    "database": "Your_CosmosDB_Database_Name",
    "container": "Your_CosmosDB_Container_Name",
    "schema": "Path_to_Your_GraphQL_Schema_File"
  }
}
    • 一般的な接続文字列形式の: "AccountEndpoint=https://mycosmosdb.documents.azure.com:443/;AccountKey=myAccountKey;"

  • cosmosdb_postgresql

    "data-source": {
  "database-type": "cosmosdb_postgresql",
  "connection-string": "$env('my-connection-string')"
}
    • 一般的な接続文字列形式の: "Host=mycosmosdb.postgres.database.azure.com;Database=myDataBase;Username=mylogin@mycosmosdb;Password=myPassword;Port=5432;SSL Mode=Require;"

手記

database、container、schema など、指定された "オプション" は、PostgreSQL API ではなく Azure Cosmos DB の NoSQL API に固有です。 PostgreSQL API を使用する Azure Cosmos DB の場合、"オプション" には、NoSQL セットアップのように database、container、または schema は含まれません。

オプション

親 財産 種類 必須 デフォルト
data-source options オブジェクト ❌ いいえ 何一つ

特定のデータベース接続用の追加のキー値パラメーターの省略可能なセクション。

形式

{
  "data-source": {
    "options": {
      "<key-name>": <string>
    }
  }
}

例

options セクションが必要かどうかは、使用されているデータベース サービスに大きく依存します。

価値 形容
Azure SQL または SQL Server で SESSION_CONTEXT を有効にする "set-session-context": false Azure SQL および SQL Server の場合、データ API ビルダーは、SESSION_CONTEXT を利用して、ユーザー指定のメタデータを基になるデータベースに送信できます。 このようなメタデータは、アクセス トークンに存在する要求により、Data API ビルダーで使用できます。 SESSION_CONTEXT データは、その接続が閉じられるまで、データベース接続中にデータベースで使用できます。 詳細については、セッション コンテキスト参照してください。 
{
  "data-source"{
    "options": {
        "set-session-context": false
    }
  }
}

データ ソース ファイル

親 財産 種類 必須 デフォルト
$root data-source-files 文字列配列 ❌ いいえ 何一つ

データ API ビルダーは、さまざまなデータ ソースに対して複数の構成ファイルをサポートします。1 つは、runtime 設定を管理する最上位ファイルとして指定されています。 すべての構成で同じスキーマが共有されるため、エラーを発生させずに任意のファイルに runtime 設定できます。 子構成は自動的にマージされますが、循環参照は避ける必要があります。 エンティティは、管理を強化するために個別のファイルに分割できますが、エンティティ間のリレーションシップは同じファイル内に存在する必要があります。

1 つの構成ファイル内で配列として参照される複数の構成ファイルの図。

形式

{
  "data-source-files": [ <string> ]
}

構成ファイルに関する考慮事項

  • すべての構成ファイルに、data-source プロパティを含める必要があります。
  • すべての構成ファイルに、entities プロパティを含める必要があります。
  • runtime 設定は、他のファイルに含まれている場合でも、最上位の構成ファイルからのみ使用されます。
  • 子構成ファイルには、独自の子ファイルを含めることもできます。
  • 構成ファイルは、必要に応じてサブフォルダーに整理できます。
  • エンティティ名は、すべての構成ファイルで一意である必要があります。
  • 異なる構成ファイル内のエンティティ間のリレーションシップはサポートされていません。

例

{
  "data-source-files": [
    "dab-config-2.json"
  ]
}

{
  "data-source-files": [
    "dab-config-2.json", 
    "dab-config-3.json"
  ]
}

サブフォルダーの構文もサポートされています。

{
  "data-source-files": [
    "dab-config-2.json",
    "my-folder/dab-config-3.json",
    "my-folder/my-other-folder/dab-config-4.json"
  ]
}

実行中

親 財産 種類 必須 デフォルト
$root runtime オブジェクト ✔️ はい 何一つ

runtime セクションでは、公開されているすべてのエンティティの実行時の動作と設定に影響するオプションについて説明します。

形式

{
  "runtime": {
    "rest": {
      "path": <string> (default: /api),
      "enabled": <true> (default) | <false>,
      "request-body-strict": <true> (default) | <false>
    },
    "graphql": {
      "path": <string> (default: /graphql),
      "enabled": <true> (default) | <false>,
      "allow-introspection": <true> (default) | <false>
    },
    "host": {
      "mode": "production" (default) | "development",
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      },
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  },
  "cache": {
    "enabled": <true> | <false> (default),
    "ttl-seconds": <integer; default: 5>
  },
  "pagination": {
    "max-page-size": <integer; default: 100000>,
    "default-page-size": <integer; default: 100>,
    "max-response-size-mb": <integer; default: 158>
  },
  "telemetry": {
    "application-insights": {
      "connection-string": <string>,
      "enabled": <true> | <false> (default)
    }
  }
}

プロパティ

必須 種類
rest ❌ いいえ オブジェクト
graphql ❌ いいえ オブジェクト
host ❌ いいえ オブジェクト
cache ❌ いいえ オブジェクト

例

複数の一般的な既定のパラメーターが指定されたランタイム セクションの例を次に示します。

{
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/api",
      "request-body-strict": true
    },
    "graphql": {
      "enabled": true,
      "path": "/graphql",
      "allow-introspection": true
    },
    "host": {
      "mode": "development",
      "cors": {
        "allow-credentials": false,
        "origins": [
          "*"
        ]
      },
      "authentication": {
        "provider": "StaticWebApps",
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<identity-provider-issuer-uri>"
        }
      }
    },
    "cache": {
      "enabled": true,
      "ttl-seconds": 5
    },
    "pagination": {
      "max-page-size": -1 | <integer; default: 100000>,
      "default-page-size": -1 | <integer; default: 100>,
      "max-response-size-mb": <integer; default: 158>
    },
    "telemetry": {
      "application-insights": {
        "connection-string": "<connection-string>",
        "enabled": true
      }
    }
  }
}

GraphQL (ランタイム)

親 財産 種類 必須 デフォルト
runtime graphql オブジェクト ❌ いいえ 何一つ

このオブジェクトは、GraphQL が有効かどうか、およびエンティティを GraphQL 型として公開するために使用される名前を定義します。 このオブジェクトは省略可能であり、既定の名前または設定で十分でない場合にのみ使用されます。 このセクションでは、GraphQL エンドポイントのグローバル設定について説明します。

形式

{
  "runtime": {
    "graphql": {
      "path": <string> (default: /graphql),
      "enabled": <true> (default) | <false>,
      "depth-limit": <integer; default: none>,
      "allow-introspection": <true> (default) | <false>,
      "multiple-mutations": <object>
    }
  }
}

プロパティ

財産 必須 種類 デフォルト
enabled ❌ いいえ ブーリアン 真
path ❌ いいえ 糸 /graphql (既定値)
allow-introspection ❌ いいえ ブーリアン 真
multiple-mutations ❌ いいえ オブジェクト { create: { enabled: false } } }

有効 (GraphQL ランタイム)

親 財産 種類 必須 デフォルト
runtime.graphql enabled ブーリアン ❌ いいえ 何一つ

GraphQL エンドポイントをグローバルに有効または無効にするかどうかを定義します。 グローバルに無効にした場合、個々のエンティティ設定に関係なく、GraphQL 要求を介してアクセスできるエンティティはありません。

形式

{
  "runtime": {
    "graphql": {
      "enabled": <true> (default) | <false>
    }
  }
}

例

この例では、GraphQL エンドポイントはすべてのエンティティに対して無効になっています。

{
  "runtime": {
    "graphql": {
      "enabled": false
    }
  }
}

深度制限 (GraphQL ランタイム)

親 財産 種類 必須 デフォルト
runtime.graphql depth-limit 整数 ❌ いいえ 何一つ

クエリの許容されるクエリの最大深さ。

リレーションシップ定義に基づいて入れ子になったクエリを処理する GraphQL の機能は、ユーザーが複雑で関連するデータを 1 つのクエリでフェッチできるすばらしい機能です。 ただし、ユーザーが入れ子になったクエリを追加し続けるにつれて、クエリの複雑さが増し、最終的にデータベースと API エンドポイントの両方のパフォーマンスと信頼性が損なわれる可能性があります。 このような状況を管理するために、runtime/graphql/depth-limit プロパティは GraphQL クエリの最大許容深度 (および変更) を設定します。 このプロパティを使用すると、開発者はバランスを取ることができ、ユーザーは入れ子になったクエリの利点を享受しながら、システムのパフォーマンスと品質を危険にさらす可能性のあるシナリオを防ぐために制限を設定できます。

例

{
  "runtime": {
    "graphql": {
      "depth-limit": 2
    }
  }
}

パス (GraphQL ランタイム)

親 財産 種類 必須 デフォルト
runtime.graphql path 糸 ❌ いいえ "/graphql"

GraphQL エンドポイントを使用できるようにする URL パスを定義します。 たとえば、このパラメーターが /graphqlに設定されている場合、GraphQL エンドポイントは /graphqlとして公開されます。 既定では、パスは /graphqlです。

大事な

このプロパティのサブパスは使用できません。 GraphQL エンドポイントのカスタマイズされたパス値は現在使用できません。

形式

{
  "runtime": {
    "graphql": {
      "path": <string> (default: /graphql)
    }
  }
}

例

この例では、ルート GraphQL URI が /query。

{
  "runtime": {
    "graphql": {
      "path": "/query"
    }
  }
}

イントロスペクションを許可する (GraphQL ランタイム)

親 財産 種類 必須 デフォルト
runtime.graphql allow-introspection ブーリアン ❌ いいえ 真

このブール型フラグは、GraphQL エンドポイントでスキーマのイントロスペクション クエリを実行する機能を制御します。 イントロスペクションを有効にすると、使用可能なデータの種類、実行できるクエリの種類、使用可能な変更に関する情報をクライアントがスキーマに照会できます。

この機能は、GraphQL API の構造を理解したり、クエリを自動的に生成するツールを開発する際に役立ちます。 ただし、運用環境では、API のスキーマの詳細を隠し、セキュリティを強化することが無効になる場合があります。 既定では、イントロスペクションが有効になっており、GraphQL スキーマを迅速かつ包括的に探索できます。

形式

{
  "runtime": {
    "graphql": {
      "allow-introspection": <true> (default) | <false>
    }
  }
}

例

この例では、イントロスペクションは無効になっています。

{
  "runtime": {
    "graphql": {
      "allow-introspection": false
    }
  }
}

複数の変更 (GraphQL ランタイム)

親 財産 種類 必須 デフォルト
runtime.graphql multiple-mutations オブジェクト ❌ いいえ 何一つ

GraphQL ランタイムのすべての複数の変更操作を構成します。

手記

既定では、複数の変更は有効ではなく、有効にするように明示的に構成する必要があります。

形式

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": <true> (default) | <false>
        }
      }
    }
  }
}

プロパティ

必須 種類
create ❌ いいえ オブジェクト

複数の変更 - 作成 (GraphQL ランタイム)

親 財産 種類 必須 デフォルト
runtime.graphql.multiple-mutations create ブーリアン ❌ いいえ 偽

GraphQL ランタイムの複数の作成操作を構成します。

形式

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": <true> (default) | <false>
        }
      }
    }
  }
}

プロパティ

財産 必須 種類 デフォルト
enabled ✔️ はい ブーリアン 真

例

この例では、GraphQL ランタイムに対して複数の変更が有効になっています。 具体的には、runtime.graphql.multiple-mutations.create.enabled プロパティに true の値を指定することで、複数の作成操作が有効になります。

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": true
        }
      }
    }
  }
}

REST (ランタイム)

親 財産 種類 必須 デフォルト
runtime rest オブジェクト ❌ いいえ 何一つ

このセクションでは、REST エンドポイントのグローバル設定について説明します。 これらの設定は、すべてのエンティティの既定値として機能しますが、それぞれの構成でエンティティごとにオーバーライドできます。

形式

{
  "runtime": {
    "rest": {
      "path": <string> (default: /api),
      "enabled": <true> (default) | <false>,
      "request-body-strict": <true> (default) | <false>
    }
  }
}

プロパティ

財産 必須 種類 デフォルト
enabled ❌ いいえ ブーリアン 真
path ❌ いいえ 糸 /api
request-body-strict ❌ いいえ ブーリアン 真

有効 (REST ランタイム)

親 財産 種類 必須 デフォルト
runtime.rest enabled ブーリアン ❌ いいえ 何一つ

REST エンドポイントのグローバル可用性を決定するブール型フラグ。 無効にした場合、個々のエンティティ設定に関係なく、REST 経由でエンティティにアクセスすることはできません。

形式

{
  "runtime": {
    "rest": {
      "enabled": <true> (default) | <false>,
    }
  }
}

例

この例では、REST API エンドポイントはすべてのエンティティに対して無効になっています。

{
  "runtime": {
    "rest": {
      "enabled": false
    }
  }
}

パス (REST ランタイム)

親 財産 種類 必須 デフォルト
runtime.rest path 糸 ❌ いいえ "/api"

公開されているすべての REST エンドポイントにアクセスするための URL パスを設定します。 たとえば、path を /api に設定すると、REST エンドポイントは /api/<entity>でアクセスできるようになります。 サブパスは許可されません。 このフィールドは省略可能で、既定値として /api。

手記

Static Web Apps (プレビュー) を使用してデータ API ビルダーをデプロイすると、Azure サービスによって、追加のサブパス /data-api が URL に自動的に挿入されます。 この動作により、既存の静的 Web アプリ機能との互換性が確保されます。 結果のエンドポイントは /data-api/api/<entity>。 これは静的 Web Apps にのみ関連します。

形式

{
  "runtime": {
    "rest": {
      "path": <string> (default: /api)
    }
  }
}

大事な

このプロパティでは、ユーザーが指定したサブパスを使用できません。

例

この例では、ルート REST API URI が /data。

{
  "runtime": {
    "rest": {
      "path": "/data"
    }
  }
}

先端

Author エンティティを定義すると、このエンティティのエンドポイントが /data/Authorされます。

要求本文の厳密 (REST ランタイム)

親 財産 種類 必須 デフォルト
runtime.rest request-body-strict ブーリアン ❌ いいえ 真

このブール値フラグは、REST 変更操作の要求本文に余分なフィールドを含めることができるかどうかを決定します。 既定では、この値は true です。つまり、要求本文に追加のフィールドを指定すると、BadRequest 例外が発生します。 ただし、このフラグを false に設定すると、ユーザーは要求本文に追加のフィールドを含めることができます。これは無視されます。 要求本文は常に GET 操作で無視されるため、このフラグは REST クエリ (GET) 要求には影響しません。

手記

このフラグは、REST API エンドポイントへの HTTP GET 要求には影響しません。 GET 操作では、要求本文は常に無視されます。

形式

{
  "runtime": {
    "rest": {
      "request-body-strict": <true> (default) | <false>
    }
  }
}

例

この例では、厳密な要求本文の検証が無効になっています。

{
  "runtime": {
    "rest": {
      "request-body-strict": false
    }
  }
}

ホスト (ランタイム)

親 財産 種類 必須 デフォルト
runtime host オブジェクト ❌ いいえ 何一つ

ランタイム構成内の host セクションには、Data API ビルダーの運用環境に不可欠な設定が用意されています。 これらの設定には、操作モード、CORS 構成、認証の詳細が含まれます。

形式

{
  "runtime": {
    "host": {
      "mode": "production" (default) | "development",
      "max-response-size-mb": <integer; default: 158>,
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      },
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

プロパティ

財産 必須 種類 デフォルト
mode ❌ いいえ enum 文字列 生産
cors ❌ いいえ オブジェクト 何一つ
authentication ❌ いいえ オブジェクト 何一つ

例

開発ホスティング用に構成されたランタイムの例を次に示します。

{
  "runtime": {
    "host": {
      "mode": "development",
      "cors": {
        "allow-credentials": false,
        "origins": ["*"]
      },
      "authentication": {
        "provider": "Simulator"
      }
    }
  }
}

モード (ホスト ランタイム)

親 財産 種類 必須 デフォルト
runtime.host mode 糸 ❌ いいえ "production"

データ API ビルダー エンジンを development モードで実行するか、production モードで実行するかを定義します。 既定値は productionです。

通常、基になるデータベース エラーは、開発中にログの既定の詳細レベルを Debug に設定することで詳細に公開されます。 運用環境では、ログの詳細レベルは Errorに設定されます。

先端

既定のログ レベルは、dab start --LogLevel <level-of-detail>を使用してさらにオーバーライドできます。 詳細については、コマンド ライン インターフェイス (CLI) リファレンスを参照してください。

形式

{
  "runtime": {
    "host": {
      "mode": "production" (default) | "development"
    }
  }
}

価値観

このプロパティで使用できる値の一覧を次に示します。

形容
production Azure での運用環境でのホスティング時に使用する
development ローカル コンピューターでの開発での使用

最大応答サイズ (ランタイム)

親 財産 種類 必須 デフォルト
runtime.host max-response-size-mb 整数 ❌ いいえ 158

特定の結果の最大サイズ (メガバイト単位) を設定します。 この設定により、ユーザーは、基になるデータ ソースからデータをストリーミングするときにホスト プラットフォームのメモリで処理できるデータの量を構成できます。

ユーザーが大規模な結果セットを要求すると、データベースとデータ API ビルダーに負担をかける可能性があります。 これに対処するために、max-response-size-mb を使用すると、開発者は、データ ソースからのデータ ストリームとして、最大応答サイズをメガバイト単位で制限できます。 この制限は、行数ではなく、全体的なデータ サイズに基づいています。 列のサイズはさまざまであるため、一部の列 (テキスト、バイナリ、XML、JSON など) はそれぞれ最大 2 GB を保持できるため、個々の行が非常に大きくなる可能性があります。 この設定は、開発者が応答サイズを制限し、さまざまなデータ型の柔軟性を維持しながらシステムのオーバーロードを防ぐことで、エンドポイントを保護するのに役立ちます。

使用できる値

価値 結果
null nullに設定されていないか明示的に設定されている場合、既定値は 158 メガバイトです。
integer 任意の正の 32 ビット整数がサポートされます。
< 0 サポートされていません。 検証エラーは、1 MB 未満に設定すると発生します。

形式

{
  "runtime": {
    "host": {
      "max-response-size-mb": <integer; default: 158>
    }
  }
}

CORS (ホスト ランタイム)

親 財産 種類 必須 デフォルト
runtime.host cors オブジェクト ❌ いいえ 何一つ

データ API ビルダー エンジン ホストのクロスオリジン リソース共有 (CORS) 設定。

形式

{
  "runtime": {
    "host": {
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      }
    }
  }
}

プロパティ

必須 種類
allow-credentials ❌ いいえ ブーリアン
origins ❌ いいえ 文字列配列

資格情報を許可する (ホスト ランタイム)

親 財産 種類 必須 デフォルト
runtime.host.cors allow-credentials ブーリアン ❌ いいえ 偽

true の場合は、Access-Control-Allow-Credentials CORS ヘッダーを設定します。

手記

CORS ヘッダーの詳細については、MDN Web Docs CORS リファレンス参照してください。

形式

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": <true> (default) | <false>
      }
    }
  }
}

配信元 (ホスト ランタイム)

親 財産 種類 必須 デフォルト
runtime.host.cors origins 文字列配列 ❌ いいえ 何一つ

CORS で許可されるオリジンのリストを含む配列を設定します。 この設定では、すべての配信元に対して * ワイルドカードを使用できます。

形式

{
  "runtime": {
    "host": {
      "cors": {
        "origins": ["<array-of-strings>"]
      }
    }
  }
}

例

すべての配信元からの資格情報なしで CORS を許可するホストの例を次に示します。

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": false,
        "origins": ["*"]
      }
    }
  }
}

認証 (ホスト ランタイム)

親 財産 種類 必須 デフォルト
runtime.host authentication オブジェクト ❌ いいえ 何一つ

データ API ビルダー ホストの認証を構成します。

形式

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  }
}

プロパティ

財産 必須 種類 デフォルト
provider ❌ いいえ enum 文字列 StaticWebApps
jwt ❌ いいえ オブジェクト 何一つ

プロバイダー (ホスト ランタイム)

親 財産 種類 必須 デフォルト
runtime.host.authentication provider 糸 ❌ いいえ "StaticWebApps"

host 構成内の authentication.provider 設定では、データ API ビルダーによって使用される認証方法が定義されます。 リソースへのアクセスを試みるユーザーまたはサービスの ID を API が検証する方法を決定します。 この設定では、さまざまな環境とセキュリティ要件に合わせて調整されたさまざまな認証メカニズムをサポートすることで、デプロイと統合を柔軟に行うことができます。

供給者 形容
StaticWebApps 静的 Web Apps 環境内で実行されている場合にのみ存在する一連の HTTP ヘッダーを検索するように Data API ビルダーに指示します。
AppService ランタイムが Azure AppService でホストされ、AppService 認証が有効で構成されている場合 (EasyAuth)。
AzureAd データ API ビルダー ("サーバー アプリ") に送信された要求を認証できるように、Microsoft Entra Identity を構成する必要があります。 詳細については、「Microsoft Entra ID 認証」を参照してください。
Simulator すべての要求を認証済みとして扱うようにデータ API ビルダー エンジンに指示する構成可能な認証プロバイダー。 詳細については、ローカル認証を参照してください。

形式

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...
      }
    }
  }
}

価値観

このプロパティで使用できる値の一覧を次に示します。

形容
StaticWebApps Azure Static Web Apps
AppService Azure App Service
AzureAD Microsoft Entra ID
Simulator シミュレーター

JSON Web トークン (ホスト ランタイム)

親 財産 種類 必須 デフォルト
runtime.host.authentication jwt オブジェクト ❌ いいえ 何一つ

認証プロバイダーが AzureAD (Microsoft Entra ID) に設定されている場合、このセクションは JSOn Web トークン (JWT) トークンの対象ユーザーと発行者を指定するために必要です。 このデータは、Microsoft Entra テナントに対してトークンを検証するために使用されます。

認証プロバイダーが Microsoft Entra ID に AzureAD 場合に必要です。 このセクションでは、認証の目的の AzureAD テナントに対して受信した JWT トークンを検証するための audience と issuer を指定する必要があります。

設定 形容
聴衆 トークンの目的の受信者を識別します。通常、Microsoft Entra Identity (または ID プロバイダー) に登録されているアプリケーションの識別子。トークンが実際にアプリケーションに対して発行されたことを確認します。
発行者 発行元機関の URL (JWT を発行したトークン サービス) を指定します。 この URL は、JWT が取得された ID プロバイダーの発行者 URL と一致し、トークンの配信元を検証する必要があります。

形式

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

プロパティ

財産 必須 種類 デフォルト
audience ❌ いいえ 糸 何一つ
issuer ❌ いいえ 糸 何一つ

例

データ API ビルダー (DAB) は、Microsoft Entra Identity およびカスタム JSON Web トークン (JWT) サーバーと統合された柔軟な認証サポートを提供します。 この画像では、JWT Server は、サインインが成功したときにクライアントに JWT トークンを発行する認証サービスを表しています。 その後、クライアントはトークンを DAB に渡します。これにより、要求とプロパティを問い合えることができます。

Data API Builder での JSON Web トークンのサポートの図。

ソリューションで行う可能性のあるさまざまなアーキテクチャの選択を host プロパティの例を次に示します。

Azure Static Web Apps
{
 "host": {
  "mode": "development",
  "cors": {
   "origins": ["https://dev.example.com"],
   "credentials": true
  },
  "authentication": {
   "provider": "StaticWebApps"
  }
 }
}

StaticWebAppsでは、データ API ビルダーは Azure Static Web Apps が要求を認証することを想定しており、X-MS-CLIENT-PRINCIPAL HTTP ヘッダーが存在します。

Azure App Service
{
 "host": {
  "mode": "production",
  "cors": {
   "origins": [ "https://api.example.com" ],
   "credentials": false
  },
  "authentication": {
   "provider": "AppService",
   "jwt": {
    "audience": "9e7d452b-7e23-4300-8053-55fbf243b673",
    "issuer": "https://example-appservice-auth.com"
   }
  }
 }
}

認証は、アクセス トークンを発行できるサポートされている ID プロバイダーに委任されます。 取得したアクセス トークンは、Data API ビルダーへの受信要求に含める必要があります。 データ API ビルダーは、提示されたアクセス トークンを検証し、データ API ビルダーがトークンの対象ユーザーであることを確認します。

Microsoft Entra ID
{
 "host": {
  "mode": "production",
  "cors": {
   "origins": [ "https://api.example.com" ],
   "credentials": true
  },
  "authentication": {
   "provider": "AzureAD",
   "jwt": {
    "audience": "c123d456-a789-0abc-a12b-3c4d56e78f90",
    "issuer": "https://login.microsoftonline.com/98765f43-21ba-400c-a5de-1f2a3d4e5f6a/v2.0"
   }
  }
 }
}
シミュレーター (開発専用)
{
 "host": {
  "mode": "development",
  "authentication": {
   "provider": "Simulator"
  }
 }
}

対象ユーザー (ホスト ランタイム)

親 財産 種類 必須 デフォルト
runtime.host.authentication.jwt audience 糸 ❌ いいえ 何一つ

JWT トークンの対象ユーザー。

形式

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "audience": "<client-id>"
        }
      }
    }
  }
}

発行者 (ホスト ランタイム)

親 財産 種類 必須 デフォルト
runtime.host.authentication.jwt issuer 糸 ❌ いいえ 何一つ

JWT トークンの発行者。

形式

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

改ページ (ランタイム)

親 財産 種類 必須 デフォルト
runtime pagination オブジェクト ❌ いいえ 何一つ

改ページ位置の制限を構成します。

形式

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>,
      "default-page-size": <integer; default: 100>
    }
  }
}

プロパティ

財産 必須 種類 デフォルト
max-page-size ❌ いいえ 整数 100,000
default-page-size ❌ いいえ 整数 100

例

{
  "runtime": {
    "pagination": {
      "max-page-size": 100000,
      "default-page-size": 1
    }
  }
}
REST 改ページ位置の例

この例では、REST GET https://localhost:5001/api/books を発行すると、default-page-size が 1 に設定されているため、value 配列内の 1 つのレコードが返されます。 さらに多くの結果が存在する場合、Data API ビルダーは応答に nextLink を追加します。 nextLink には、データの次のページを取得するための $after パラメーターが含まれています。

{
  "value": [
    {
      "id": 1000,
      "title": "Prelude to Foundation",
      "year": 1988,
      "pages": 403,
      "series_id": 10000
    }
  ],
  "nextLink": "https://localhost:5001/api/books?$after=W3siRW50aXR5TmFtZSI6ImJvb2tzIiwiRmllbGROYW1lI=="
}

nextLink を使用すると、クエリ間でデータが変更された場合でも、次の結果セットが確実に返されます。

GraphQL の改ページ位置の例

GraphQL の場合は、改ページ位置の hasNextPage フィールドと endCursor フィールドを使用します。 これらは、次の結果セットをフェッチするために必要です。 指定しない場合でも、クエリは既定のページ サイズに制限されます。

query {
  books {
    items {
      id,
      title,
      year,
      pages,
      series_id
    }
    hasNextPage
    endCursor
  }
}

応答には、hasNextPage フィールドと endCursor フィールドが含まれます。

{
  "data": {
    "books": {
      "items": [
        {
          "id": 1000,
          "title": "Prelude to Foundation",
          "year": 1988,
          "pages": 403,
          "series_id": 10000
        }
      ],
      "hasNextPage": true,
      "endCursor": "W3siRW50aXR5TmFtZSI6ImJvb2tzIiwiRmllbGROYW1lI=="
    }
  }
}

次のページをフェッチするには、次のクエリにカーソル値を含めます。

query {
  books(after: "W3siRW50aXR5TmFtZSI6ImJvb2tzIiwiRmllbGROYW1lI==") {
    items {
      id
      title
      year
      pages
      series_id
    }
    hasNextPage
    endCursor
  }
}

$limit または first を使用して、ページ サイズのを変更します。

REST と GraphQL の両方で、クエリごとの結果の数を調整するための $limit または first パラメーターがサポートされます。 たとえば、https://{server}/api/books?$limit=10 は結果を 10 レコードに制限し、default-page-sizeをオーバーライドします。 $limit が max-page-sizeを超えた場合、結果は max-page-sizeで制限されます。

最初の値 結果
-1 既定値は現在の max-page-size 設定です。
< max-page-size 結果を指定された値に制限します。
0 サポートされていません。
< -1 サポートされていません。
> max-page-size サポートされていません。

最大ページ サイズ (改ページ ランタイム)

親 財産 種類 必須 デフォルト
runtime.pagination max-page-size int ❌ いいえ 100,000

REST または GraphQL によって返される最上位レコードの最大数を設定します。 ユーザーが max-page-sizeを超える要求を行った場合、結果は max-page-sizeで制限されます。

使用できる値

価値 結果
-1 既定値は、サポートされている最大値です。
integer 任意の正の 32 ビット整数がサポートされます。
< -1 サポートされていません。
0 サポートされていません。

形式

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>
    }
  }
}

既定のページ サイズ (改ページ ランタイム)

親 財産 種類 必須 デフォルト
runtime.pagination default-page-size int ❌ いいえ 100

改ページが有効になっているが、明示的なページ サイズが指定されていない場合に返される最上位レコードの既定の数を設定します。

使用できる値

価値 結果
-1 既定値は現在の max-page-size 設定です。
integer 現在の max-page-sizeより小さい任意の正の整数。
< -1 サポートされていません。
0 サポートされていません。

キャッシュ (ランタイム)

親 財産 種類 必須 デフォルト
runtime cache オブジェクト ❌ いいえ 何一つ

ランタイム全体のキャッシュを有効にして構成します。

形式

{
  "runtime": {
    "cache": <object>
  }
}

プロパティ

財産 必須 種類 デフォルト
enabled ❌ いいえ ブーリアン 何一つ
ttl-seconds ❌ いいえ 整数 5

例

この例では、キャッシュが有効になり、項目は 30 秒後に期限切れになります。

{
  "runtime": {
    "cache": {
      "enabled": true,
      "ttl-seconds": 30
    }
  }
}

有効 (キャッシュ ランタイム)

親 財産 種類 必須 デフォルト
runtime.cache enabled ブーリアン ❌ いいえ 偽

すべてのエンティティに対してグローバルにキャッシュを有効にします。 既定値は falseです。

形式

{
  "runtime": {
    "cache":  {
      "enabled": <boolean>
    }
  }
}

例

この例では、キャッシュは無効になっています。

{
  "runtime": {
    "cache": {
      "enabled": false
    }
  }
}

TTL (秒単位) (キャッシュ ランタイム)

親 財産 種類 必須 デフォルト
runtime.cache ttl-seconds 整数 ❌ いいえ 5

キャッシュされた項目の Time-to-Live (TTL) 値を秒単位で構成します。 この時間が経過すると、項目はキャッシュから自動的に排除されます。 既定値は 5 秒です。

形式

{
  "runtime": {
    "cache":  {
        "ttl-seconds": <integer>
    }
  }
}

例

この例では、キャッシュはグローバルに有効になり、すべての項目は 15 秒後に期限切れになります。

{
  "runtime": {
    "cache": {
      "enabled": true,
      "ttl-seconds": 15
    }
  }
}

テレメトリ (ランタイム)

親 財産 種類 必須 デフォルト
runtime telemetry オブジェクト ❌ いいえ 何一つ

このプロパティは、API ログを一元化するように Application Insights を構成します。 その他 について説明します。

形式

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": <true; default: true> | <false>,
        "connection-string": <string>
      }
    }
  }
}

Application Insights (テレメトリ ランタイム)

親 財産 種類 必須 デフォルト
runtime.telemetry application-insights オブジェクト ✔️ はい 何一つ

有効 (Application Insights テレメトリ)

親 財産 種類 必須 デフォルト
runtime.telemetry.application-insights enabled ブーリアン ❌ いいえ 真

接続文字列 (Application Insights テレメトリ)

親 財産 種類 必須 デフォルト
runtime.telemetry.application-insights connection-string 糸 ✔️ はい 何一つ

エンティティ

親 財産 種類 必須 デフォルト
$root entities オブジェクト ✔️ はい 何一つ

entities セクションは、構成ファイルのコアとして機能し、データベース オブジェクトとそれに対応する API エンドポイント間のブリッジを確立します。 このセクションでは、データベース オブジェクトを公開されたエンドポイントにマップします。 このセクションには、プロパティのマッピングとアクセス許可の定義も含まれています。 公開される各エンティティは、専用オブジェクトで定義されます。 オブジェクトのプロパティ名は、公開するエンティティの名前として使用されます。

このセクションでは、プロパティ マッピングやアクセス許可など、データベース内の各エンティティを API で表す方法を定義します。 各エンティティは独自のサブセクション内にカプセル化され、エンティティの名前は構成全体を通じて参照のキーとして機能します。

形式

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true; default: true> | <false>,
        "path": <string; default: "<entity-name>">,
        "methods": <array of strings; default: ["GET", "POST"]>
      },
      "graphql": {
        "enabled": <true; default: true> | <false>,
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": <"query" | "mutation"; default: "query">
      },
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": <array of strings>,
        "parameters": {
          "<parameter-name>": <string | number | boolean>
        }
      },
      "mappings": {
        "<database-field-name>": <string>
      },
      "relationships": {
        "<relationship-name>": {
          "cardinality": <"one" | "many">,
          "target.entity": <string>,
          "source.fields": <array of strings>,
          "target.fields": <array of strings>,
          "linking.object": <string>,
          "linking.source.fields": <array of strings>,
          "linking.target.fields": <array of strings>
        }
      },
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role-name">,
          "actions": <array of strings>,
          "fields": {
            "include": <array of strings>,
            "exclude": <array of strings>
          },
          "policy": {
            "database": <string>
          }
        }
      ]
    }
  }
}

プロパティ

必須 種類
source ✔️ はい オブジェクト
permissions ✔️ はい 配列
rest ❌ いいえ オブジェクト
graphql ❌ いいえ オブジェクト
mappings ❌ いいえ オブジェクト
relationships ❌ いいえ オブジェクト
cache ❌ いいえ オブジェクト

例

たとえば、この JSON オブジェクトは、Author という名前の GraphQL エンティティと、/Author パスを介して到達可能な REST エンドポイントを公開するように Data API ビルダーに指示します。 dbo.authors データベース テーブルはエンティティをバックアップし、構成により、すべてのユーザーがエンドポイントに匿名でアクセスできるようになります。

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "*"
            }
          ]
        }
      ]
    }
  }
}

この例では、User エンティティを宣言します。 この名前 User は、エンティティが参照される構成ファイル内の任意の場所で使用されます。 それ以外の場合、エンティティ名はエンドポイントに関連しません。

{
  "entities": {
    "Book": {
      "rest": {
        "enabled": true,
        "path": "/books",
        "methods": ["GET", "POST", "PUT"]
      },
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "Book",
          "plural": "Books"
        },
        "operation": "query"
      },
      "source": {
        "object": "BooksTable",
        "type": "table",
        "key-fields": ["Id"],
        "parameters": {}
      },
      "mappings": {
        "id": "Id",
        "title": "Title",
        "authorId": "AuthorId"
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"],
          "fields": {
            "include": ["id", "title"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userId eq @item.authorId"
          }
        },
        {
          "role": "admin",
          "actions": ["create", "read", "update", "delete"],
          "fields": {
            "include": ["*"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userRoles has 'BookAdmin'"
          }
        }
      ]
    }
  }
}

源

親 財産 種類 必須 デフォルト
entities.{entity} source オブジェクト ✔️ はい 何一つ

{entity}.source 構成は、API で公開されているエンティティとその基になるデータベース オブジェクトを接続します。 このプロパティは、エンティティが表すデータベース テーブル、ビュー、またはストアド プロシージャを指定し、データの取得と操作のための直接リンクを確立します。

エンティティが 1 つのデータベース テーブルまたはコレクションに直接マップされる単純なシナリオでは、ソース プロパティにはそのデータベース オブジェクトの名前のみが必要です。 このシンプルさにより、一般的なユース ケースの迅速なセットアップが容易になります。

形式

{
  "entities": {
    "<entity-name>": {
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">, 
        "key-fields": <array of strings>,
        "parameters": {
          "<name>": <string | number | boolean>
        }
      }
    }
  }
}

プロパティ

必須 種類
object ✔️ はい 糸
type ✔️ はい enum 文字列
parameters ❌ いいえ オブジェクト
key-fields ❌ いいえ 文字列配列

例

この例では、エンティティをソース テーブルに関連付ける最も簡単な構造を示します。

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      }
    }
  }
}

多対多リレーションシップの例を次に示します。

複数のデータベース テーブル間の多対多リレーションシップの図 

{
  "entities": {
    "Todo": {
      "type": "stored-procedure",
      "source": {
        "type": "stored-procedure",
        "object": "GetUserTodos"
      },
      "parameters": {
        "UserId": 0, 
        "Completed": null,
        "CategoryName": null
      },
      "mapping": {
        "Id": "todo_id",
        "Title": "todo_title",
        "Description": "todo_description",
        "Completed": "todo_completed"
      }
    }
  }
}
  • ストアド プロシージャによってサポートされる Todo エンティティ。
  • ソース内の type プロパティは stored-procedureに設定され、エンティティがマップされるソース オブジェクトの種類を示します。
  • ソース内の object プロパティは、データベース内のストアド プロシージャの名前です。

また、この例では、(省略可能) mapping プロパティが "Todo" エンティティの構成に追加されます。 エンティティ (Id、Title、Description、および Completed) のフィールドが、基になるデータ ソースまたはストアド プロシージャ パラメーター (todo_id、todo_title、todo_description、および todo_completed) 内の対応するフィールドにどのようにマップされるかを指定します。 このマッピングにより、作成/更新操作中にエンティティとストアド プロシージャの間で正しいデータが確実に渡されます。

前の例では、次の SQL プロシージャを使用します。

CREATE PROCEDURE GetUserTodos
    @UserId INT,
    @Completed BIT = NULL,
    @CategoryName NVARCHAR(100) = NULL
AS
BEGIN
    SELECT t.*
    FROM Todo t
    INNER JOIN users_todos ut ON t.id = ut.todo_id
    INNER JOIN Category c ON t.category_id = c.id
    WHERE ut.user_id = @UserId
    AND ISNULL(@Completed, t.completed)
    AND ISNULL(@CategoryName, c.name)
END
  • @UserId: 既定値のない必須パラメーター。
  • @Completed: 省略可能なパラメーター。 指定した場合は、完了状態によって todos がフィルター処理されます。
  • @CategoryName: 省略可能なパラメーター。 指定した場合は、カテゴリ名で todos をフィルター処理します。

ストアド プロシージャを使用した更新の例を次に示します。

{
  "entities": {
    "Todo": {
      "type": "stored-procedure",
      "source": {
        "object": "UpsertTodo"
      },
      "method": "POST", // Specify the HTTP method as POST
      "parameters": {
        "Id": 0,
        "Title": null,
        "Description": null,
        "Completed": null
      }
    }
  }
}

この例では、このエンティティと対話するための HTTP メソッドを、メソッド プロパティを使用して POST するように明示的に設定します。

CREATE PROCEDURE UpsertTodo
    @Id INT,
    @Title NVARCHAR(100),
    @Description NVARCHAR(255),
    @Completed BIT
AS
BEGIN
    SET NOCOUNT ON;

    MERGE INTO Todo AS target
    USING (VALUES (@Id, @Title, @Description, @Completed)) AS source (Id, Title, Description, Completed)
    ON target.Id = source.Id
    WHEN MATCHED THEN
        UPDATE SET
            Title = source.Title,
            Description = source.Description,
            Completed = source.Completed
    WHEN NOT MATCHED THEN
        INSERT (Id, Title, Description, Completed)
        VALUES (source.Id, source.Title, source.Description, source.Completed);
END;

オブジェクト

親 財産 種類 必須 デフォルト
entities.{entity}.source object 糸 ✔️ はい 何一つ

使用するデータベース オブジェクトの名前。

例

この例では、object はデータベース内の dbo.books オブジェクトを参照します。

{
  "entities": {
    "Book": {
      "source": {
        "object": "dbo.books",
        "type": "table"
      }
    }
  }
}

型 (エンティティ)

親 財産 種類 必須 デフォルト
entities.{entity}.source type 糸 ✔️ はい 何一つ

type プロパティは、エンティティの背後にあるデータベース オブジェクトの種類を識別します。これには、view、table、および stored-procedureが含まれます。 type プロパティは必須であり、既定値はありません。

形式

{
  "entities": {
    "<entity-name>": {
      "type": <"view" | "stored-procedure" | "table">
    }
  }
}

価値観

このプロパティで使用できる値の一覧を次に示します。

形容
table テーブルを表します。
stored-procedure ストアド プロシージャを表します。
view ビューを表します。

例

この例では、type は、このソースがデータベース内のビューであることを示します。 この値は、他の値 (例: key-fields) が必要かどうかに影響します。

{
  "entities": {
    "Category": {
      "source": {
        "object": "dbo.vw_category_details",
        "type": "view",
        "key-fields": [
          "category_id"
        ]
      }
    }
  }
}

キー フィールド

親 財産 種類 必須 デフォルト
entities.{entity}.source key-fields 文字列配列 ❌ いいえ 何一つ

{entity}.key-fields 設定は、ビューによってサポートされるエンティティに必要であるため、データ API ビルダーは、必要に応じて 1 つの項目を識別して返す方法を認識します。 type が key-fieldsなしで view に設定されている場合、データ API ビルダー エンジンは開始を拒否します。

大事な

このプロパティは、オブジェクトの型が viewの場合に必要です。 また、このプロパティは、オブジェクトの型が主キーが定義されていない table である必要があります。

形式

{
  "entities": {
    "<entity-name>": {
      "source": {
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": <array of strings>
      }
    }
  }
}

例

この例では、キー フィールドとして category_id が示されている dbo.vw_category_details ビューを使用します。

{
  "entities": {
    "Category": {
      "source": {
        "object": "dbo.vw_category_details",
        "type": "view",
        "key-fields": [
          "category_id"
        ]
      }
    }
  }
}

パラメーター

親 財産 種類 必須 デフォルト
entities.{entity}.source parameters オブジェクト ❌ いいえ 何一つ

{entity}.source.parameters 設定は、ストアド プロシージャによってサポートされるエンティティにとって重要であり、開発者はパラメーターとその既定値を指定できます。 パラメーターにより、特定のパラメーターが HTTP 要求内で指定されていない場合、システムはこれらの定義済みの値にフォールバックできます。

大事な

このプロパティは、オブジェクトの型が stored-procedureの場合に必要です。

形式

{
  "entities": {
    "<entity-name>": {
      "source": {
        "type": "stored-procedure",
        "parameters": {
          "<parameter-name-1>": <string | number | boolean>,
          "<parameter-name-2>": <string | number | boolean>,
          "<parameter-name-3>": <string | number | boolean>
        }
      }
    }
  }
}

例

この例では、次の 2 つのパラメーターを渡す dbo.stp_get_bestselling_books ストアド プロシージャを呼び出します。

価値
depth 25
list contoso-best-sellers 
{
  "entities": {
    "BestsellingBooks": {
      "source": {
        "object": "dbo.stp_get_bestselling_books",
        "type": "stored-procedure",
        "parameters": {
          "depth": 25,
          "list": "contoso-best-sellers"
        }
      }
    }
  }
}

権限

親 財産 種類 必須 デフォルト
entities.{entity} permissions オブジェクト ✔️ はい 何一つ

このセクションでは、関連エンティティにアクセスできるユーザーと、許可されるアクションを定義します。 このセクションでは、ロールの観点からアクセス許可を定義します。 アクションは、create、read、update、deleteなどの一般的な CRUD 操作として定義されます。 permissions セクションでは、(ロールの観点から) 関連エンティティにアクセスできるユーザーと、どのアクションを使用できるかを定義します。 アクションは、通常の CRUD 操作です。create、read、update、delete。

形式

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "actions": <["create", "read", "update", "delete", "execute", "*"]>
        }
      ]
    }
  }
}
アクション 形容
create エンティティに新しいレコードを作成できるようにします。
read エンティティからのレコードの読み取りまたは取得を許可します。
update エンティティ内の既存のレコードの更新を許可します。
delete エンティティからレコードを削除できます。
execute エンティティに関連するストアド プロシージャまたは操作の実行を許可します。
* 適用可能なすべての CRUD 操作を許可します

例

この例では、匿名ロールが定義され、考えられるすべてのアクションにアクセスできます。

{
  "entities": {
    "Writer": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

文字列とオブジェクト配列のアクションを組み合わせることもできます。

{
  "entities": {
    "Reviewer": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            },
            "create"
          ]        
        }
      ]
    }
  }
}

匿名ロール 匿名ユーザーが secret-fieldを除くすべてのフィールドを読み取ることを許可します。 "exclude": ["secret-field"] で "include": ["*"] を使用すると、他のすべてのフィールドへのアクセスを許可しながら、匿名ユーザーから secret-field が効果的に非表示になります。

認証済みロール 認証されたユーザーが特定のフィールドの読み取りと更新を許可します(id、title、secret-fieldを明示的に含みますが、secret-fieldは除きます)。 明示的な包含とその後の secret-fieldの除外を示し、excludeの優先順位を示します。 secret-field は両方とも含まれ、除外されるため、アクセスできなくなります。これは、優先される exclude の目的のルールに一致します。

作成者ロール 作成者は、すべてのフィールドに * すべての操作を除外せずに実行できます。 このファイルは、空の "exclude": [] 配列を持つ "include": ["*"] が、明示的に除外されるフィールドがないため、すべてのフィールドへのアクセスを許可することを示します。

何も指定されていない場合、この構成は既定値を表します。

"fields": {
  "include": [],
  "exclude": []
}

これは実質的に次と同じです。

"fields": {
  "include": [ "*" ],
  "exclude": []
}

また、次のセットアップも検討してください。

"fields": {
  "include": [],
  "exclude": ["*"]
}

前の構成では、フィールドが明示的に含まれていない ("include": [] が空で、フィールドが許可されていないことを示す) と、すべてのフィールドが除外されることを実質的に指定しています ("exclude": ["*"] はワイルドカード * を使用してすべてのフィールドを示します)。

実際の使用: このような構成は、すべてのフィールドへのアクセスを制限するため、直感に反しているように見える場合があります。 ただし、ロールがエンティティの作成などの特定のアクションを実行する可能性があるシナリオでは、データにアクセスせずに使用できます。

同じ動作ですが、構文は異なります。

"fields": {
  "include": ["Id", "Title"],
  "exclude": ["*"]
}

前のセットアップでは、Id フィールドと Title フィールドのみを含める必要があることを指定する一方で、exclude セクションのすべてのフィールドをワイルドカード * で除外する必要があることを示しています。 同じロジックを表すもう 1 つの方法は次のとおりです。

"fields": {
  "include": ["Id", "Title"],
  "exclude": ["Id", "Title"]
}

exclude リストが include リストよりも優先されるという一般的なルールを考えると、通常、exclude: ["*"] を指定すると、include セクションにリストされているフィールドであっても、すべてのフィールドが除外されることを意味します。 したがって、一見すると、除外ルールが優先されるため、この構成ではフィールドにアクセスできないように見える場合があります。

逆: 許可する場合、Id フィールドと Title フィールドにのみアクセスする場合は、include セクションのフィールドのみを指定し、ワイルドカードで exclude を使用しない方が明確で信頼性が高くなります。 または、システムのアクセス許可ロジックを調整して、設計を制御していると仮定して、このようなケースに明示的に対応することもできます。 例えば：

"fields": {
  "include": ["Id", "Title"],
  "exclude": []
}

プロパティ

必須 種類
role ✔️ はい 糸
actions (文字列配列) または actions (オブジェクト配列) ✔️ はい オブジェクトまたは文字列配列

役割

親 財産 種類 必須 デフォルト
entities.permissions role 糸 ✔️ はい 何一つ

定義されたアクセス許可が適用されるロールの名前を含む文字列。 role 文字列には、定義されたアクセス許可が適用されるロールの名前が含まれます。

ロールは、要求を実行するアクセス許可コンテキストを設定します。 ランタイム構成で定義されているエンティティごとに、REST エンドポイントと GraphQL エンドポイントの両方でエンティティにアクセスする方法を決定するロールと関連するアクセス許可のセットを定義できます。 ロールは追加的ではありません。 ロールの詳細については、承認を参照してください。

データ API ビルダーは、1 つのロールのコンテキストで要求を評価します。

役割 形容
anonymous アクセス トークンが表示されない
authenticated 有効なアクセス トークンが表示される
<custom-role> 有効なアクセス トークンが提示され、アクセス トークンのロール要求にも含まれるユーザー ロールを指定する X-MS-API-ROLE HTTP ヘッダーが含まれます

形式

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role">,
          "actions": <["create", "read", "update", "delete", "execute", "*"]>,
          "fields": {
            "include": <array of strings>,
            "exclude": <array of strings>
          }
        }
      ]
    }
  }
}

例

この例では、エンドポイントに対する read アクセス許可のみを持つ reader という名前のロールを定義します。

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "reader",
          "actions": [
            "read"
          ]        
        }
      ]
    }
  }
}

Actions (string-array)

親 財産 種類 必須 デフォルト
entities.permissions actions oneOf [string, array] ✔️ はい 何一つ

関連付けられているロールに対して許可される操作の詳細を示す文字列値の配列。 table および view データベース オブジェクトの場合、ロールは、create、read、update、または delete アクションの任意の組み合わせを使用するように構成できます。 ストアド プロシージャの場合、ロールは execute アクションのみを持つことができます。 actions 配列は、関連付けられたロールで許可されるアクションの詳細を示します。 エンティティがテーブルまたはビューである場合は、create、read、update、deleteなどのアクションを組み合わせてロールを構成できます。

アクション SQL 操作
* ワイルドカード (execute を含む)
create 1 つ以上の行を挿入する
read 1 つ以上の行を選択する
update 1 つ以上の行を変更する
delete 1 つ以上の行を削除する
execute ストアド プロシージャを実行する

手記

ストアド プロシージャの場合、ワイルドカード (*) アクションは、execute アクションのみを含むリストに展開されます。 テーブルとビューの場合、ワイルドカード アクションは、create、read、update、および delete アクションを含むリストに展開されます。

例

この例では、contributorという名前の最初のロールに create と read のアクセス許可を付与します。 auditor という名前の 2 つ目のロールには、delete アクセス許可しかありません。

{
  "entities": {
    "CheckoutLogs": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            "delete"
          ]        
        },
        {
          "role": "contributor",
          "actions": [
            "read",
            "create"
          ]
        }
      ]
    }
  }
}

別の例を次に示します。

{
  ...
  "entities": {
    "<entity-name>": {
      ...
      "permissions": [
        {
          "role": "contributor",
          "actions": ["read", "create"]
        }
      ]
    }
  }
}

Actions (object-array)

親 財産 種類 必須 デフォルト
entities.permissions actions 文字列配列 ✔️ はい 何一つ

関連付けられているロールに対して許可される操作の詳細を示す文字列値の配列。 table および view データベース オブジェクトの場合、ロールは、create、read、update、または delete アクションの任意の組み合わせを使用するように構成できます。 ストアド プロシージャの場合、ロールは execute アクションのみを持つことができます。

手記

ストアド プロシージャの場合、ワイルドカード (*) アクションは、execute アクションのみを含むリストに展開されます。 テーブルとビューの場合、ワイルドカード アクションは、create、read、update、および delete アクションを含むリストに展開されます。

形式

{
  "entities": {
    <string>: {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <array of strings>,
              "policy": <object>
            }
          ]
        }
      ]
    }
  }
}

プロパティ

財産 必須 種類 デフォルト
action ✔️ はい 糸 何一つ
fields ❌ いいえ 文字列配列 何一つ
policy ❌ いいえ オブジェクト 何一つ

例

この例では、auditor ロール read アクセス許可のみを付与します。 auditor ロールは、policy.databaseで定義されている述語を使用してのみ、特定のデータを読み取ることができます。 auditor ロールは、fields プロパティを使用して読み取ることができるフィールドや読み取ることができないフィールドでも制限されます。

{
  "entities": {
    "CheckoutLogs": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["last_updated"]
              },
              "policy": {
                "database": "@item.LogDepth lt 3"
              }
            }
          ]
        }
      ]
    }
  }
}

アクション

親 財産 種類 必須 デフォルト
entities.permissions.actions[] action 糸 ✔️ はい 何一つ

データベース オブジェクトで許可される特定の操作を指定します。

価値観

このプロパティで使用できる値の一覧を次に示します。

テーブル 表示モード ストアド プロシージャ 形容
create ✔️ はい ✔️ はい ❌ いいえ 新しい項目を作成する
read ✔️ はい ✔️ はい ❌ いいえ 既存の項目をポイント読み取り
update ✔️ はい ✔️ はい ❌ いいえ 既存のアイテムを更新または置換する
delete ✔️ はい ✔️ はい ❌ いいえ 既存のアイテムを削除する
execute ❌ いいえ ❌ いいえ ✔️ はい プログラムによる操作を実行する

形式

{
  "entities": {
    <string>: {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <object>,
              "policy": <object>
            }
          ]
        }
      ]
    }
  }
}

例

anonymous ユーザーが特定のストアド プロシージャを execute し、特定のテーブルを read できる例を次に示します。

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            }
          ]
        }
      ]
    },
    "BestSellingAuthor": {
      "source": {
        "object": "dbo.stp_get_bestselling_authors",
        "type": "stored-procedure",
        "parameters": {
          "depth": 10
        }
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "execute"
            }
          ]
        }
      ]
    }
  }
}

田畑

親 財産 種類 必須 デフォルト
entities.permissions.actions[] fields オブジェクト ❌ いいえ 何一つ

データベース オブジェクトに対して特定のフィールドへのアクセスを許可する詳細な仕様。 ロールの構成は、include と excludeの 2 つの内部プロパティを持つオブジェクトの種類です。 これらの値は、セクション fieldsでアクセスを許可するデータベース列 (フィールド) を詳細に定義することをサポートします。

形式

{
  "entities": {
    <string>: {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": {
                "include": <array of strings>,
                "exclude": <array of strings>
              },
              "policy": <object>
            }
          ]
        }
      ]
    }
  }
}

例

この例では、anonymous ロールは、idを除くすべてのフィールドから読み取ることができますが、アイテムの作成時にすべてのフィールドを使用できます。

{
  "entities": {
    "Author": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": [ "*" ],
                "exclude": [ "id" ]
              }
            },
            { "action": "create" }
          ]
        }
      ]
    }
  }
}

作業を一緒に含める/除外する。 include セクションのワイルドカード * は、すべてのフィールドを示します。 exclude セクションに示されているフィールドは、include セクションに示されているフィールドよりも優先されます。 定義は、フィールド 'last_updated' を除くすべてのフィールドを含める に変換されます

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ],
            // Include All Except Specific Fields
            "fields": {
              "include": [ "*" ],
              "exclude": [ "secret-field" ]
            }
        },
        {
            "role": "authenticated",
            "actions": [ "read", "update" ],
            // Explicit Include and Exclude
            "fields": {
              "include": [ "id", "title", "secret-field" ],
              "exclude": [ "secret-field" ]
            }
        },
        {
            "role": "author",
            "actions": [ "*" ],
            // Include All With No Exclusions (default)
            "fields": {
              "include": ["*"],
              "exclude": []
            }
        }
    ]
}

政策

親 財産 種類 必須 デフォルト
entities.{entity}.permissions.actions[] policy オブジェクト ❌ いいえ 何一つ

actionごとに定義された policy セクションでは、要求から返される結果を制限する項目レベルのセキュリティ規則 (データベース ポリシー) を定義します。 サブセクション database は、要求の実行中に評価されるデータベース ポリシー式を表します。

形式

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <object>,
              "policy": {
                "database": <string>
              }
            }
          ]
        }
      ]
    }
  }
}

プロパティ

財産 必須 種類 デフォルト
database ✔️ はい 糸 何一つ

形容

database ポリシー: eq、lt、gtなどの演算子など、データベースが評価するクエリ述語に変換される OData に似た式。 要求に対して結果を返すには、データベース ポリシーから解決された要求のクエリ述語が、データベースに対して実行されるときに true に評価される必要があります。

アイテム ポリシーの例 述語
@item.OwnerId eq 2000 WHERE Table.OwnerId = 2000
@item.OwnerId gt 2000 WHERE Table.OwnerId > 2000
@item.OwnerId lt 2000 WHERE Table.OwnerId < 2000

predicate は、TRUE または FALSE に評価される式です。 述語は 、WHERE 句と HAVING 句、FROM 句の結合条件、およびブール値が必要なその他のコンストラクトの検索条件で使用されます。 (Microsoft Learn Docs)

データベース ポリシー

データベース ポリシー式を作成するときに、次の 2 種類のディレクティブを使用してデータベース ポリシーを管理できます。

指令 形容
@claims 要求で指定された検証済みアクセス トークン内の要求にアクセスする
@item データベース ポリシーが定義されているエンティティのフィールドを表します。

手記

Azure Static Web Apps 認証 (EasyAuth) が構成されている場合、データベース ポリシーで使用できる要求の種類は限られています。identityProvider、userId、userDetails、および userRoles。 詳細については、Azure Static Web App の クライアント プリンシパル データ ドキュメントを参照してください。

データベース ポリシーの例を次に示します。

  • @claims.userId eq @item.OwnerId
  • @claims.userId gt @item.OwnerId
  • @claims.userId lt @item.OwnerId

データ API ビルダーは、UserId 要求の値を、OwnerIdデータベース フィールドの値と比較します。 結果ペイロードには、要求メタデータとデータベース ポリシー式の両方 を満たすレコードのみが含まれます。

制限

データベース ポリシーは、テーブルとビューでサポートされています。 ストアド プロシージャをポリシーで構成することはできません。

データベース ポリシーでは、データベース内で要求が実行されるのを防ぐことはありません。 この動作は、データベース エンジンに渡される生成されたクエリで述語として解決されるためです。

データベース ポリシーは、作成、読み取り、更新、および削除でのみサポートされます。 ストアド プロシージャ呼び出しには述語がないため、追加できません。

サポートされている OData に似た演算子
演算子 形容 サンプル構文
and 論理 AND "@item.status eq 'active' and @item.age gt 18"
or 論理 OR "@item.region eq 'US' or @item.region eq 'EU'"
eq イコール "@item.type eq 'employee'"
gt より大きい "@item.salary gt 50000"
lt 未満 "@item.experience lt 5"

詳細については、二項演算子参照してください。

演算子 形容 サンプル構文
- Negate (数値) "@item.balance lt -100"
not 論理否定 (NOT) "not @item.status eq 'inactive'"

詳細については、単項演算子参照してください。

エンティティ フィールド名の制限
  • ルール: 文字またはアンダースコア (_) で始まり、最大 127 文字、アンダースコア (_)、または数字 (0-9) で始まる必要があります。
  • 影響: これらのルールに準拠していないフィールドは、データベース ポリシーで直接使用することはできません。
  • ソリューションの: mappings セクションを使用して、これらの名前付け規則を満たしていないフィールドのエイリアスを作成します。マッピングにより、すべてのフィールドをポリシー式に含めることができます。
不適合フィールドに mappings を利用する

エンティティ フィールド名が OData 構文規則を満たしていない場合、または他の理由でエイリアスを付けるだけの場合は、構成の mappings セクションでエイリアスを定義できます。

{
  "entities": {
    "<entity-name>": {
      "mappings": {
        "<field-1-name>": <string>,
        "<field-2-name>": <string>,
        "<field-3-name>": <string>
      }
    }
  }
}

この例では、field-1-name は、OData の名前付け規則を満たしていない元のデータベース フィールド名です。 field-1-name と field-1-alias へのマップを作成すると、このフィールドをデータベース ポリシー式で問題なく参照できます。 この方法は、OData の名前付け規則に準拠するのに役立つだけでなく、GraphQL エンドポイントと RESTful エンドポイントの両方でデータ モデルの明確さとアクセシビリティを向上させます。

例

要求ディレクティブと項目ディレクティブの両方を利用する Data API 構成内で Employee という名前のエンティティを考えてみましょう。 これにより、ユーザー ロールとエンティティの所有権に基づいて、データ アクセスが安全に管理されます。

{
  "entities": {
    "Employee": {
      "source": {
        "object": "HRUNITS",
        "type": "table",
        "key-fields": ["employee NUM"],
        "parameters": {}
      },
      "mappings": {
        "employee NUM": "EmployeeId",
        "employee Name": "EmployeeName",
        "department COID": "DepartmentId"
      },
      "policy": {
        "database": "@claims.role eq 'HR' or @claims.userId eq @item.EmployeeId"
      }
    }
  }
}

エンティティ定義: Employee エンティティは REST インターフェイスと GraphQL インターフェイス用に構成されており、これらのエンドポイントを介してデータのクエリまたは操作が可能であることを示します。

ソース構成: employee NUM をキー フィールドとして使用して、データベース内の HRUNITS を識別します。

マッピング: エイリアスは、employee NUM、employee Name、および department COID をそれぞれ EmployeeId、EmployeeName、および DepartmentIdにマップするために使用され、フィールド名が簡略化され、機密性の高いデータベース スキーマの詳細が難読化される可能性があります。

ポリシー アプリケーションの: policy セクションでは、OData に似た式を使用してデータベース ポリシーを適用します。 このポリシーは、HR ロール (@claims.role eq 'HR') を持つユーザー、または UserId 要求がデータベース (@claims.userId eq @item.EmployeeId) の EmployeeId (フィールド エイリアス) と一致するユーザーにデータ アクセスを制限します。 これにより、従業員が人事部に属していない限り、自分のレコードにのみアクセスできるようになります。 ポリシーでは、動的条件に基づいて行レベルのセキュリティを適用できます。

データベース

親 財産 種類 必須 デフォルト
entities.{entity}.permissions.actions.policy database オブジェクト ✔️ はい 何一つ

actionごとに定義された policy セクションでは、要求から返される結果を制限する項目レベルのセキュリティ規則 (データベース ポリシー) を定義します。 サブセクション database は、要求の実行中に評価されるデータベース ポリシー式を表します。

形式

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": {
                "include": <array of strings>,
                "exclude": <array of strings>
              },
              "policy": {
                "database": <string>
              }
            }
          ]
        }
      ]
    }
  }
}

このプロパティは、要求の実行中に評価されるデータベース ポリシー式を表します。 ポリシー文字列は、データベースによって評価されたクエリ述語に変換される OData 式です。 たとえば、ポリシー式 @item.OwnerId eq 2000 は、クエリ述語 WHERE <schema>.<object-name>.OwnerId = 2000に変換されます。

手記

述語 は、TRUE、FALSE、または UNKNOWNに回避する式です。 述語は次の場合に使用されます。

  • WHERE 句の検索条件
  • FROM 句の検索条件
  • FROM 句の結合条件
  • ブール値が必要なその他のコンストラクト。

詳細については、述語のに関する記事を参照してください。

要求に対して結果を返すには、データベース ポリシーから解決された要求のクエリ述語が、データベースに対して実行されるときに true に評価される必要があります。

データベース ポリシー式を作成するときに、次の 2 種類のディレクティブを使用してデータベース ポリシーを管理できます。

形容
@claims 要求で指定された検証済みアクセス トークン内の要求にアクセスします
@item データベース ポリシーが定義されているエンティティのフィールドを表します。

手記

Azure Static Web Apps 認証 (EasyAuth) が構成されている場合、データベース ポリシーで使用できる要求の種類は限られています。 これらの要求の種類には、identityProvider、userId、userDetails、および userRolesが含まれます。 詳細については、「Azure Static Web Apps クライアント プリンシパル データ」を参照してください。

例

たとえば、基本ポリシー式では、テーブル内の特定のフィールドが true かどうかを評価できます。 この例では、soft_delete フィールドが falseされているかどうかを評価します。

{
  "entities": {
    "Manuscripts": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@item.soft_delete eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

述語では、claims と item の両方のディレクティブ型を評価することもできます。 次の使用例は、アクセス トークンから UserId フィールドを取得し、ターゲット データベース テーブルの owner_id フィールドと比較します。

{
  "entities": {
    "Manuscript": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.userId eq @item.owner_id"
              }
            }
          ]
        }
      ]
    }
  }
}

制限

  • データベース ポリシーは、テーブルとビューでサポートされています。 ストアド プロシージャをポリシーで構成することはできません。
  • データベース ポリシーを使用して、要求がデータベース内で実行されないようにすることはできません。 この制限は、生成されたデータベース クエリでデータベース ポリシーがクエリ述語として解決されるためです。 データベース エンジンは最終的にこれらのクエリを評価します。
  • データベース ポリシーは、actionscreate、read、update、および deleteでのみサポートされます。
  • データベース ポリシー OData 式の構文では、これらのシナリオのみがサポートされます。
    • 二項演算子を含みますが、これらに限定されません。and、or、eq、gt、および lt。 詳細については、BinaryOperatorKindを参照してください。
    • - (否定) 演算子や not 演算子などの単項演算子。 詳細については、UnaryOperatorKindを参照してください。
  • データベース ポリシーには、フィールド名に関連する制限もあります。
    • 文字またはアンダースコアで始まり、その後に最大 127 文字、アンダースコア、または数字が続くエンティティ フィールド名。
    • この要件は OData 仕様に従います。 詳細については、「OData 共通スキーマ定義言語」を参照してください。

先端

前述の制限に準拠していないフィールドは、データベース ポリシーで参照できません。 回避策として、対応するエイリアスをフィールドに割り当てるために、マッピング セクションを使用してエンティティを構成します。

GraphQL (エンティティ)

親 財産 種類 必須 デフォルト
entities.{entity} graphql オブジェクト ❌ いいえ 何一つ

このオブジェクトは、GraphQL が有効かどうか、およびエンティティを GraphQL 型として公開するために使用される名前を定義します。 このオブジェクトは省略可能であり、既定の名前または設定で十分でない場合にのみ使用されます。

このセグメントは、GraphQL スキーマにエンティティを統合するために提供されます。 これにより、開発者は GraphQL でエンティティの既定値を指定または変更できます。 この設定により、スキーマに意図した構造と名前付け規則が正確に反映されます。

形式

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "enabled": <true> (default) | <false>,
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": "query" (default) | "mutation"
      }
    }
  }
}

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "enabled": <boolean>,
        "type": <string-or-object>,
        "operation": "query" (default) | "mutation"
      }
    }
  }
}

プロパティ

財産 必須 種類 デフォルト
enabled ❌ いいえ ブーリアン 何一つ
type ❌ いいえ 文字列またはオブジェクト 何一つ
operation ❌ いいえ enum 文字列 何一つ

例

これら 2 つの例は機能的に同等です。

{
  "entities": {
    "Author": {
      "graphql": true
    }
  }
}

{
  "entities": {
    "Author": {
      "graphql": {
        "enabled": true
      }
    }
  }
}

この例では、定義されたエンティティが Bookされ、データベース内の書籍に関連する一連のデータを処理していることを示しています。 GraphQL セグメント内の Book エンティティの構成は、GraphQL スキーマで表現および対話する方法に関する明確な構造を提供します。

Enabled プロパティの: Book エンティティは GraphQL ("enabled": true) を使用して使用できます。つまり、開発者とユーザーは GraphQL 操作を使用して書籍データのクエリまたは変更を行うことができます。

Type プロパティ: エンティティは、GraphQL スキーマの単数形の名前 "Book" と複数形の名前 "Books" で表されます。 この区別により、単一の書籍または複数の書籍に対してクエリを実行する場合、スキーマは直感的に名前付きの型 (1 つのエントリにBook、リストに Books) を提供し、API の使いやすさを向上させます。

Operation プロパティ: 操作は "query"に設定されています。これは、GraphQL を介した Book エンティティとの主な対話は、変更 (作成、更新、または削除) するのではなく、データのクエリ (取得) を目的としていることを示します。 このセットアップは、書籍データが変更よりも頻繁に読み取られる一般的な使用パターンに合わせて調整されます。

{
  "entities": {
    "Book": {
      ...
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "Book",
          "plural": "Books"
        },
        "operation": "query"
      },
      ...
    }
  }
}

型 (GraphQL エンティティ)

親 財産 種類 必須 デフォルト
entities.{entity}.graphql type oneOf [string, object] ❌ いいえ {entity-name}

このプロパティは、GraphQL スキーマ内のエンティティの名前付け規則を指定します。 スカラー文字列値とオブジェクト型の両方がサポートされています。 オブジェクト値は、単数形と複数形を指定します。 このプロパティは、スキーマの読みやすさとユーザー エクスペリエンスをきめ細かく制御します。

形式

{
  "entities": {
    <entity-name>: {
      "graphql": {
        "type": <string>
      }
    }
  }
}

{
  "entities": {
    <entity-name>: {
      "graphql": {
        "type": {
          "singular": <string>,
          "plural": <string>
        }
      }
    }
  }
}

プロパティ

財産 必須 種類 デフォルト
singular ❌ いいえ 糸 何一つ
plural ❌ いいえ 糸 N/A (既定値: 単数形)

例

GraphQL 型をさらに詳細に制御するために、単数形と複数形の名前を個別に表す方法を構成できます。

plural が見つからないか省略されている場合 (スカラー値など) データ API ビルダーは、複数形化のための英語の規則に従って自動的に名前を複数形化しようとします (例: https://engdic.org/singular-and-plural-noun-rules-definitions-examples)

{
  "entities" {
    "<entity-name>": {
      ...
      "graphql": {
        ...
        "type": {
          "singular": "User",
          "plural": "Users"
        }
      }
    }
  }
}

カスタム エンティティ名は、文字列値と共に type パラメーターを使用して指定できます。 この例では、複数形化の一般的な英語規則を使用して、エンジンによってこの名前の単数形と複数形のバリアントが自動的に区別されます。

{
  "entities": {
    "Author": {
      "graphql": {
        "type": "bookauthor"
      }
    }
  }
}

名前を明示的に指定する場合は、type.singular プロパティと type.plural プロパティを使用します。 この例では、両方の名前を明示的に設定します。

{
  "entities": {
    "Author": {
      "graphql": {
        "type": {
          "singular": "bookauthor",
          "plural": "bookauthors"
        }
      }
    }
  }
}

どちらの例も機能的に同等です。 どちらも、bookauthors エンティティ名を使用する GraphQL クエリに対して同じ JSON 出力を返します。

{
  bookauthors {
    items {
      first_name
      last_name
    }
  }
}

{
  "data": {
    "bookauthors": {
      "items": [
        {
          "first_name": "Henry",
          "last_name": "Ross"
        },
        {
          "first_name": "Jacob",
          "last_name": "Hancock"
        },
        ...
      ]
    }
  }
}

操作 (GraphQL エンティティ)

親 財産 種類 必須 デフォルト
entities.{entity}.graphql operation enum 文字列 ❌ いいえ 何一つ

ストアド プロシージャにマップされたエンティティの場合、operation プロパティは、ストアド プロシージャにアクセスできる GraphQL 操作の種類 (クエリまたは変更) を指定します。 この設定により、機能に影響を与えることなく、スキーマの論理的な編成と GraphQL のベスト プラクティスへの準拠が可能になります。

手記

エンティティは、{entity}.type プロパティの値を stored-procedureに設定することによって、ストアド プロシージャとして指定されます。 ストアド プロシージャの場合、新しい GraphQL 型 executeXXX が自動的に作成されます。 ただし、operation プロパティを使用すると、開発者はその型の場所をスキーマの mutation または query 部分に強制的に変換できます。 このプロパティを使用すると、スキーマ hygene を使用でき、operation 値に関係なく機能的な影響はありません。

不足している場合、operation の既定値は mutationです。

形式

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "operation": "query" (default) | "mutation"
      }
    }
  }
}

価値観

このプロパティで使用できる値の一覧を次に示します。

形容
query 基になるストアド プロシージャがクエリとして公開される
mutation 基になるストアド プロシージャは、変更として公開されます

例

operation が mutationされている場合、GraphQL スキーマは次のようになります。

type Mutation {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

operation が queryされている場合、GraphQL スキーマは次のようになります。

GraphQL スキーマは次のようになります。

type Query {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

手記

operation プロパティは、GraphQL スキーマでの操作の配置についてのみであり、操作の動作は変更されません。

Enabled (GraphQL エンティティ)

親 財産 種類 必須 デフォルト
entities.{entity}.graphql enabled ブーリアン ❌ いいえ 真

GraphQL エンドポイントを有効または無効にします。 GraphQL エンドポイントを介してエンティティを使用できるかどうかを制御します。 enabled プロパティを切り替えることで、開発者は GraphQL スキーマからエンティティを選択的に公開できます。

形式

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "enabled": <true> (default) | <false>
      }
    }
  }
}

REST (エンティティ)

親 財産 種類 必須 デフォルト
entities.{entity} rest オブジェクト ❌ いいえ 何一つ

構成ファイルの rest セクションは、各データベース エンティティの RESTful エンドポイントの微調整専用です。 このカスタマイズ機能により、公開されている REST API が特定の要件と一致し、ユーティリティと統合機能の両方が向上します。 既定の推定設定と必要なエンドポイント動作の間の潜在的な不一致に対処します。

形式

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": <string; default: "<entity-name>">,
        "methods": <array of strings; default: ["GET", "POST"]>
      }
    }
  }
}

プロパティ

財産 必須 種類 デフォルト
enabled ✔️ はい ブーリアン 真
path ❌ いいえ 糸 /<entity-name>
methods ❌ いいえ 文字列配列 取得

例

これら 2 つの例は機能的に同等です。

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ],
      "rest": true
    }
  }
}

{
  "entities": {
    "Author": {
      ...
      "rest": {
        "enabled": true
      }
    }
  }
}

エンティティの REST 構成のもう 1 つの例を次に示します。

{
  "entities" {
    "User": {
      "rest": {
        "enabled": true,
        "path": "/User"
      },
      ...
    }
  }
}

Enabled (REST エンティティ)

親 財産 種類 必須 デフォルト
entities.{entity}.rest enabled ブーリアン ❌ いいえ 真

このプロパティは、REST API 内のエンティティの可視性の切り替えとして機能します。 enabled プロパティを true または falseに設定することで、開発者は特定のエンティティへのアクセスを制御し、アプリケーションのセキュリティと機能の要件に合わせて調整された API サーフェスを有効にすることができます。

形式

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>
      }
    }
  }
}

パス (REST エンティティ)

親 財産 種類 必須 デフォルト
entities.rest path 糸 ❌ いいえ 何一つ

path プロパティは、REST API を介してエンティティにアクセスするために使用される URI セグメントを指定します。 このカスタマイズにより、既定のエンティティ名を超えて、よりわかりやすいエンドポイント パスまたは簡略化されたエンドポイント パスが可能になり、API のナビゲーション性とクライアント側の統合が強化されます。 既定では、パスは /<entity-name>です。

形式

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "path": <string; default: "<entity-name>">
      }
    }
  }
}

例

この例では、/auth エンドポイントを使用して Author エンティティを公開します。

{
  "entities": {
    "Author": {
      "rest": {
        "path": "/auth"
      }
    }
  }
}

メソッド (REST エンティティ)

親 財産 種類 必須 デフォルト
entities.{entity}.rest methods 文字列配列 ❌ いいえ 何一つ

ストアド プロシージャに特に適用できる methods プロパティは、プロシージャが応答できる HTTP 動詞 (GET、POST など) を定義します。 メソッドを使用すると、REST API を介してストアド プロシージャを公開する方法を正確に制御でき、RESTful 標準とクライアントの期待との互換性が確保されます。 このセクションでは、柔軟性と開発者制御に対するプラットフォームのコミットメントを強調し、各アプリケーションの特定のニーズに合わせた正確で直感的な API 設計を可能にします。

省略した場合、または指定されていない場合、methods の既定値は POSTです。

形式

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "methods": ["GET" (default), "POST"]
      }
    }
  }
}

価値観

このプロパティで使用できる値の一覧を次に示します。

形容
get HTTP GET 要求を公開します
post HTTP POST 要求を公開します

例

この例では、stp_get_bestselling_authors ストアド プロシージャが HTTP GET アクションのみをサポートするようにエンジンに指示します。

{
  "entities": {
    "BestSellingAuthor": {
      "source": {
        "object": "dbo.stp_get_bestselling_authors",
        "type": "stored-procedure",
        "parameters": {
          "depth": 10
        }
      },
      "rest": {
        "path": "/best-selling-authors",
        "methods": [ "get" ]
      }
    }
  }
}

マッピング (エンティティ)

親 財産 種類 必須 デフォルト
entities.{entity} mappings オブジェクト ❌ いいえ 何一つ

mappings セクション、データベース オブジェクト フィールドのエイリアスまたは公開された名前を構成できます。 構成された公開名は、GraphQL エンドポイントと REST エンドポイントの両方に適用されます。

大事な

GraphQL が有効になっているエンティティの場合、構成された公開名が GraphQL の名前付け要件を満たしている必要があります。 詳細については、「GraphQL 名の仕様」を参照してください。

形式

{
  "entities": {
    "<entity-name>": {
      "mappings": {
        "<field-1-name>": "<field-1-alias>",
        "<field-2-name>": "<field-2-alias>",
        "<field-3-name>": "<field-3-alias>"
      }
    }
  }
}

例

この例では、データベース オブジェクト dbo.magazines の sku_title フィールドは、titleという名前を使用して公開されます。 同様に、sku_status フィールドは、REST エンドポイントと GraphQL エンドポイントの両方で status として公開されます。

{
  "entities": {
    "Magazine": {
      ...
      "mappings": {
        "sku_title": "title",
        "sku_status": "status"
      }
    }
  }
}

マッピングの別の例を次に示します。

{
  "entities": {
    "Book": {
      ...
      "mappings": {
        "id": "BookID",
        "title": "BookTitle",
        "author": "AuthorName"
      }
    }
  }
}

Mappings: mappings オブジェクトは、データベース フィールド (BookID、BookTitle、AuthorName) を、外部で使用されるより直感的または標準化された名前 (id、title、author) にリンクします。 このエイリアスは、いくつかの目的で機能します。

  • 明確さと整合性の: 基になるデータベース スキーマに関係なく、API 全体で明確で一貫性のある名前付けを使用できます。 たとえば、データベース内の BookID は API の id として表され、開発者がエンドポイントを操作する際に直感的になります。

  • GraphQL コンプライアンス: フィールド名をエイリアス化するメカニズムを提供することで、GraphQL インターフェイスを介して公開される名前が GraphQL の名前付け要件に準拠していることを確認します。 名前に注意することは重要です。GraphQL には名前に関する厳密な規則があります (スペースがない、文字やアンダースコアなどで始まる必要があるなど)。 たとえば、データベース フィールド名がこれらの条件を満たしていない場合は、マッピングを使用して準拠している名前にエイリアスを付けることができます。

  • 柔軟性: このエイリアスにより、データベース スキーマと API の間に抽象化レイヤーが追加され、もう一方のスキーマに変更を加える必要はありません。 たとえば、データベース内のフィールド名の変更では、マッピングに一貫性がある場合、API ドキュメントまたはクライアント側コードを更新する必要はありません。

  • フィールド名難読化: マッピングを使用すると、フィールド名を難読化できます。これにより、権限のないユーザーがデータベース スキーマや格納されているデータの性質に関する機密情報を推測するのを防ぐことができます。

  • プロプライエタリな情報の保護: フィールドの名前を変更することで、データベースの元のフィールド名を使用してヒントが表示される可能性がある独自の名前やビジネス ロジックを保護することもできます。

リレーションシップ (エンティティ)

親 財産 種類 必須 デフォルト
entities.{entity} relationships オブジェクト ❌ いいえ 何一つ

このセクションマップには、エンティティが他の公開エンティティとどのように関連しているかをマップするリレーションシップ定義のセットが含まれています。 これらのリレーションシップ定義には、必要に応じて、リレーションシップのサポートと適用に使用される基になるデータベース オブジェクトの詳細を含めることもできます。 このセクションで定義されているオブジェクトは、関連エンティティの GraphQL フィールドとして公開されます。 詳細については、「データ API ビルダーのリレーションシップの内訳を参照してください。

手記

リレーションシップは GraphQL クエリにのみ関連します。 REST エンドポイントは一度に 1 つのエンティティにのみアクセスし、入れ子になった型を返すことはできません。

relationships セクションでは、エンティティがデータ API ビルダー内でどのように相互作用するかについて説明し、関連付けと、これらのリレーションシップに対する潜在的なデータベース サポートについて詳しく説明します。 各リレーションシップの relationship-name プロパティは両方とも必須であり、特定のエンティティのすべてのリレーションシップで一意である必要があります。 カスタム名は、明確で識別可能な接続を保証し、これらの構成から生成された GraphQL スキーマの整合性を維持します。

繋がり 濃度 例
一対多 many 1 つのカテゴリ エンティティは、多くの todo エンティティに関連付けることができます
多対一 one 多くの todo エンティティは、1 つのカテゴリ エンティティに関連付けることができます
多対多 many 1 つの todo エンティティは多くのユーザー エンティティに関連付けることができ、1 つのユーザー エンティティは多くの todo エンティティに関連付けることができます

形式

{
  "entities": {
    "<entity-name>": {
      "relationships": {
        "<relationship-name>": {
          "cardinality": "one" | "many",
          "target.entity": "<string>",
          "source.fields": ["<string>"],
          "target.fields": ["<string>"],
          "linking.object": "<string>",
          "linking.source.fields": ["<string>"],
          "linking.target.fields": ["<string>"]
        }
      }
    }
  }
}

プロパティ

財産 必須 種類 デフォルト
cardinality ✔️ はい enum 文字列 何一つ
target.entity ✔️ はい 糸 何一つ
source.fields ❌ いいえ 文字列配列 何一つ
target.fields ❌ いいえ 文字列配列 何一つ
linking.<object-or-entity> ❌ いいえ 糸 何一つ
linking.source.fields ❌ いいえ 文字列配列 何一つ
linking.target.fields ❌ いいえ 文字列配列 何一つ

例

リレーションシップを検討するときは、一対多の、多対一の、および多対多の リレーションシップ の違いを比較することをお勧めします。

一対多

最初に、公開されている Category エンティティとのリレーションシップの例として、Book エンティティと 一対多の リレーションシップを持つ例を考えてみましょう。 ここでは、カーディナリティは manyに設定されています。 各 Category は複数の関連する Book エンティティを持つことができますが、各 Book エンティティは 1 つの Category エンティティにのみ関連付けられます。

{
  "entities": {
    "Book": {
      ...
    },
    "Category": {
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

この例では、source.fields リストはソース エンティティ (Category) の id フィールドを指定します。 このフィールドは、target エンティティ内の関連アイテムに接続するために使用されます。 逆に、target.fields リストでは、ターゲット エンティティ (Book) の category_id フィールドを指定します。 このフィールドは、source エンティティ内の関連アイテムに接続するために使用されます。

このリレーションシップを定義すると、結果として公開される GraphQL スキーマは次の例のようになります。

type Category
{
  id: Int!
  ...
  books: [BookConnection]!
}
多対一

次に、カーディナリティを に設定する多対一 を することを検討します。 公開された Book エンティティには、1 つの関連 Category エンティティを含めることができます。 Category エンティティには、複数の関連 Book エンティティを含めることができます。

{
  "entities": {
    "Book": {
      "relationships": {
        "books_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      },
      "Category": {
        ...
      }
    }
  }
}

ここで、source.fields リストは、ソース エンティティ (Book) の category_id フィールドが、関連するターゲット エンティティ (Category) の id フィールドを参照することを指定します。 逆に、target.fields リストは逆リレーションシップを指定します。 このリレーションシップにより、結果の GraphQL スキーマに書籍からカテゴリへのマッピングが含まれるようになりました。

type Book
{
  id: Int!
  ...
  category: Category
}
多対多

最後に、多対多 リレーションシップは、many のカーディナリティとより多くのメタデータを使用して定義され、バッキング データベースにリレーションシップを作成するために使用されるデータベース オブジェクトを定義します。 ここでは、Book エンティティは複数の Author エンティティを持つ場合があり、逆に Author エンティティは複数の Book エンティティを持つことができます。

{
  "entities": {
    "Book": {
      "relationships": {
        ...,
        "books_authors": {
          "cardinality": "many",
          "target.entity": "Author",
          "source.fields": [ "id" ],
          "target.fields": [ "id" ],
          "linking.object": "dbo.books_authors",
          "linking.source.fields": [ "book_id" ],
          "linking.target.fields": [ "author_id" ]
        }
      },
      "Category": {
        ...
      },
      "Author": {
        ...
      }
    }
  }
}

この例では、source.fields と target.fields の両方が、リレーションシップ テーブルでソース (Book) エンティティとターゲット (Author) エンティティの両方のプライマリ識別子 (id) を使用していることを示しています。 linking.object フィールドは、リレーションシップが dbo.books_authors データベース オブジェクトで定義されていることを指定します。 また、linking.source.fields リンク オブジェクトの book_id フィールドが Book エンティティの id フィールドを参照することを指定し、リンク オブジェクトの author_id フィールドが Author エンティティの id フィールドを参照することを指定 linking.target.fields。

この例は、この例のような GraphQL スキーマを使用して説明できます。

type Book
{
  id: Int!
  ...
  authors: [AuthorConnection]!
}

type Author
{
  id: Int!
  ...
  books: [BookConnection]!
}

濃度

親 財産 種類 必須 デフォルト
entities.{entity}.relationships cardinality 糸 ✔️ はい 何一つ

現在のソース エンティティがターゲット エンティティの 1 つのインスタンスにのみ関連付けられているか、複数に関連付けられているのか指定します。

価値観

このプロパティで使用できる値の一覧を次に示します。

形容
one ソースはターゲットの 1 つのレコードにのみ関連します
many ソースは、ターゲットからの 0 から多のレコードに関連付けることができます

ターゲット エンティティ

親 財産 種類 必須 デフォルト
entities.{entity}.relationships target.entity 糸 ✔️ はい 何一つ

リレーションシップのターゲットである構成内の他の場所で定義されているエンティティの名前。

ソース フィールド

親 財産 種類 必須 デフォルト
entities.{entity}.relationships source.fields 配列 ❌ いいえ 何一つ

ターゲット エンティティ内の関連アイテムへの接続に使用する ソース エンティティのマッピングに使用するフィールドを定義する省略可能なパラメーター。

先端

リレーションシップを自動的に推論するために使用できる 2 つのデータベース オブジェクト間に 外部キー 制約がある場合、このフィールドは必要ありません。

ターゲット フィールド

親 財産 種類 必須 デフォルト
entities.{entity}.relationships target.fields 配列 ❌ いいえ 何一つ

ソース エンティティ内の関連アイテムへの接続に使用される、ターゲット エンティティのマッピングに使用するフィールドを定義する省略可能なパラメーター。

先端

リレーションシップを自動的に推論するために使用できる 2 つのデータベース オブジェクト間に 外部キー 制約がある場合、このフィールドは必要ありません。

オブジェクトまたはエンティティのリンク

親 財産 種類 必須 デフォルト
entities.{entity}.relationships linking.object 糸 ❌ いいえ 何一つ

多対多リレーションシップの場合、他の 2 つのエンティティ間のリレーションシップを定義するために必要なデータを含むデータベース オブジェクトまたはエンティティの名前。

ソース フィールドのリンク

親 財産 種類 必須 デフォルト
entities.{entity}.relationships linking.source.fields 配列 ❌ いいえ 何一つ

ソース エンティティに関連するデータベース オブジェクトまたはエンティティ フィールドの名前。

リンク先フィールド

親 財産 種類 必須 デフォルト
entities.{entity}.relationships linking.target.fields 配列 ❌ いいえ 何一つ

ターゲット エンティティに関連するデータベース オブジェクトまたはエンティティ フィールドの名前。

キャッシュ (エンティティ)

親 財産 種類 必須 デフォルト
entities.{entity}.cache enabled ブーリアン ❌ いいえ 偽

エンティティのキャッシュを有効にして構成します。

形式

You're right; the formatting doesn't match your style. Here’s the corrected version following your preferred documentation format:

```json
{
  "entities": {
    "<entity-name>": {
      "cache": {
        "enabled": <true> (default) | <false>,
        "ttl-seconds": <integer; default: 5>
      }
    }
  }
}

プロパティ

財産 必須 種類 デフォルト
enabled ❌ いいえ ブーリアン 偽
ttl-seconds ❌ いいえ 整数 5

例

この例では、キャッシュが有効になり、項目は 30 秒後に期限切れになります。

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": true,
        "ttl-seconds": 30
      }
    }
  }
}

有効 (キャッシュ エンティティ)

親 財産 種類 必須 デフォルト
entities.{entity}.cache enabled ブーリアン ❌ いいえ 偽

エンティティのキャッシュを有効にします。

データベース オブジェクトのサポート

オブジェクトの種類 キャッシュのサポート
テーブル ✅ はい
眺める ✅ はい
ストアド プロシージャ ✖️ いいえ
コンテナ ✖️ いいえ

HTTP ヘッダーのサポート

要求ヘッダー キャッシュのサポート
no-cache ✖️ いいえ
no-store ✖️ いいえ
max-age ✖️ いいえ
public ✖️ いいえ
private ✖️ いいえ
etag ✖️ いいえ

形式

{
  "entities": {
    "<entity-name>": {
      "cache": {
        "enabled": <boolean> (default: false)
      }
    }
  }
}

例

この例では、キャッシュは無効になっています。

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": false
      }
    }
  }
}

TTL (秒単位) (キャッシュ エンティティ)

親 財産 種類 必須 デフォルト
entities.cache ttl-seconds 整数 ❌ いいえ 5

キャッシュされた項目の Time-to-Live (TTL) 値を秒単位で構成します。 この時間が経過すると、項目はキャッシュから自動的に排除されます。 既定値は 5 秒です。

形式

{
  "entities": {
    "<entity-name>": {
      "cache": {
        "ttl-seconds": <integer; inherited>
      }
    }
  }
}

例

この例では、キャッシュが有効になり、項目は 15 秒後に期限切れになります。 省略すると、この設定はグローバル設定または既定値を継承します。

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": true,
        "ttl-seconds": 15
      }
    }
  }
}

関連コンテンツ