次の方法で共有

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

  • [アーティクル]

Data 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 スキーマを指定し、構成が必要な形式に準拠していることを確認します。
data-source データベース接続を確立するために必要な、 データベースの種類 と 接続文字列に関する詳細が含まれます。
data-source-files 他のデータ ソースを定義する可能性がある他の構成ファイルを指定する省略可能な配列。
ランタイム 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 つの 共通の環境値が用意されています。 Development、 Staging、および Production。ただし、選択した任意の環境値を使用することを選択できます。 Data API ビルダーが使用する環境は、 環境変数を使用して構成する DAB_ENVIRONMENT 必要があります。

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

環境
dab-config.json ベース
dab-config。Development.json 開発

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

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

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

基本構成で指定 基本構成で指定されていません
現在の環境構成で指定 現在の環境 現在の環境
現在の環境構成で指定されていません ベース なし

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

構成プロパティ

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

スキーマ

必須: ✔️ はい

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

Format

{
  "$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 より前のバージョンの Data API ビルダーでは、スキーマ URI が異なる場合があります。

データ ソース

必須: ✔️ はい

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

フォーマット

{
  "data-source": {
    "database-type": "...",
    "connection-string": "your-connection-string",
    
    // mssql-only
    "options": {
      "set-session-context": <true> (default) | <false>
    },
    
    // cosmosdb_nosql-only
    "options": {
      "database": "your-cosmosdb-database-name", 
      "container": "your-cosmosdb-container-name",
      "schema": "path-to-your-graphql-schema-file"
    }
  }
}

プロパティ

必須 型
database-type ✔️ はい 列挙型文字列
connection-string ✔️ はい string
options ❌ いいえ object

データベースの種類

必須: ✔️ はい

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

フォーマット

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

値

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

型 説明 最小バージョン
mssql Azure SQL データベース 該当なし
mssql Azure SQL MI 該当なし
mssql SQL Server SQL 2016
sqldw Azure SQL Data Warehouse 該当なし
postgresql PostgreSQL v11
mysql MySQL v8
cosmosdb_nosql NoSQL 用 Azure Cosmos DB 該当なし
cosmosdb_postgresql PostgreSQL 用 Azure Cosmos DB 該当なし

接続文字列

必須: ✔️ はい

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

フォーマット

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

接続の回復性

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

$r^2$

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

秒
First 2
Second 4
Third 8
第 四 16
第 5 32

Azure SQL と SQL Server

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

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

例

接続文字列に使用される値は、シナリオで使用されるデータベース サービスによって大きく異なります。 環境変数に接続文字列を格納し、 関数を使用してアクセスすることを常に @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 接続文字列」を参照してください。
環境変数にアクセスする @env('database-connection-string') ローカル コンピューターから環境変数にアクセスします。 この例では、 環境変数が database-connection-string 参照されています。

ヒント

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

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

  • 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;"

注意

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

オプション

必須: ❌ いいえ

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

Format

{
  "data-source"{
    "options": {
        "<key>": "<value>"
    }
  }
}

例

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

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

データ ソース ファイル

必須: ❌ いいえ

このプロパティには、追加のデータベースを参照するランタイム構成ファイルの名前が含まれます。

フォーマット

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

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

  • data-sourceすべての構成ファイルの プロパティが必要です。
  • entitiesすべての構成ファイルの プロパティが必要です。
  • 最上位の構成ファイル runtime 設定のみが使用されます。
  • 子レベルの構成ファイルは、子ファイルを識別することもできます。
  • 構成ファイルは、必要に応じてサブフォルダーに配置できます。
  • エンティティ名は、すべての構成ファイルで一意である必要があります。
  • 構成ファイル間のリレーションシップはサポートされていません。

既知の問題

  • 現在、子構成ファイルは GraphQL でのみサポートされています。
  • 現在、子構成ファイルは環境変数をサポートしていません。

例

{
  "data-source-files": ["dab-config-two.json", "dab-config-three.json"]
}

使用している場合はサブフォルダーを参照します。

{
  "data-source-files": ["myfolder/dab-config-two.json"]
}

ランタイム

必須: ❌ いいえ

セクションでは runtime 、公開されているすべてのエンティティのランタイムの動作と設定に影響を与えるオプションの概要を示します。

フォーマット

{
  "runtime": {
    "rest": {
      "path": "/api" (default),
      "enabled": <true> (default) | <false>,
      "request-body-strict": <true> (default) | <false>
    },
    "graphql": {
      "path": "/graphql" (default),
      "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": -1, <integer; default: 100000>,
    "default-page-size": -1 | <integer; default: 100>
  },
  "telemetry": {
    "application-insights": {
      "connection-string": "<connection-string>",
      "enabled": <true> | <false> (default)
    }
  }
}

プロパティ

必須 型
rest ❌ いいえ object
graphql ❌ いいえ object
host ❌ いいえ object
cache ❌ いいえ object

例

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

{
  "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": 100000,
      "default-page-size": 100
    },
    "telemetry": {
      "application-insights": {
        "connection-string": "<connection-string>",
        "enabled": true
      }
    }
  }
}

