数据 API 生成器配置架构参考

项目
01/15/2025

数据 API 生成器的引擎需要配置文件。数据 API 生成器配置文件提供了一种结构化且全面的方法来设置 API，详细介绍了环境变量到特定于实体的配置的所有内容。此 JSON 格式的文档以 $schema 属性开头。此设置验证文档。

属性 database-type 和 connection-string 确保从 Azure SQL 数据库到 Cosmos DB NoSQL API 与数据库系统的无缝集成。

配置文件可以包括以下选项：

数据库服务和连接信息
全局和运行时配置选项
公开实体集
身份验证方法
访问标识所需的安全规则
API 和数据库之间的名称映射规则
无法推断的实体之间的关系
特定数据库服务的独特功能

语法概述

下面是配置文件中主要“节”的快速细分。

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

顶级属性

下面是表格式的顶级属性的说明：

财产	描述
$schema	指定用于验证的 JSON 架构，确保配置遵循所需的格式。
数据源	包含有关建立数据库连接所需的数据库类型和连接字符串的详细信息。
data-source-files	指定可能定义其他数据源的其他配置文件的可选数组。
运行时	配置运行时行为和设置，包括 REST、GraphQL、主机、缓存和遥测的子属性。
实体	定义通过 API 公开的实体集（数据库表、视图等），包括其映射、权限以及关系。

示例配置

下面是一个示例配置文件，该文件仅包含单个简单实体的必需属性。此示例旨在演示一个最小的方案。

{
  "$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": {
    "User": {
      "source": "dbo.Users",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

有关更复杂的方案的示例，请参阅端到端示例配置。

环境

数据 API 生成器的配置文件可以支持需要支持多个环境的方案，类似于 ASP.NET Core 中的 appSettings.json 文件。该框架提供三个常见环境值;Development、Staging和 Production;但可以选择使用你选择的任何环境值。必须使用 DAB_ENVIRONMENT 环境变量配置数据 API 生成器使用的环境。

请考虑一个示例，其中需要基线配置和特定于开发的配置。此示例需要两个配置文件：

	环境
dab-config.json	基础
dab-config.Development.json	发展

若要使用特定于开发的配置，必须将 DAB_ENVIRONMENT 环境变量设置为 Development。

特定于环境的配置文件会覆盖基本配置文件中的属性值。在此示例中，如果在这两个文件中设置了 connection-string 值，则使用 *.Development.json 文件中的值。

请参阅此矩阵，根据任一文件中指定或未指定该值的位置，更好地了解使用哪个值。

	在基本配置中指定的	未在基本配置中指定
在当前环境配置中指定的	当前环境	当前环境
当前环境配置中未指定	基础	没有

有关使用多个配置文件的示例，请参阅将数据 API 生成器用于环境。

配置属性

本部分包括可用于配置文件的所有可能配置属性。

图式

父母	财产	类型	必填	违约
`$root`	`$schema`	字符串	✔️ 是的	没有

每个配置文件都以 $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`	使用该工具的 alpha 版本的配置架构。
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`	✔️ 是的	枚举字符串
`connection-string`	✔️ 是的	字符串
`options`	❌ 否	对象

数据库类型

父母	财产	类型	必填	违约
`data-source`	`database-type`	enum-string	✔️ 是的	没有

用于指定要用作数据源的数据库类型的枚举字符串。

格式

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

类型值

type 属性指示后端数据库的类型。

类型	描述	最小版本
`mssql`	Azure SQL 数据库	没有
`mssql`	Azure SQL MI	没有
`mssql`	SQL Server	SQL 2016
`sqldw`	Azure SQL 数据仓库	没有
`postgresql`	PostgreSQL	v11
`mysql`	MySQL	v8
`cosmosdb_nosql`	用于 NoSQL 的 Azure Cosmos DB	没有
`cosmosdb_postgresql`	Azure Cosmos DB for PostgreSQL	没有

连接字符串

父母	财产	类型	必填	违约
`data-source`	`connection-string`	字符串	✔️ 是的	没有

字符串 值，该值包含连接到目标数据库服务的有效连接字符串。要连接到后端数据库的 ADO.NET 连接字符串。有关详细信息，请参阅 ADO.NET 连接字符串。

格式

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

连接复原能力

数据 API 生成器在检测暂时性错误后自动重试数据库请求。重试逻辑遵循 指数退避 策略，其中最大重试次数五。使用此公式计算后续请求后的重试回退持续时间（假设当前重试尝试 r）：$r^2$

使用此公式，可以计算每次重试尝试的时间（以秒为单位）。

	秒
First	`2`
第二个	`4`
第三	`8`
第四	`16`
第五	`32`

Azure SQL 和 SQL Server

数据 API 生成器使用 SqlClient 库通过配置文件中提供的连接字符串连接到 Azure SQL 或 SQL Server。此处提供了所有支持的连接字符串选项的列表：SqlConnection.ConnectionString 属性。

数据 API 生成器还可以在 Azure 中托管数据 API 生成器时使用托管服务标识（MSI）连接到目标数据库。 DefaultAzureCredential 库中定义的 Azure.Identity 用于在连接字符串中未指定用户名或密码时使用已知标识进行连接。有关详细信息，请参阅 DefaultAzureCredential 示例。

用户分配的托管标识（UMI）：将 身份验证 和 用户 ID 属性追加到连接字符串中，同时替换用户分配的托管标识的客户端 ID：Authentication=Active Directory Managed Identity; User Id=<UMI_CLIENT_ID>;。
系统分配的托管标识（SMI）：追加 身份验证 属性，并从连接字符串中排除 UserId 和密码参数：Authentication=Active Directory Managed Identity;。缺少 UserId 和密码连接字符串属性将指示 DAB 使用系统分配的托管标识进行身份验证。

有关使用 Azure SQL 或 SQL Server 配置托管服务标识的详细信息，请参阅 azure SQLMicrosoft Entra 中的托管标识。

例子

用于连接字符串的值在很大程度上取决于方案中使用的数据库服务。始终可以选择将连接字符串存储在环境变量中，并使用 @env() 函数对其进行访问。

	价值	描述
使用 Azure SQL 数据库字符串值	`Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;`	Azure SQL 数据库帐户的连接字符串。有关详细信息，请参阅 Azure SQL 数据库连接字符串。
使用 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('SQL_CONNECTION_STRING')`	从本地计算机访问环境变量。在此示例中，引用 `SQL_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）特定于 Azure Cosmos DB 的 NoSQL API，而不是 PostgreSQL API。对于使用 PostgreSQL API 的 Azure Cosmos DB，“选项”不包括在 NoSQL 设置中 database、container或 schema。

选项

父母	财产	类型	必填	违约
`data-source`	`options`	对象	❌ 否	没有

特定数据库连接的附加键值参数的可选部分。

是否需要 options 节在很大程度上取决于正在使用的数据库服务。

格式

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

options： { set-session-context： boolean }

对于 Azure SQL 和 SQL Server，数据 API 生成器可以利用 SESSION_CONTEXT 将用户指定的元数据发送到基础数据库。此类元数据可通过访问令牌中存在的声明提供给数据 API 生成器。在数据库连接期间，SESSION_CONTEXT 数据可供数据库使用，直到该连接关闭。有关详细信息，请参阅会话上下文。

SQL 存储过程示例：

CREATE PROC GetUser @userId INT AS
BEGIN
    -- Check if the current user has access to the requested userId
    IF SESSION_CONTEXT(N'user_role') = 'admin' 
        OR SESSION_CONTEXT(N'user_id') = @userId
    BEGIN
        SELECT Id, Name, Age, IsAdmin
        FROM Users
        WHERE Id = @userId;
    END
    ELSE
    BEGIN
        RAISERROR('Unauthorized access', 16, 1);
    END
END;

JSON 配置示例：

{
  "$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')",
    "options": {
      "set-session-context": true
    }
  },
  "entities": {
    "User": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["execute"]
        }
      ]
    }
  }
}