GraphQL (ランタイム)

必須: ❌ いいえ

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

フォーマット

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

プロパティ

必須 型
enabled ❌ いいえ ブール値
path ❌ いいえ string
allow-introspection ❌ いいえ ブール値
multiple-mutations ❌ いいえ object

有効 (GraphQL ランタイム)

必須: ❌ いいえ

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

Format

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

例

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

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

パス (GraphQL ランタイム)

必須: ❌ いいえ

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

重要

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

Format

{
  "runtime": {
    "graphql": {
      "path": "<string>"
    }
  }
}

例

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

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

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

必須: ❌ いいえ

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

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

Format

{
  "runtime": {
    "graphql": {
      "allow-introspection": "<boolean>"
    }
  }
}

例

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

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

複数のミューテーション (GraphQL ランタイム)

必須: ❌ いいえ

GraphQL ランタイムのすべての複数のミューテーション操作を構成します。

注意

既定では、複数のミューテーションは有効ではなく、有効にするように明示的に構成する必要があります。

フォーマット

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": <object>
      }
    }
  }
}

プロパティ

必須 型
create ❌ いいえ object

複数のミューテーション - 作成 (GraphQL ランタイム)

必須: ❌ いいえ

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

フォーマット

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

プロパティ

必須 型
enabled ✔️ はい ブール値

例

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

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

REST (ランタイム)

必須: ❌ いいえ

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

フォーマット

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

プロパティ

必須 型
enabled ❌ いいえ ブール値
path ❌ いいえ string
request-body-strict ❌ いいえ ブール値

有効 (REST ランタイム)

必須: ❌ いいえ

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

Format

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

例

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

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

パス (REST ランタイム)

必須: ❌ いいえ

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

注意

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

重要

このプロパティにはサブパスを使用できません。

Format

{
  "runtime": {
    "rest": {
      "path": "<string>"
    }
  }
}

例

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

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

ヒント

エンティティを定義する Author 場合、このエンティティのエンドポイントは になります /data/Author。

要求本文 strict (REST ランタイム)

必須: ❌ いいえ

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

注意

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

Format

{
  "runtime": {
    "rest": {
      "request-body-strict": "<boolean>"
    }
  }
}

例

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

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

ホスト (ランタイム)

必須: ❌ いいえ

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

フォーマット

{
  "runtime": {
    ...
    "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>"
        }
      }
    }
  }
  ...
}

プロパティ

必須 型
mode ❌ いいえ 列挙型文字列
cors ❌ いいえ object
authentication ❌ いいえ object

例

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

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

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

必須: ❌ いいえ

Data API ビルダー エンジンを または production モードでdevelopment実行するかどうかを定義します。 既定値は production です。

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

ヒント

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