解释：

存储过程（GetUser）：
- 该过程检查 SESSION_CONTEXT，以验证调用方是否具有角色 admin 或匹配提供的 userId。
- 未经授权的访问会导致错误。
JSON 配置：
- 启用 set-session-context，以便将用户元数据从访问令牌传递到数据库。
- parameters 属性映射存储过程所需的 userId 参数。
- permissions 块可确保只有经过身份验证的用户才能执行存储过程。

数据源文件

父母	财产	类型	必填	违约
`$root`	`data-source-files`	字符串数组	❌ 否	没有

数据 API 生成器支持不同数据源的多个配置文件，其中一个配置文件指定为管理 runtime 设置的顶级文件。所有配置都共享相同的架构，允许在任何文件中 runtime 设置，而不会出错。子配置会自动合并，但应避免循环引用。实体可以拆分为单独的文件，以便更好地管理，但实体之间的关系必须位于同一文件中。

单个配置文件中作为数组引用的多个配置文件的关系图。

格式

{
  "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 类型的名称[s]。此对象是可选的，仅当默认名称或设置不够时使用。本部分概述了 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 能够基于关系定义处理嵌套查询是一项不可思议的功能，使用户可以提取单个查询中的复杂相关数据。但是，随着用户继续添加嵌套查询，查询的复杂性会增加，这最终可能会损害数据库和 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 运行时中启用和使用多个突变。在这种情况下，create 操作配置为允许在单个请求中创建多个记录，方法是将 runtime.graphql.multiple-mutations.create.enabled 属性设置为 true。

配置示例

此配置可实现多个 create 突变：

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": true
        }
      }
    }
  },
  "entities": {
    "User": {
      "source": "dbo.Users",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["create"]
        }
      ]
    }
  }
}

GraphQL 突变示例

使用上述配置，以下突变在单个操作中创建多个 User 记录：

mutation {
  createUsers(input: [
    { name: "Alice", age: 30, isAdmin: true },
    { name: "Bob", age: 25, isAdmin: false },
    { name: "Charlie", age: 35, isAdmin: true }
  ]) {
    id
    name
    age
    isAdmin
  }
}

REST （运行时）

父母	财产	类型	必填	违约
`runtime`	`rest`	对象	❌ 否	没有

本部分概述了 REST 终结点的全局设置。这些设置充当所有实体的默认值，但在各自的配置中可以按实体重写。

格式

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

性能