フォーマット

{
  "runtime": {
    "host": {
      "mode": "<enum-string>"
    }
  }
}

値

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

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

CORS (ホスト ランタイム)

必須: ❌ いいえ

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

フォーマット

{
  "runtime": {
    "host": {
      "cors": "<object>"
    }
  }
}

プロパティ

必須 型
allow-credentials ❌ いいえ ブール値
origins ❌ いいえ 文字列配列

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

必須: ❌ いいえ

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

注意

CORS ヘッダーの Access-Control-Allow-Credentials 詳細については、「 MDN Web Docs CORS リファレンス」を参照してください。

フォーマット

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": "<boolean>",
      }
    }
  }
}

Origins (ホスト ランタイム)

必須: ❌ いいえ

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

Format

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

例

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

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

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

必須: ❌ いいえ

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

フォーマット

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "<enum-string>",
        "jwt": "<object>"
      }
    }
  }
}

プロパティ

必須 型
provider ❌ いいえ 列挙型文字列
jwt ❌ いいえ object

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

必須: ❌ いいえ

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

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

フォーマット

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "<enum-string>",
      }
    }
  }
}

値

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

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

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

必須: ❌ いいえ

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

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

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

フォーマット

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  }
}

プロパティ

必須 型
audience ❌ いいえ string
issuer ❌ いいえ string

例

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

データ API ビルダーでの JSON Web トークンのサポートの図。

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

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

では StaticWebApps、Data 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"
  }
 }
}

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

必須: ❌ いいえ

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

フォーマット

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "audience": "<string>",
        }
      }
    }
  }
}

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

必須: ❌ いいえ

JWT トークンの発行者。

フォーマット

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "issuer": "<string>"
        }
      }
    }
  }
}

改ページ (ランタイム)

必須: ❌ いいえ

結果の制限を構成します。

フォーマット

{
  "runtime": {
    "pagination": {
      "max-page-size": -1, 
      "default-page-size": -1 
    }
  }
}

プロパティ

必須 Type Default
max-page-size ❌ いいえ 整数 (integer) 100,000
default-page-size ❌ いいえ 整数 (integer) 100

例

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

この例では、REST GET を https://localhost:5001/api/books発行した場合、ページ サイズが既定で value 1 に設定されているため、結果の JSON には配列に 1 つのレコードが含まれます。 結果の例は、後続のページが存在する場合に Data API ビルダーが結果に追加 nextLink する方法を示しています。

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

エンドポイントの $after クエリに使用されるのと同じ URL にオプションが追加されていることに注意してください。 この特殊な値は、現在のページの最後のレコードを内部的に示します。 指定した文字列を の値として使用すると、データの $after 次のページが自動的に返されます。

注意

基になるテーブル データがクエリ間で変更されている可能性があります。 この場合、エラーは発生しません。ただし、データ API ビルダーがページ番号の概念を持たない理由を示しています。 後続の呼び出しでは正しい次のページが返されますが、データの変更によりページ番号が変更された可能性があります。 このようにして、 nextLink は文字通り次の ページのデータであり、次のページ 番号ではありません。

GraphQL の改ページ位置の例

この例では、GraphQL クエリを発行する場合は、 と endCursor を含めhasNextPage、改ページ位置を使用する必要があります。 この要件の理由は、REST エンドポイントがペイロードの構造を決定するが、コンシューマーのクエリによって GraphQL ペイロードの構造が決定されるためです。 これらの値の有無にかかわらず、結果は引き続き既定のページ サイズに制限されます。 クエリは次のようになります。

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

GraphQL の結果には、 と endCursorが含まれますhasNextPage。これは、さらにページをフェッチするために使用されます。

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

後続の GraphQL クエリには、次の方法で変数の after 値としてカーソルが含まれます。

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

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