财产	必填	类型	违约
`enabled`	❌ 否	布尔	真
`path`	❌ 否	字符串	/应用程序接口
`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 为默认值。

注意

使用静态 Web 应用（预览版）部署数据 API 生成器时，Azure 服务会自动向 URL 注入其他子路径 /data-api。此行为可确保与现有的静态 Web 应用功能兼容。生成的终结点将 /data-api/api/<entity>。这仅适用于静态 Web 应用。

格式

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

重要

此属性不允许用户提供的子路径。

例子

在此示例中，根 REST API URI /data。

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

提示

如果定义 Author 实体，则此实体的终结点将 /data/Author。

请求正文严格（REST 运行时）

父母	财产	类型	必填	违约
`runtime.rest`	`request-body-strict`	布尔	❌ 否	真

此设置控制对 REST 突变操作（例如，POST、PUT、PATCH）的请求正文的验证程度。

true（默认）：不映射到表列的请求正文中的额外字段会导致 BadRequest 异常。
false：将忽略额外的字段，并且只处理有效的列。

此设置不应用于 GET 请求，因为始终忽略其请求正文。

具有特定列配置的行为

仅当有效负载中的值 null时，才会在 INSERT 期间忽略具有 default（）值的列。无论有效负载值如何，在 UPDATE 期间不会忽略具有 default（）的列。
始终忽略计算列。
自动生成的列始终被忽略。

格式

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

例子

CREATE TABLE Users (
    Id INT PRIMARY KEY IDENTITY,
    Name NVARCHAR(50) NOT NULL,
    Age INT DEFAULT 18,
    IsAdmin BIT DEFAULT 0,
    IsMinor AS IIF(Age <= 18, 1, 0)
);

示例配置

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

带有 `request-body-strict: false` 的 INSERT 行为

请求有效负载：

{
  "Id": 999,
  "Name": "Alice",
  "Age": null,
  "IsAdmin": null,
  "IsMinor": false,
  "ExtraField": "ignored"
}

生成的 Insert 语句：

INSERT INTO Users (Name) VALUES ('Alice');
-- Default values for Age (18) and IsAdmin (0) are applied by the database.
-- IsMinor is ignored because it’s a computed column.
-- ExtraField is ignored.
-- The database generates the Id value.

响应有效负载：

{
  "Id": 1,          // Auto-generated by the database
  "Name": "Alice",
  "Age": 18,        // Default applied
  "IsAdmin": false, // Default applied
  "IsMinor": true   // Computed
}

使用 `request-body-strict: false` 更新行为

请求有效负载：

{
  "Id": 1,
  "Name": "Alice Updated",
  "Age": null,     // explicitely set to 'null'
  "IsMinor": true, // ignored because computed
  "ExtraField": "ignored"
}

生成的 Update 语句：

UPDATE Users
SET Name = 'Alice Updated', Age = NULL
WHERE Id = 1;
-- IsMinor and ExtraField are ignored.

响应有效负载：

{
  "Id": 1,
  "Name": "Alice Updated",
  "Age": null,
  "IsAdmin": false,
  "IsMinor": false // Recomputed by the database (false when age is `null`)
}

主机（运行时）

父母	财产	类型	必填	违约
`runtime`	`host`	对象	❌ 否	没有

运行时配置中的 host 部分提供对数据 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`	❌ 否	枚举字符串	生产
`cors`	❌ 否	对象	没有
`authentication`	❌ 否	对象	没有

例子

下面是为开发托管配置的运行时的示例。

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

模式（主机运行时）

父母	财产	类型	必填	违约
`runtime.host`	`mode`	字符串	❌ 否	“生产”

定义数据 API 生成器引擎是否应在 development 或 production 模式下运行。默认值为 production。

通常，在开发中运行时，日志的默认详细信息级别设置为 Debug，从而详细公开基础数据库错误。在生产中，日志的详细信息级别设置为 Error。

提示

可以使用 dab start --LogLevel <level-of-detail>进一步替代默认日志级别。有关详细信息，请参阅命令行接口（CLI）参考。

格式

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

值

下面是此属性允许的值列表：

	描述
`production`	在 Azure 上托管生产环境时使用
`development`	在本地计算机上开发中使用

行为

仅在 development 模式下，Swagger 才可用。
仅在 development 模式下才提供香蕉蛋糕流行。

最大响应大小（运行时）

父母	财产	类型	必填	违约
`runtime.host`	`max-response-size-mb`	整数	❌ 否	158

设置任何给定结果的最大大小（以兆字节为单位）。此设置允许用户配置主机平台内存在从基础数据源流式传输数据时可以处理的数据量。

当用户请求大型结果集时，它可以使数据库和数据 API 生成器紧张。为了解决此问题，max-response-size-mb 允许开发人员限制以兆字节为单位的最大响应大小，作为数据源中的数据流。此限制基于总体数据大小，而不是行数。由于列的大小可能会有所不同，因此某些列（如文本、二进制、XML 或 JSON）可以容纳最多 2 GB，从而使单个行可能非常大。此设置通过限制响应大小和防止系统重载，同时保持不同数据类型的灵活性，帮助开发人员保护其终结点。

允许的值

价值	结果
`null`	如果未设置或显式设置为 `null`，则默认值为 158 MB。
`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 标头。

注意

有关 Access-Control-Allow-Credentials 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`	❌ 否	枚举字符串	StaticWebApps
`jwt`	❌ 否	对象	没有

身份验证和客户责任

数据 API 生成器设计为在更广泛的安全管道中运行，在处理请求之前，需要执行重要配置步骤。请务必了解，数据 API 生成器不会根据受信任的标识提供者（例如 Entra ID）提供的有效 JWT 令牌对直接调用方（如 Web 应用程序）进行身份验证，而是对最终用户进行身份验证。当请求到达数据 API 生成器时，它假定 JWT 令牌有效，并针对已配置的任何先决条件（例如特定声明）对其进行检查。然后应用授权规则来确定用户可以访问或修改的内容。

授权通过后，数据 API 生成器使用连接字符串中指定的帐户执行请求。由于此帐户通常需要提升的权限来处理各种用户请求，因此必须尽量减少其访问权限以降低风险。我们建议通过在前端 Web 应用程序和 API 终结点之间配置专用链接以及强化托管数据 API 生成器的计算机来保护体系结构。这些措施有助于确保环境保持安全，保护数据，并最大程度地减少可能利用的漏洞来访问、修改或泄露敏感信息。

提供程序（主机运行时）

父母	财产	类型	必填	违约
`runtime.host.authentication`	`provider`	字符串	❌ 否	“StaticWebApps”

authentication.provider 配置中的 host 设置定义数据 API 生成器使用的身份验证方法。它确定 API 如何验证尝试访问其资源的用户或服务的标识。此设置支持根据不同环境和安全要求定制的各种身份验证机制，实现部署和集成的灵活性。

供应商	描述
`StaticWebApps`	指示数据 API 生成器仅在静态 Web 应用环境中运行时查找一组 HTTP 标头。
`AppService`	当运行时托管在启用了 AppService 身份验证的 Azure AppService 中时（EasyAuth）。
`AzureAd`	需要配置Microsoft Entra Identity，以便它可以对发送到数据 API 生成器（“服务器应用”）的请求进行身份验证。有关详细信息，请参阅 Microsoft Entra ID 身份验证。
`Simulator`	可配置的身份验证提供程序，指示数据 API 生成器引擎将所有请求视为经过身份验证。有关详细信息，请参阅本地身份验证。

格式

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

值

下面是此属性允许的值列表：

	描述
`StaticWebApps`	Azure 静态 Web 应用
`AppService`	Azure 应用服务
`AzureAD`	Microsoft Entra ID
`Simulator`	模拟器

JSON Web 令牌（主机运行时）

父母	财产	类型	必填	违约
`runtime.host.authentication`	`jwt`	对象	❌ 否	没有

如果身份验证提供程序设置为 AzureAD（Microsoft Entra ID），则需要此部分为 JSOn Web 令牌（JWT）令牌指定访问群体和颁发者。此数据用于验证Microsoft Entra 租户的令牌。

如果身份验证提供程序为 Microsoft Entra ID AzureAD，则为必需。本部分必须指定 audience 和 issuer，以针对预期的 AzureAD 租户验证收到的 JWT 令牌以进行身份验证。

设置	描述
观众	标识令牌的预期收件人;通常，Microsoft Entra Identity（或标识提供者）中注册的应用程序标识符，确保确实为应用程序颁发了令牌。
发行	指定颁发机构 URL，即颁发 JWT 的令牌服务。此 URL 应与从中获取 JWT 的标识提供者颁发者 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 服务器 表示在成功登录时向客户端颁发 JWT 令牌的身份验证服务。然后，客户端将令牌传递给 DAB，该令牌可以询问其声明和属性。

数据 API 生成器中 JSON Web 令牌支持的示意图。

下面是在解决方案中可能做出的各种体系结构选择的情况下 host 属性的示例。

Azure 静态 Web 应用

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

使用 StaticWebApps，数据 API 生成器要求 Azure 静态 Web 应用对请求进行身份验证，并且存在 X-MS-CLIENT-PRINCIPAL HTTP 标头。

Azure 应用服务

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

身份验证委托给受支持的标识提供者，可在其中颁发访问令牌。获取的访问令牌必须包含在对数据 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`	对象	❌ 否	没有

为 REST 和 GraphQL 终结点配置分页限制。

格式

{
  "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": 1000,
      "default-page-size": 2
    }
  },
  "entities": {
    "Users": {
      "source": "dbo.Users",
      "permissions": [
        {
          "actions": ["read"],
          "role": "anonymous"
        }
      ]
    }
  }
}

REST 分页示例

在此示例中，发出 REST GET 请求 https://localhost:5001/api/users 将返回 value 数组中的两条记录，因为 default-page-size 设置为 2。如果存在更多结果，数据 API 生成器在响应中包含 nextLink。 nextLink 包含用于检索下一页数据的 $after 参数。

请求：

GET https://localhost:5001/api/users

响应：

{
  "value": [
    {
      "Id": 1,
      "Name": "Alice",
      "Age": 30,
      "IsAdmin": true,
      "IsMinor": false
    },
    {
      "Id": 2,
      "Name": "Bob",
      "Age": 17,
      "IsAdmin": false,
      "IsMinor": true
    }
  ],
  "nextLink": "https://localhost:5001/api/users?$after=W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
}

使用 nextLink，客户端可以提取下一组结果。

GraphQL 分页示例

对于 GraphQL，请使用分页的 hasNextPage 和 endCursor 字段。这些字段指示是否有更多结果可用，并提供用于提取下一页的游标。

查询：

query {
  users {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

响应：

{
  "data": {
    "users": {
      "items": [
        {
          "Id": 1,
          "Name": "Alice",
          "Age": 30,
          "IsAdmin": true,
          "IsMinor": false
        },
        {
          "Id": 2,
          "Name": "Bob",
          "Age": 17,
          "IsAdmin": false,
          "IsMinor": true
        }
      ],
      "hasNextPage": true,
      "endCursor": "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
    }
  }
}

若要提取下一页，请在下一个查询中包含 endCursor 值：

使用游标进行查询：

query {
  users(after: "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==") {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

调整页面大小

REST 和 GraphQL 都允许使用 $limit （REST）或 first （GraphQL）调整每个查询的结果数。

`$limit` / `first` 值	行为
`-1`	默认为 `max-page-size`。
`< max-page-size`	将结果限制为指定的值。
`0` 或 `< -1`	不支持。
`> max-page-size`	封顶在 `max-page-size`。

REST 查询示例：

GET https://localhost:5001/api/users?$limit=5

示例 GraphQL 查询：

query {
  users(first: 5) {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
  }
}

最大页面大小（分页运行时）

父母	财产	类型	必填	违约
`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

为缓存的项配置生存时间（TTL）值（以秒为单位）。此时间过后，会自动从缓存中修剪项。默认值为 5 秒。

格式

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

例子

在此示例中，缓存是全局启用的，所有项将在 15 秒后过期。

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

遥测（运行时）

父母	财产	类型	必填	违约
`runtime`	`telemetry`	对象	❌ 否	没有

此属性将 Application Insights 配置为集中化 API 日志。了解更多。

格式

{
  "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 对象指示数据 API 生成器公开名为 User 的 GraphQL 实体，以及可通过 /User 路径访问的 REST 终结点。 dbo.User 数据库表支持实体，配置允许任何人匿名访问终结点。

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

此示例声明 User 实体。此名称 User 用于引用实体的配置文件中的任何位置。否则，实体名称与终结点无关。

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table",
        "key-fields": ["Id"],
        "parameters": {} // only when source.type = stored-procedure
      },
      "rest": {
        "enabled": true,
        "path": "/users",
        "methods": [] // only when source.type = stored-procedure
      },
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "User",
          "plural": "Users"
        },
        "operation": "query"
      },
      "mappings": {
        "id": "Id",
        "name": "Name",
        "age": "Age",
        "isAdmin": "IsAdmin"
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"],  // "execute" only when source.type = stored-procedure
          "fields": {
            "include": ["id", "name", "age", "isAdmin"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userId eq @item.id"
          }
        },
        {
          "role": "admin",
          "actions": ["create", "read", "update", "delete"],
          "fields": {
            "include": ["*"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userRole eq 'UserAdmin'"
          }
        }
      ]
    }
  }
}

源

父母	财产	类型	必填	违约
`entities.{entity}`	`source`	对象	✔️ 是的	没有