REST と GraphQL には、それぞれ または first 変数を$limit含めることができます。 の目的は、特定の limit クエリの結果を制限することです。 ただし、 を検討してください https://{server}/api/books?$limit=10。 が の場合 limit (たとえば、既定のページ サイズが 100 の場合は 10)、結果は 10 に制限されます。 ただし、既定のページ サイズが 100 のときに が 200 の場合 limit 、結果は 200 (既定のページ サイズより大きい値) に制限されます。

最初の値 結果
-1 設定の現在の max-page-size 値。 設定値がコンシューマーにmax-page-size不明な場合は、 を使用-1すると便利です。 データ API ビルダーは、 を -1 の現在の値 max-page-sizeに置き換えます。
< max-page-size 結果は、指定された値に制限されます。
0 無効。 例外が返されます。
< -1 無効。 例外が返されます。
> max-page-size 無効。 例外が返されます。

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

必須: ❌ いいえ

REST または GraphQL クエリによって返される最上位レコードの最大数を設定します。

使用できる値

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

注意

32 ビット整数の最大値は 2,147,483,647 です。 これは大きいです。 実際には、送信エンドポイント ペイロードのサイズには厳密な普遍的な制限はありませんが、サーバーの構成、帯域幅、タイムアウトなど、いくつかの要因によってサイズが効果的に制限される可能性があります。 データ API ビルダーはシナリオを把握していないため、この設定は各開発者が構成できます。 既定の最大値である 100,000 は、既に非常に積極的です。

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

必須: ❌ いいえ

改ページが REST または GraphQL クエリによって返される最上位レベルのレコードの数である場合に、ページ サイズを設定します。

使用できる値

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

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

必須: ❌ いいえ

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

フォーマット

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

プロパティ

必須 型
enabled ❌ いいえ ブール値
ttl-seconds ❌ いいえ 整数 (integer)

例

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

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

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

必須: ❌ いいえ

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

Format

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

例

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

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

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

必須: ❌ いいえ

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

Format

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

例

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

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

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

必須: ❌ いいえ

このプロパティは、API ログを一元化するように Application Insights を構成します。 詳細情報。

エンティティ

必須: ✔️ はい

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

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

フォーマット

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": "/entity-path", (default <entity-name>)
        "methods": ["GET", "POST" (default)]
      },
      "graphql": {
        "enabled": <true> (default) | <false>,
        "type": {
          "singular": "myEntity",
          "plural": "myEntities"
        },
        "operation": "query" | "mutation" (default)
      },
      "source": {
        "object": "database-object-name",
        "type": "view" | "stored-procedure" | "table",
        "key-fields": ["field-name"],
        "parameters": {
          "parameter-name": "parameter-value"
        }
      },
      "mappings": {
        "database-field-name": "field-alias"
      },
      "relationships": {
        "relationship-name": {
          "cardinality": "one" | "many",
          "target.entity": "target-entity-name",
          "source.fields": ["source-field-name"],
          "target.fields": ["target-field-name"],
          "linking.object": "linking-object-name",
          "linking.source.fields": ["linking-source-field-name"],
          "linking.target.fields": ["linking-target-field-name"]
        }
      },
      "permissions": [
        {
          "role": "anonymous | authenticated | custom-role-name",
          "actions": ["create" | "read" | "update" | "delete" | "*"],
          "fields": {
            "include": ["field-name"],
            "exclude": ["field-name"]
          },
          "policy": {
            "database": "<Expression>"
          }
        }
      ]
    }
  }
}

プロパティ

必須 型
source ✔️ はい object
permissions ✔️ はい array
rest ❌ いいえ object
graphql ❌ いいえ object
mappings ❌ いいえ object
relationships ❌ いいえ object
cache ❌ いいえ object

例

たとえば、この JSON オブジェクトは、 という名前 Author の GraphQL エンティティと、パスを介して到達可能な REST エンドポイントを公開するように Data API ビルダーに /Author 指示します。 データベース テーブルによって 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'"
          }
        }
      ]
    }
  }
}

source

必須: ✔️ はい

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

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