{entity}.source 配置连接 API 公开的实体及其基础数据库对象。此属性指定实体表示的数据库表、视图或存储过程，从而建立用于数据检索和操作的直接链接。

对于实体直接映射到单个数据库表的简单方案，源属性只需要该数据库对象的名称。这种简单性有助于快速设置常见用例："source": "dbo.User"。

格式

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

性能

	必填	类型
`object`	✔️ 是的	字符串
`type`	✔️ 是的	枚举字符串
`parameters`	❌ 否	对象
`key-fields`	❌ 否	字符串数组

例子

1.简单表映射：

此示例演示如何将 User 实体与源表关联 dbo.Users。

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

配置

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

2.存储过程示例：

此示例演示如何将 User 实体与源过程 dbo.GetUsers相关联。

SQL

CREATE PROCEDURE GetUsers 
     @IsAdmin BIT 
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;

配置

{
  "entities": {
    "User": {
      "source": {
        "type": "stored-procedure",
        "object": "GetUsers",
        "parameters": {
          "IsAdmin": "boolean"
        }
      },
      "mappings": {
        "Id": "id",
        "Name": "name",
        "Age": "age",
        "IsAdmin": "isAdmin"
      }
    }
  }
}

mappings 属性对于存储过程是可选的。

对象

父母	财产	类型	必填	违约
`entities.{entity}.source`	`object`	字符串	✔️ 是的	没有

要使用的数据库对象的名称。如果对象属于 dbo 架构，则指定架构是可选的。此外，可以使用或省略对象名称周围的方括号（例如，[dbo].[Users] 与 dbo.Users）。

例子

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

配置

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

不带架构和括号的替代表示法：

如果表位于 dbo 架构中，则可以省略架构或括号：

{
  "entities": {
    "User": {
      "source": {
        "object": "Users",
        "type": "table"
      }
    }
  }
}

类型（实体）

父母	财产	类型	必填	违约
`entities.{entity}.source`	`type`	字符串	✔️ 是的	没有

type 属性标识实体背后的数据库对象类型，包括 view、table和 stored-procedure。此属性是必需的，并且没有默认值。

格式

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

值

价值	描述
`table`	表示表。
`stored-procedure`	表示存储过程。
`view`	表示视图。

例子

1.表示例：

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

配置

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

2.查看示例：

SQL

CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;

配置

{
  "entities": {
    "AdminUsers": {
      "source": {
        "object": "dbo.AdminUsers",
        "type": "view",
        "key-fields": ["Id"]
      },
      "mappings": {
        "Id": "id",
        "Name": "name",
        "Age": "age"
      }
    }
  }
}

注意： 指定 key-fields 对于视图非常重要，因为它们缺少固有的主键。

3.存储过程示例：

SQL

CREATE PROCEDURE dbo.GetUsers (@IsAdmin BIT)
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;

配置

{
  "entities": {
    "User": {
      "source": {
        "type": "stored-procedure",
        "object": "GetUsers",
        "parameters": {
          "IsAdmin": "boolean"
        }
      }
    }
  }
}

键字段

父母	财产	类型	必填	违约
`entities.{entity}.source`	`key-fields`	字符串数组	❌ 否	没有

{entity}.key-fields 属性对于由视图支持的实体尤其必要，因此数据 API 生成器知道如何标识和返回单个项。如果 type 设置为 view 而不指定 key-fields，引擎将拒绝启动。允许对表和存储过程使用此属性，但在这些情况下不使用此属性。

重要

如果对象的类型为 view，则此属性是必需的。

格式

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

示例：使用键字段查看

此示例使用 dbo.AdminUsers 视图，Id 指示为键字段。

SQL

CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;

配置

{
  "entities": {
    "AdminUsers": {
      "source": {
        "object": "dbo.AdminUsers",
        "type": "view",
        "key-fields": ["Id"]
      }
    }
  }
}

参数

父母	财产	类型	必填	违约
`entities.{entity}.source`	`parameters`	对象	❌ 否	没有

entities.{entity}.source 中的 parameters 属性用于存储过程支持的实体。它确保存储过程所需的参数名称和数据类型的正确映射。

重要

如果对象的 typestored-procedure 且需要参数，则需要 parameters 属性。

格式

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

示例 1：不带参数的存储过程

SQL

CREATE PROCEDURE dbo.GetUsers AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users;

配置

{
  "entities": {
    "Users": {
      "source": {
        "object": "dbo.GetUsers",
        "type": "stored-procedure"
      }
    }
  }
}

示例 2：带参数的存储过程

SQL

CREATE PROCEDURE dbo.GetUser (@userId INT) AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users
WHERE Id = @userId;

配置

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      }
    }
  }
}

权限

父母	财产	类型	必填	违约
`entities.{entity}`	`permissions`	对象	✔️ 是的	没有

本部分定义谁可以访问相关实体以及允许哪些操作。权限在角色和 CRUD 操作方面定义：create、read、update和 delete。 permissions 节指定哪些角色可以访问相关实体和使用哪些操作。

格式

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

行动	描述
`create`	允许在实体中创建新记录。
`read`	允许从实体读取或检索记录。
`update`	允许更新实体中的现有记录。
`delete`	允许从实体中删除记录。
`execute`	允许执行存储过程或操作。
`*`	授予所有适用的 CRUD 操作。

例子

示例 1：用户实体上的匿名角色

在此示例中，定义 anonymous 角色，并有权访问 User 实体上的所有可能操作。

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

示例 2：匿名角色的混合操作

此示例演示如何混合 User 实体的字符串和对象数组操作。

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

匿名角色：允许匿名用户读取除假设敏感字段（例如 secret-field）之外的所有字段。将 "include": ["*"] 与 "exclude": ["secret-field"] 一起使用会隐藏 secret-field，同时允许访问所有其他字段。

经过身份验证的角色：允许经过身份验证的用户读取和更新特定字段。例如，显式包括 id、name和 age，但排除 isAdmin 可以演示排除项如何替代包含。

管理员角色：管理员可以对所有字段执行所有操作（*），而无需排除。使用空 "exclude": [] 数组指定 "include": ["*"] 授予对所有字段的访问权限。