フォーマット

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

プロパティ

必須 型
object ✔️ はい string
type ✔️ はい 列挙型文字列
parameters ❌ いいえ object
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ストアド プロシージャによってサポートされるエンティティ。
  • source 内の type プロパティは に stored-procedure設定され、エンティティがマップされるソース オブジェクトの種類を示します。
  • object source 内の プロパティは、データベース内のストアド プロシージャの名前です。

また、この例では、(省略可能) mapping プロパティが "Todo" エンティティの構成に追加されます。 エンティティ内のフィールド (Id、DescriptionTitleおよびCompleted) を、基になるデータ ソースまたはストアド プロシージャ パラメーター (todo_id、todo_descriptiontodo_titleおよび 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;

Object

必須: ✔️ はい

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

例

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

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

型 (エンティティ)

必須: ✔️ はい

プロパティはtype、エンティティの背後にあるデータベース オブジェクトの種類を識別します。これには、、table、および stored-procedureが含まれますview。 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"
        ]
      }
    }
  }
}

キー フィールド

必須: ❌ いいえ

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

重要

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

Format

{
  "entities" {
    "<entity-name>": {
      ...
      "type": "view",
      "key-fields": [ "<field-name>" ]
    }
  }
}

例

この例では、 dbo.vw_category_details キー フィールドとして を指定した ビュー category_id を使用します。

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

パラメーター

必須: ❌ いいえ

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

重要

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

Format

{
  "entities" {
    "<entity-name>": {
      ...
      "type": "stored-procedure",
      "parameters": {
        "<parameter-name-1>" : "<default-value>",
        "<parameter-name-2>" : "<default-value>",
        "<parameter-name-3>" : "<default-value>"
      }
    }
  }
}

例

この例では、次の 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"
        }
      }
    }
  }
}

アクセス許可

必須: ✔️ はい

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

フォーマット

{
  ...
  "entities": {
    "<entity-name>": {
      ...
      "permissions": [
        {
          ...
          "actions": [
            "create", 
            "read", 
            "update", 
            "delete", 
            "execute"
          ],
        }
      ]
    }
  }
}

プロパティ

必須 型
role ✔️ はい string
actions (string-array) または actions (object-array) ✔️ はい オブジェクトまたは文字列配列

例

この例では、匿名ロールは、考えられるすべてのアクションへのアクセス権を持って定義されています。

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

または、オブジェクトを使用してワイルドカード アクションを定義することもできます。

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

文字列とオブジェクトの配列アクションを混在させ、照合することもできます。

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

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

認証済みロール認証されたユーザーが、 を明示的に含めてidtitle、特定のフィールドの読み取りと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含める必要があることを指定し、セクション内のすべてのフィールドをワイルドカード*でexclude除外する必要があることを示Titleしています。 同じロジックを表すもう 1 つの方法は次のとおりです。

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

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

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

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

ロール

必須: ✔️ はい

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

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

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

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

Format

{
  "entities": {
    "entity-name": {
      "permissions": [
        {
          "role": "anonymous" | "authenticated" | "custom-role",
          "actions": [
            "create",
            "read",
            "update",
            "delete",
            "execute", // only when stored-procedure
            "*"
          ],
          "fields": {
            "include": ["field-name", "field-name"],
            "exclude": ["field-name", "field-name"]
          }
        }
      ]
    }
  }
}

例

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

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

Actions (string-array)

必須: ✔️ はい

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

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

注意

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

例

この例では、 という名前contributorのcreateread最初のロールに と のアクセス許可を付与します。 という名前 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)

必須: ✔️ はい

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

注意

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

フォーマット

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

プロパティ

必須 型
action ✔️ はい string
fields ❌ いいえ 文字列配列
policy ❌ いいえ object

例

この例では、ロールに対する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"
              }
            }
          ]
        }
      ]
    }
  }
}

アクション

必須: ✔️ はい

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

値

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

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