此配置：

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

实际上与：

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

另请考虑此设置：

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

这指定未显式包含任何字段，并且排除所有字段，这通常完全限制访问。

实际使用：此类配置似乎具有逆性，因为它限制了对所有字段的访问。但是，可以在角色执行某些操作（例如创建实体）而不访问其任何数据的情况下使用它。

相同的行为（但语法不同）为：

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

此设置尝试仅包含 Id 和 Name 字段，但由于 exclude中的通配符，排除所有字段。

表达相同逻辑的另一种方法是：

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

鉴于 exclude 优先于 include，指定 exclude: ["*"] 意味着排除所有字段，即使是 include字段也是如此。因此，一目了然，此配置似乎可能会阻止任何字段访问。

反向：如果意图只授予对 Id 和 Name 字段的访问权限，则仅指定 include 节中的这些字段（而不使用排除通配符）更为清晰且更可靠：

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

性能

	必填	类型
`role`	✔️ 是的	字符串
`actions` （string-array）或 `actions` （object-array）	✔️ 是的	对象或字符串数组

角色

父母	财产	类型	必填	违约
`entities.permissions`	`role`	字符串	✔️ 是的	没有

包含所定义权限应用到的角色的名称的字符串。角色设置应在其中执行请求的权限上下文。对于在运行时配置中定义的每个实体，可以定义一组角色和关联权限，用于确定如何通过 REST 和 GraphQL 终结点访问实体。角色不是累加角色。

数据 API 生成器在单个角色的上下文中评估请求：

角色	描述
`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>
          }
        }
      ]
    }
  }
}

例子

此示例定义一个名为 reader 的角色，该角色仅对 User 实体具有 read 权限。

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

当 显示有效的访问令牌并 包含 X-MS-API-ROLE HTTP 标头时，可以使用 <custom-role>，并指定访问令牌的角色声明中包含的用户角色。下面是对 User 实体的 GET 请求的示例，包括授权持有者令牌和 X-MS-API-ROLE 标头，这些标头位于 REST 终结点基础 /api，localhost 使用不同的语言。

GET https://localhost:5001/api/User
Authorization: Bearer <your_access_token>
X-MS-API-ROLE: custom-role

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<your_access_token>");
client.DefaultRequestHeaders.Add("X-MS-API-ROLE", "custom-role");
var response = await client.GetAsync("https://localhost:5001/api/User");

const response = await fetch('https://localhost:5001/api/User', {
  headers: { 
    "Authorization": "Bearer <your_access_token>",
    "X-MS-API-ROLE": "custom-role"
  }
});

import requests

headers = {
  "Authorization": "Bearer <your_access_token>",
  "X-MS-API-ROLE": "custom-role"
}
response = requests.get('https://localhost:5001/api/User', headers=headers)
print(response.json())

操作（string-array）

父母	财产	类型	必填	违约
`entities.permissions`	`actions`	oneOf [string， array]	✔️ 是的	没有

字符串值的数组，其中详细说明了关联角色允许的操作。对于 table 和 view 数据库对象，角色可以使用 create、read、update或 delete 操作的任意组合。对于存储过程，角色只能具有 execute 操作。

行动	SQL 操作
`*`	通配符，包括执行
`create`	插入一行或多行
`read`	选择一行或多行
`update`	修改一行或多行
`delete`	删除一行或多行
`execute`	运行存储过程

注意

对于存储过程，通配符（*）操作仅扩展到 execute 操作。对于表和视图，它扩展到 create、read、update和 delete。

例子

此示例为名为 contributor 的角色提供 create 和 read 权限，并为 User 实体上名为 auditor 的角色 delete 权限。

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

另一个示例：

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "contributor",
          "actions": ["read", "create"]
        }
      ]
    }
  }
}

操作（对象数组）

父母	财产	类型	必填	违约
`entities.permissions`	`actions`	字符串数组	✔️ 是的	没有

一组操作对象，详细描述关联角色允许的操作。对于 table 和 view 对象，角色可以使用 create、read、update或 delete的任意组合。对于存储过程，仅允许 execute。

注意

对于存储过程，通配符（*）操作仅扩展到 execute。对于表/视图，它扩展到 create、read、update和 delete。

格式

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

性能

财产	必填	类型	违约
`action`	✔️ 是的	字符串	没有
`fields`	❌ 否	字符串数组	没有
`policy`	❌ 否	对象	没有

例

此示例仅向 User 实体的 auditor 角色授予 read 权限，并具有字段和策略限制。

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["last_login"]
              },
              "policy": {
                "database": "@item.IsAdmin eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

行动

父母	财产	类型	必填	违约
`entities.permissions.actions[]`	`action`	字符串	✔️ 是的	没有

指定数据库对象上允许的特定操作。

值

	表	视图	存储过程	描述
`create`	✔️ 是的	✔️ 是的	❌ 否	创建新项
`read`	✔️ 是的	✔️ 是的	❌ 否	读取现有项
`update`	✔️ 是的	✔️ 是的	❌ 否	更新或替换项
`delete`	✔️ 是的	✔️ 是的	❌ 否	删除项目
`execute`	❌ 否	❌ 否	✔️ 是的	执行编程操作

格式

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": "<role>",
          "actions": [
            {
              "action": "<string>",
              "fields": {
                "include": [/* fields */],
                "exclude": [/* fields */]
              },
              "policy": {
                "database": "<predicate>"
              }
            }
          ]
        }
      ]
    }
  }
}

例

下面是一个示例，其中允许 anonymous 用户从 User 表中 execute 存储过程和 read。

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            }
          ]
        }
      ]
    },
    "GetUser": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "execute"
            }
          ]
        }
      ]
    }
  }
}

领域

父母	财产	类型	必填	违约
`entities.permissions.actions[]`	`fields`	对象	❌ 否	没有

允许访问数据库对象的特定字段的粒度规范。角色配置是具有两个内部属性的对象类型，include 和 exclude。这些值支持在 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`	对象	❌ 否	没有