例

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

{
  "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"
            }
          ]
        }
      ]
    }
  }
}

フィールド

必須: ❌ いいえ

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

Format

{
  ...
  "entities": {
    "<entity-name>": {
      ...
      "permissions": [
        {
          {
            ...
            "fields": {
              "include": ["<field-name>"],
              "exclude": ["<field-name>"]
            }
          }
        }
      ]
    }
  }
}

例

この例では、 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": []
            }
        }
    ]
}

ポリシー

必須: ❌ いいえ

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

フォーマット

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

プロパティ

必須 型
database ✔️ はい string

説明

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

アイテム ポリシーの例 Predicate
@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。 結果ペイロードには、要求メタデータとデータベース ポリシー式の 両方 を満たすレコードのみが含まれます。

制限事項

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

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

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

サポートされている OData に似た演算子
演算子 説明 サンプル構文
and 論理積 "@item.status eq 'active' and @item.age gt 18"
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"

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

演算子 説明 サンプル構文
- 否定 (数値) "@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>" : "<field-1-alias>",
        "<field-2-name>" : "<field-2-alias>",
        "<field-3-name>" : "<field-3-alias>"
      }
    }
  }
}

この例では、 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 インターフェイス用に構成されており、これらのエンドポイントを介してデータのクエリまたは操作が可能であることを示します。

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

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

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

データベース

必須: ✔️ はい

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

注意

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

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

詳細については、「 述語」を参照してください。

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

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

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

注意

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

例

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

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

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

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

制限事項

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

ヒント

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

GraphQL (エンティティ)

必須: ❌ いいえ

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

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

フォーマット

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

{
  "entities": {
    "<string>": {
      "graphql": "<boolean>"
    }
  }
}

{
  "entities": {
    "<string>": {
      "graphql": {
        "enabled": "<boolean>",
        "type": "<string-or-object>",
        "operation": "<enum-string>"
      }
    }
  }
}

プロパティ

必須 型
enabled ❌ いいえ ブール値
type ❌ いいえ 文字列またはオブジェクト
operation ❌ いいえ 列挙型文字列

例

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

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

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

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

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

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

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

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

Type (GraphQL エンティティ)

必須: ❌ いいえ

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

フォーマット

{
  "entities": {
    "<string>": {
      "graphql": {
        "type": "<string>"
      }
    }
  }
}

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

プロパティ

必須 型
singular ❌ いいえ string
plural ❌ いいえ string

例

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.plural プロパティを使用しますtype.singular。 この例では、両方の名前を明示的に設定します。

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

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

{
  bookauthors {
    items {
      first_name
      last_name
    }
  }
}

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

操作 (GraphQL エンティティ)

必須: ❌ いいえ

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

注意

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

見つからない場合、 operation 既定値は です mutation。

フォーマット

{
  "entities": {
    "<string>": {
      "graphql": {
        "operation": "<string-enum>"
      }
    }
  }
}

値

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

説明
query 基になるストアド プロシージャがクエリとして公開される
mutation 基になるストアド プロシージャは、ミューテーションとして公開されます

例

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

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

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

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

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

注意

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

Enabled (GraphQL エンティティ)

必須: ❌ いいえ

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

フォーマット

{
  "entities" {
    "<entity-name>": {
      ...
      "graphql": {
        ...
        "enabled": true | false
      }
    }
  }
}

REST (エンティティ)

必須: ❌ いいえ

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

フォーマット

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": "/entity-path", (default <entity-name>)
        "methods": ["GET", "POST" (default)]
      },
      ...
    }
  }
}

プロパティ

必須 型
enabled ✔️ はい ブール値
path ❌ いいえ string
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"
      },
      ...
    }
  }
}

有効 (REST エンティティ)

必須: ❌ いいえ

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

省略した場合、または欠落している場合、 の enabled 既定値は です true。

フォーマット

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

パス (REST エンティティ)

必須: ❌ いいえ

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

Format