每个 policy定义的 action 节定义项级安全规则（数据库策略），这些规则限制从请求返回的结果。子节 database 表示在请求执行期间计算的数据库策略表达式。

格式

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

性能

财产	必填	类型	违约
`database`	✔️ 是的	字符串	没有

描述

database 策略：转换为查询谓词的 OData 类表达式计算，包括 eq、lt和 gt等运算符。为了使请求返回结果，从数据库策略解析的请求的查询谓词在针对数据库执行时必须评估为 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）

数据库策略

创作数据库策略表达式时，可以使用两种类型的指令来管理数据库策略：

命令	描述
`@claims`	访问请求中提供的已验证访问令牌中的声明
`@item`	表示为其定义数据库策略的实体的字段

注意

Azure 静态 Web 应用 身份验证（EasyAuth）配置后，数据库策略中可以使用有限数量的声明类型：identityProvider、userId、userDetails和 userRoles。有关详细信息，请参阅 Azure 静态 Web 应用的客户端主体数据文档。

下面是几个示例数据库策略：

@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"`

有关详细信息，请参阅二进制运算符。

算子	描述	示例语法
`-`	反门（数值）	`"@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 终结点中数据模型的清晰度和可访问性。

例子

考虑使用声明和项指令的数据 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"
      }
    }
  }
}

实体定义：为 REST 和 GraphQL 接口配置 Employee 实体，指示可以通过这些终结点查询或操作其数据。

源配置：标识数据库中的 HRUNITS，employee NUM 作为键字段。

映射：别名用于分别将 employee NUM、employee Name和 department COID 映射到 EmployeeId、EmployeeName和 DepartmentId，从而简化字段名称和可能混淆敏感数据库架构详细信息。

策略应用程序：policy 部分使用类似于 OData 的表达式应用数据库策略。此策略限制对具有 HR 角色的用户（@claims.role eq 'HR'）或 UserId 声明与数据库中 EmployeeId（字段别名）匹配的用户（@claims.userId eq @item.EmployeeId）。它确保员工只能访问自己的记录，除非他们属于人力资源部门。策略可以根据动态条件强制实施行级别安全性。

数据库

父母	财产	类型	必填	违约
`entities.{entity}.permissions.actions.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。

创作数据库策略表达式时，可以使用两种类型的指令来管理数据库策略：

	描述
`@claims`	访问请求中提供的已验证访问令牌中的声明
`@item`	表示为其定义数据库策略的实体的字段

注意

配置 Azure 静态 Web 应用身份验证（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 类型的名称[s]。此对象是可选的，仅当默认名称或设置不够时使用。

此段提供将实体集成到 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`	❌ 否	枚举字符串	没有

例子

这两个示例在功能上是等效的。

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

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

在此示例中，定义的实体 Book，表示我们正在处理一组与数据库中书籍相关的数据。 GraphQL 段内 Book 实体的配置提供了一个明确的结构，说明如何在 GraphQL 架构中表示和交互该实体。

Enabled 属性：Book 实体通过 GraphQL（"enabled": true）提供，这意味着开发人员和用户可以通过 GraphQL 操作查询或改变书籍数据。

Type 属性：实体以单一名称 "Book" 表示，在 GraphQL 架构中 "Books" 复数名称。此区别可确保在查询单个书籍或多本书时，架构提供直观命名的类型（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`	枚举字符串	❌ 否	没有

对于映射到存储过程的实体，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`	基础存储过程以突变的形式公开

例子

当 operationmutation时，GraphQL 架构将类似于：

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

当 operationquery时，GraphQL 架构将类似于：

GraphQL 架构类似于：

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

注意

operation 属性仅关于操作在 GraphQL 架构中的位置，它不会更改操作的行为。

已启用（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`	❌ 否	字符串数组	获取

例子

这两个示例在功能上是等效的。

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

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

下面是实体的 REST 配置的另一个示例。

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

已启用（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>">
      }
    }
  }
}

例子

此示例使用 Author 终结点公开 /auth 实体。

{
  "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": "number"
        }
      },
      "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>"
      }
    }
  }
}

例子

在此示例中，数据库对象 sku_titledbo.magazines 字段使用名称 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 对象将数据库字段（BookID、BookTitle、AuthorName）链接到外部使用的更直观或标准化的名称（id、title、author）。此别名有多种用途：

清晰度和一致性：无论基础数据库架构如何，它都可以跨 API 使用清晰且一致的命名。例如，数据库中的 BookID 表示为 API 中的 id，从而使开发人员与终结点交互更加直观。
GraphQL 符合性：通过提供别名字段名称的机制，可确保通过 GraphQL 接口公开的名称符合 GraphQL 命名要求。注意名称很重要，因为 GraphQL 对名称有严格的规则（例如，没有空格，必须以字母或下划线开头等）。例如，如果数据库字段名称不符合这些条件，则可以通过映射将其别名为合规名称。
灵活性：这种别名增加了数据库架构和 API 之间的抽象层，允许在一个架构和 API 之间进行更改，而无需更改另一个。例如，如果映射保持一致，数据库中的字段名称更改不需要更新 API 文档或客户端代码。
字段名称模糊处理：映射允许对字段名称进行模糊处理，这有助于防止未经授权的用户推断有关数据库架构的敏感信息或存储的数据的性质。
保护专有信息：通过重命名字段，还可以保护可能通过数据库的原始字段名称提示的专有名称或业务逻辑。

关系（实体）

父母	财产	类型	必填	违约
`entities.{entity}`	`relationships`	对象	❌ 否	没有

本部分映射包括一组关系定义，用于映射实体与其他公开实体相关的方式。这些关系定义还可以选择性地包括用于支持和强制执行关系的基础数据库对象的详细信息。本节中定义的对象作为相关实体中的 GraphQL 字段公开。有关详细信息，请参阅数据 API 生成器关系细分。

注意

关系仅与 GraphQL 查询相关。 REST 终结点一次仅访问一个实体，并且无法返回嵌套类型。

relationships 部分概述了数据 API 生成器中的实体如何交互，详细说明了这些关系的关联和潜在数据库支持。每个关系的 relationship-name 属性都是必需的，并且对于给定实体的所有关系必须是唯一的。自定义名称可确保清晰、可识别的连接，并维护从这些配置生成的 GraphQL 架构的完整性。

关系	基数	例
一对多	`many`	一个类别实体可以与多个待办事项实体关联
多对一	`one`	许多待办事项实体可能与一个类别实体相关
多对多	`many`	一个待办事项实体可以与多个用户实体关联，一个用户实体可以与多个待办实体关联

格式

{
  "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`	✔️ 是的	枚举字符串	没有
`target.entity`	✔️ 是的	字符串	没有
`source.fields`	❌ 否	字符串数组	没有
`target.fields`	❌ 否	字符串数组	没有
`linking.<object-or-entity>`	❌ 否	字符串	没有
`linking.source.fields`	❌ 否	字符串数组	没有
`linking.target.fields`	❌ 否	字符串数组	没有

例子

在考虑关系时，最好比较 一对多、多对一和 多对多 关系之间的差异。

一对多

首先，假设与公开的 Category 实体的关系具有与实体 Book 关系。在这里，基数设置为 many。每个 Category 可以有多个相关的 Book 实体，而每个 Book 实体仅与单个 Category 实体相关联。

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

在此示例中，source.fields 列表指定源实体（id）的 Category 字段。此字段用于连接到 target 实体中的相关项。相反，target.fields 列表指定目标实体（category_id）的 Book 字段。此字段用于连接到 source 实体中的相关项。

定义此关系后，生成的公开 GraphQL 架构应类似于此示例。

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

多对一

接下来，请考虑 多对一，将基数设置为 one。公开的 Book 实体可以有一个相关的 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）的 Book 字段引用相关目标实体（id）的 Category 字段。反之，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 都表示关系表使用源（id）和目标（Book）实体的主标识符（Author）。 linking.object 字段指定关系在 dbo.books_authors 数据库对象中定义。此外，linking.source.fields 指定链接对象的 book_id 字段引用 id 实体的 Book 字段，linking.target.fields 指定链接对象的 author_id 字段引用 id 实体的 Author 字段。

可以使用类似于此示例的 GraphQL 架构来描述此示例。

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

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

基数

父母	财产	类型	必填	违约
`entities.{entity}.relationships`	`cardinality`	字符串	✔️ 是的	没有

指定当前源实体是否仅与目标实体的单个实例或多个实例相关。

值

下面是此属性允许的值列表：

	描述
`one`	源仅与目标中的一条记录相关
`many`	源可以与目标中的零对多记录相关

目标实体

父母	财产	类型	必填	违约
`entities.{entity}.relationships`	`target.entity`	字符串	✔️ 是的	没有

在配置中定义为关系目标的其他位置定义的实体的名称。

源字段

父母	财产	类型	必填	违约
`entities.{entity}.relationships`	`source.fields`	数组	❌ 否	没有

一个可选参数，用于定义用于在源实体中映射的字段，该实体用于连接到目标实体中的相关项。

提示

如果两个数据库对象之间存在外键约束，则可以自动推断关系的两个数据库对象之间，则不需要此字段。

目标字段

父母	财产	类型	必填	违约
`entities.{entity}.relationships`	`target.fields`	数组	❌ 否	没有

一个可选参数，用于定义用于在目标实体中用于连接到源实体中相关项的映射的字段。

提示

如果两个数据库对象之间存在外键约束，则可以自动推断关系的两个数据库对象之间，则不需要此字段。

链接对象或实体

父母	财产	类型	必填	违约
`entities.{entity}.relationships`	`linking.object`	字符串	❌ 否	没有

对于多对多关系，包含定义两个其他实体之间的关系所需的数据的数据库对象或实体的名称。

链接源字段

父母	财产	类型	必填	违约
`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

为缓存的项配置生存时间（TTL）值（以秒为单位）。此时间过后，会自动从缓存中修剪项。默认值为 5 秒。

格式

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

例子

在此示例中，启用缓存，项会在 15 秒后过期。省略时，此设置将继承全局设置或默认值。

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

通过

数据 API 生成器配置架构参考

语法概述

顶级属性

示例配置

环境

配置属性

图式

格式

例子

数据源

格式

性能

数据库类型

格式

类型值

连接字符串

格式

连接复原能力

Azure SQL 和 SQL Server

例子

选项

格式

options： { set-session-context： boolean }

SQL 存储过程示例：

JSON 配置示例：

解释：

数据源文件

格式

配置文件注意事项

例子

运行

格式

性能

例子

GraphQL （运行时）

格式

性能

已启用 （GraphQL 运行时）

格式

例子

深度限制（GraphQL 运行时）

例子

路径（GraphQL 运行时）

格式

例子

允许反省 （GraphQL 运行时）

格式

例子

多个突变 （GraphQL 运行时）

格式

性能

多个突变 - 创建 （GraphQL 运行时）

格式

性能

例子

配置示例

GraphQL 突变示例

REST （运行时）

格式

性能

已启用 （REST 运行时）

格式

例子

路径（REST 运行时）

格式

例子

请求正文严格 （REST 运行时）

具有特定列配置的行为

格式

例子

示例配置

带有 request-body-strict: false 的 INSERT 行为

使用 request-body-strict: false 更新行为

主机（运行时）

格式

性能

例子

模式（主机运行时）

格式

已启用（GraphQL 运行时）

允许反省（GraphQL 运行时）

多个突变（GraphQL 运行时）

多个突变 - 创建（GraphQL 运行时）

已启用（REST 运行时）

请求正文严格（REST 运行时）

带有 `request-body-strict: false` 的 INSERT 行为

使用 `request-body-strict: false` 更新行为

源（主机运行时）

JSON Web 令牌（主机运行时）

分页（运行时）

默认页面大小（分页运行时）

已启用（缓存运行时）

已启用（Application Insights 遥测）

连接字符串（Application Insights 遥测）