{
  "entities" {
    "<entity-name>": {
      ...
      "rest": {
        ...
        "path": "/entity-path"
      }
    }
  }
}

例

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

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

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

必須: ❌ いいえ

ストアド プロシージャに特に適用できる プロパティは、プロシージャが 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" ]
      }
    }
  }
}

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

必須: ❌ いいえ

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

重要

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

Format

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

例

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

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

マッピングのもう 1 つの例を次に示します。

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

マッピング: オブジェクトはmappings、データベース フィールド (BookID、、) を、BookTitleAuthorName外部で使用されるより直感的または標準化された名前 (id、、titleauthor) にリンクします。 このエイリアシングは、いくつかの目的に役立ちます。

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

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

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

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

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

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

必須: ❌ いいえ

このセクションマップには、エンティティが他の公開エンティティとどのように関連しているかをマップするリレーションシップ定義のセットが含まれています。 これらのリレーションシップ定義には、必要に応じて、リレーションシップのサポートと適用に使用される基になるデータベース オブジェクトの詳細を含めることもできます。 このセクションで定義されているオブジェクトは、関連エンティティの 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": "target-entity-name",
          "source.fields": ["source-field-name"],
          "target.fields": ["target-field-name"],
          "linking.object": "linking-object-name",
          "linking.source.fields": ["linking-source-field-name"],
          "linking.target.fields": ["linking-target-field-name"]
        }
      }
    }
  }
}

プロパティ

必須 型
cardinality ✔️ はい 列挙型文字列
target.entity ✔️ はい string
source.fields ❌ いいえ 文字列配列
target.fields ❌ いいえ 文字列配列
linking.<object-or-entity> ❌ いいえ string
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]!
}
多対一

次に、カーディナリティ を に 設定する多対一を検討します one。 公開される 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、ソース エンティティ () のcategory_idフィールドが、関連するターゲット エンティティCategory (Book) のフィールドを参照idすることを指定します。 逆に、リストは target.fields 逆リレーションシップを指定します。 このリレーションシップにより、結果の GraphQL スキーマに Books から Categories へのマッピングが含まれるようになりました。

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

最後に、 多対多 リレーションシップは のカーディナリティ many とより多くのメタデータを使用して定義され、バッキング データベースでリレーションシップを作成するために使用されるデータベース オブジェクトを定義します。 ここでは、エンティティに複数AuthorのBookエンティティを含め、逆にエンティティに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": {
        ...
      }
    }
  }
}

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

この例は、この例と同様の GraphQL スキーマを使用して説明できます。

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

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

カーディナリティ

必須: ✔️ はい

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

値

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

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

ターゲット エンティティ

必須: ✔️ はい

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

ソース フィールド

必須: ❌ いいえ

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

ヒント

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

対象フィールド

必須: ❌ いいえ

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

ヒント

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

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

必須: ❌ いいえ

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

リンク元フィールド

必須: ❌ いいえ

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

リンク先フィールド

必須: ❌ いいえ

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

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

必須: ❌ いいえ

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

フォーマット

{
  "entities": {
    "<string>": {
      "cache": {
        "enabled": <true> | <false> (default),
        "ttl-seconds": (integer, default: 5)
      }
    }
  }
}

プロパティ

必須 Type Default
enabled ❌ いいえ ブール値 false
ttl-seconds ❌ いいえ 整数 (integer) 5

例

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

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

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

必須: ❌ いいえ

エンティティのキャッシュを有効にします。 既定値は false です。

Format

{
  "entities": {
    "<string>": {
      "cache": {
        "enabled": "<boolean>"
      }
    }
  }
}

例

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

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

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

必須: ❌ いいえ

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

Format

{
  "entities": {
    "<string>": {
      "cache": {
        "ttl-seconds": "<integer>"
      }
    }
  }
}

例

この例では、キャッシュが有効になっており、項目の有効期限は 15 秒後です。

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

関連コンテンツ