Runtime

Параметры конфигурации, определяющие поведение среды выполнения.

Параметры разбиения на страницы

Параметры REST

Параметры GraphQL

Параметры узла

Параметры CORS

Параметры проверки подлинности

Параметры кэша

Параметры сжатия

Настройки телеметрии

Параметры MCP

Обзор формата

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer|null> (default: `100000`),
      "default-page-size": <integer|null> (default: `100`)
    },
    "rest": {
      "path": <string> (default: "/api"),
      "enabled": <true>|<false>,
      "request-body-strict": <true>|<false> (default: `true`)
    },
    "graphql": {
      "path": <string> (default: "/graphql"),
      "enabled": <true>|<false>,
      "allow-introspection": <true>|<false>,
      "depth-limit": <integer|null> (default: `null`),
      "multiple-mutations": {
        "create": {
          "enabled": <true>|<false> (default: `false`)
        }
      }
    },
    "host": {
      "mode": <"production"> (default) | <"development">,
      "max-response-size-mb": <integer|null> (default: `158`),
      "cors": {
        "origins": [ "<string>" ],
        "allow-credentials": <true>|<false> (default: `false`)
      },
      "authentication": {
        "provider": <string> (default: "Unauthenticated"),
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  },
    "compression": {
      "level": <"optimal"> (default) | <"fastest"> | <"none">
    },
    "cache": {
      "enabled": <true>|<false> (default: `false`),
      "ttl-seconds": <integer> (default: `5`),
      "level-2": {
        "enabled": <true>|<false> (default: `false`),
        "provider": <"redis">,
        "connection-string": <string>,
        "partition": <string>
      }
    },
    "telemetry": {
      "application-insights": {
        "connection-string": "<string>",
        "enabled": <true>|<false> (default: `true`)
      },
      "open-telemetry": {
        "endpoint": "<string>",
        "headers": "<string>",
        "service-name": <string> (default: "dab"),
        "exporter-protocol": <"grpc"> (default) | <"httpprotobuf">,
        "enabled": <true>|<false> (default: `true`)
      },
      "azure-log-analytics": {
        "enabled": <true>|<false> (default: `false`),
        "dab-identifier": <string> (default: "DabLogs"),
        "flush-interval-seconds": <integer> (default: `5`),
        "auth": {
          "custom-table-name": <string>,
          "dcr-immutable-id": <string>,
          "dce-endpoint": <string>
        }
      },
      "file": {
        "enabled": <true>|<false> (default: `false`),
        "path": <string> (default: "/logs/dab-log.txt"),
        "rolling-interval": <string> (default: "Day"),
        "retained-file-count-limit": <integer> (default: `1`),
        "file-size-limit-bytes": <integer> (default: `1048576`)
      },
      "log-level": {
        // namespace keys
        "<namespace>": <"trace"|"debug"|"information"|"warning"|"error"|"critical"|"none"|null>
      }
    },
    "health": {
      "enabled": <true>|<false> (default: `true`),
      "roles": [ "<string>" ],
      "cache-ttl-seconds": <integer> (default: `5`),
      "max-query-parallelism": <integer> (default: `4`)
    },
    "mcp": {
      "enabled": <true>|<false> (default: `true`),
      "path": <string> (default: `"/mcp"`),
      "description": <string>,
      "dml-tools": <true>|<false> | {
        "describe-entities": <true>|<false> (default: `true`),
        "create-record": <true>|<false> (default: `true`),
        "read-records": <true>|<false> (default: `true`),
        "update-record": <true>|<false> (default: `true`),
        "delete-record": <true>|<false> (default: `true`),
        "execute-entity": <true>|<false> (default: `true`),
        "aggregate-records": <true>|<false> | {
          "enabled": <true>|<false> (default: `true`),
          "query-timeout": <integer> (default: `30`)
        }
      }
    }
  }
}

Режим (среда выполнения узла)

Поведение разработки

• Включено Nitro (ранее банановый торт pop) для тестирования GraphQL
• Включенный пользовательский интерфейс Swagger для тестирования REST
• Включена анонимная проверка работоспособности
• Повышенная детализация ведения журнала (отладка)

Format

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

Максимальный размер ответа (среда выполнения узла)

Задает максимальный размер (в мегабайтах) для любого заданного результата. Так как большие ответы могут напрягать систему, max-response-size-mb заголовок общего размера (отличается от количества строк), чтобы предотвратить перегрузку, которая особенно с большими столбцами, такими как текст или JSON.

Format

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

GraphQL (среда выполнения)

Конфигурация Global GraphQL.

Вложенные свойства

Заметки о свойствах

• Подпаты не допускаются для path свойства.
• Используется depth-limit для ограничения вложенных запросов.
• Установите для allow-introspectionfalse скрытия схемы GraphQL.
• Используется multiple-mutations для вставки нескольких сущностей в одну мутацию.

Format

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

Пример: несколько мутаций

Configuration

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

Мутация GraphQL

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 (среда выполнения)

Глобальная конфигурация REST.

Вложенные свойства

Заметки о свойствах

• Если глобальный enabledfalse, отдельный уровень enabled сущности не имеет значения.
• Свойство path не поддерживает такие значения подпаток, как /api/data.
• request-body-strict был представлен для упрощения объектов POCO .NET.

Format

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

Пример: request-body-strict

• Столбцы со default() значением игнорируются только в INSERT том случае, если их значение в полезных данных nullравно. В результате INSERT операции с default() столбцами, когда request-body-strict они есть true, не могут привести к явным null значениям. Для выполнения этого поведения UPDATE требуется операция.
• Столбцы с ней default() не игнорируются во время UPDATE независимо от значения полезных данных.
• Вычисляемые столбцы всегда игнорируются.
• Автоматически созданные столбцы всегда игнорируются.

Пример таблицы

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

Тело запроса

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

Вставка поведения при request-body-strict = false

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

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`)
}

CORS (среда выполнения узла)

Глобальная конфигурация CORS.

Вложенные свойства

Format

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

Поставщик (среда выполнения узла проверки подлинности)

Выбирает метод проверки подлинности. Каждый поставщик проверяет удостоверение по-разному. Пошаговые инструкции по настройке см. в руководствах в следующей таблице.

Сводка поставщика

Не прошедший проверку подлинности (по умолчанию)

Если Unauthenticated задано (или не указан поставщик), DAB не проверяет и не проверяет JWT. Все запросы выполняются в качестве anonymous роли. Интерфейсная служба, такая как управление API Azure или шлюз приложений, по-прежнему может обрабатывать проверку подлинности или политику доступа, прежде чем запрашивать DAB, но DAB продолжает авторизовать только как anonymous.

{
  "host": {
    "authentication": {
      "provider": "Unauthenticated"
    }
  }
}

AppService

Доверяет заголовкам удостоверений, внедренным службой приложений Azure EasyAuth.

{
  "host": {
    "authentication": {
      "provider": "AppService"
    }
  }
}

EntraID

Проверяет токены JWT, выданные идентификатором Microsoft Entra.

{
  "host": {
    "authentication": {
      "provider": "EntraId",
      "jwt": {
        "audience": "<application-id>",
        "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0"
      }
    }
  }
}

Custom

Проверяет маркеры JWT от сторонних поставщиков удостоверений.

{
  "host": {
    "authentication": {
      "provider": "Custom",
      "jwt": {
        "audience": "<api-audience>",
        "issuer": "https://<your-idp-domain>/"
      }
    }
  }
}

Симулятор

Имитирует проверку подлинности для локальной разработки и тестирования.

{
  "host": {
    "authentication": {
      "provider": "Simulator"
    }
  }
}

Выбор роли

Для всех поставщиков, кроме симулятора, X-MS-API-ROLE заголовок выбирает роль, используемую из утверждений пользователя, прошедших проверку подлинности. Если опущено, запрос использует системную Authenticated роль. Дополнительные сведения об оценке ролей см. в обзоре авторизации.

JWT (среда выполнения узла проверки подлинности)

Конфигурация глобального веб-маркера JSON (JWT).

Вложенные свойства

audience* Оба и issuer обязательны, когда jwt объект присутствует. Сам jwt объект требуется, если поставщик имеет EntraIDзначение , AzureADили Custom.

Format

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

Разбиение на страницы (среда выполнения)

Глобальные ограничения на страницы для конечных точек REST и GraphQL.

Вложенные свойства

Поддерживаемые значения максимального размера страницы

Поддерживаемые значения размера страницы по умолчанию

Относительное поведение next-link

Если next-link-relative это trueтак, значения разбиения nextLink на страницы используют относительные URL-адреса вместо абсолютных URL-адресов.

Format

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>,
      "default-page-size": <integer; default: 100>,
      "next-link-relative": <boolean; default: false>
    }
  }
}

Пример: разбиение по страницам в REST

Request

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

Следующая страница запроса

GET https://localhost:5001/api/users?$after=W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==

Пример. Разбиение по страницам в GraphQL

Полезные данные запроса (запрос)

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

Следующая страница запроса

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

Пример: доступ к запросам max-page-size

Используйте значение, задав max-page-size для параметра $limit REST или first (GraphQL).-1

REST

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

GraphQL

query {
  users(first: -1) {
    items {
      ...
    }
  }
}

Сжатие (среда выполнения)

Конфигурация сжатия http-ответа. Если этот параметр включен, DAB сжимает тела ответа, чтобы уменьшить размеры полезных данных и повысить скорость передачи.

Вложенные свойства

Поддерживаемые значения для level

Заголовки HTTP клиента

Сжатие вызывается заголовком клиента Accept-Encoding . Поддерживаются алгоритмы Gzip и Brotli. Параметр level настраивает стратегию сжатия, если клиент и сервер поддерживают несколько алгоритмов.

Поддерживаемые заголовки

Format

{
  "runtime": {
    "compression": {
      "level": <"optimal"> (default) | <"fastest"> | <"none">
    }
  }
}

Example

{
  "runtime": {
    "compression": {
      "level": "optimal"
    }
  }
}

Кэш (среда выполнения)

Конфигурация глобального кэша.

Вложенные свойства

Format

{
  "runtime": {
    "cache":  {
      "enabled": <boolean>,
      "ttl-seconds": <integer>,
      "level-2": {
        "enabled": <boolean>,
        "provider": "redis",
        "connection-string": <string>,
        "partition": <string>
      }
    }
  }
}

Если level-2.enabled это trueтак, DAB использует настроенный поставщик распределенного кэша в дополнение к локальному кэшу в памяти. Сущность, настроенная на уровне L1L2 кэша, сначала проверяет локальный кэш, а затем распределенный кэш перед переходом в базу данных.

Телеметрия (среда выполнения)

Глобальная конфигурация телеметрии.

Вложенные свойства

Настраивает детализацию ведения журнала для каждого пространства имен. Эта конфигурация соответствует стандартным соглашениям по ведению журнала .NET и позволяет детализировать управление, хотя предполагается, что некоторые знания о внутренних компонентах построитель API данных. Построитель API данных — это открытый исходный код: https://aka.ms/dab

Format

{
  "runtime": {
    "telemetry": {
      "log-level": {
        "namespace": "log-level",
        "namespace": "log-level"
      }
    }
  }
}

Example

{
  "runtime": {
    "telemetry": {
      "log-level": {
        "Azure.DataApiBuilder.Core.Configurations.RuntimeConfigValidator": "debug",
        "Azure.DataApiBuilder.Core": "information",
        "default": "warning"
      }
    }
  }
}

Application Insights (телеметрия)

Настраивает ведение журнала в Application Insights.

Вложенные свойства

Format

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

OpenTelemetry (телеметрия)

Настраивает ведение журнала для Open Telemetry.

Вложенные свойства

Несколько заголовков разделены , запятыми.

Format

{
  "runtime": {
    "telemetry": {
      "open-telemetry": {
        "enabled": <true> (default) | <false>,
        "endpoint": <string>,
        "headers": <string>,
        "service-name": <string> (default: "dab"),
        "exporter-protocol": <"grpc" (default) | "httpprotobuf">
      }
    }
  }
}

Example

{
  "runtime": {
    "telemetry": {
      "open-telemetry": {
        "enabled": true,
        // a gRPC endpoint example
        "endpoint": "http://localhost:4317",
        // an HTTP/protobuf endpoint example
        "endpoint": "http://localhost:4318/v1/metrics",
        "headers": "api-key=key,other-config-value=value",
        "service-name": "dab",
      }
    }
  }
}

Дополнительные сведения о OTEL_EXPORTER_OTLP_HEADERS.

Azure Log Analytics (телеметрия)

Настраивает ведение журнала в Azure Log Analytics с помощью конечной точки сбора данных. При включении DAB отправляет данные телеметрии в пакетах с настраиваемым интервалом.

Вложенные свойства

* auth является обязательным, если enabled имеет значение true.

* Обязательный, если enabled имеет значение true.

• dab-identifier— метка, переданная в Log Analytics, чтобы отличить журналы, поступающие из построителя API данных.
• flush-interval-seconds— интервал времени (в секундах) между отправкой пакетов данных телеметрии.
• custom-table-name— имя настраиваемой таблицы в Azure Log Analytics, в которой хранятся данные.
• dcr-immutable-id— неизменяемый идентификатор правила сбора данных, определяющего способ сбора данных.
• dce-endpoint— URL-адрес конечной точки сбора данных, используемый для отправки данных телеметрии.

Format

{
  "runtime": {
    "telemetry": {
      "azure-log-analytics": {
        "enabled": <true> | <false> (default),
        "dab-identifier": <string> (default: "DabLogs"),
        "flush-interval-seconds": <integer> (default: 5),
        "auth": {
          "custom-table-name": "<string>",
          "dcr-immutable-id": "<string>",
          "dce-endpoint": "<string>"
        }
      }
    }
  }
}

Example

{
  "runtime": {
    "telemetry": {
      "azure-log-analytics": {
        "enabled": true,
        "dab-identifier": "MyDabInstance",
        "flush-interval-seconds": 10,
        "auth": {
          "custom-table-name": "DabTelemetry_CL",
          "dcr-immutable-id": "dcr-abc123def456",
          "dce-endpoint": "https://my-dce.eastus-1.ingest.monitor.azure.com"
        }
      }
    }
  }
}

Файл (телеметрия)

Настраивает запись журналов телеметрии в локальный файл. При включении DAB записывает структурированные выходные данные журнала в указанный путь к файлу с настраиваемыми интервалами и ограничениями размера.

Вложенные свойства

* path является обязательным, если enabled имеет значение true.

Значения скользящего интервала

Format

{
  "runtime": {
    "telemetry": {
      "file": {
        "enabled": <true> | <false> (default),
        "path": <string> (default: "/logs/dab-log.txt"),
        "rolling-interval": <"Day"> (default) | <"Minute"> | <"Hour"> | <"Month"> | <"Year"> | <"Infinite">,
        "retained-file-count-limit": <integer> (default: 1),
        "file-size-limit-bytes": <integer> (default: 1048576)
      }
    }
  }
}

Example

{
  "runtime": {
    "telemetry": {
      "file": {
        "enabled": true,
        "path": "/var/log/dab/dab-telemetry.txt",
        "rolling-interval": "Hour",
        "retained-file-count-limit": 24,
        "file-size-limit-bytes": 5242880
      }
    }
  }
}

MCP (среда выполнения)

Настраивает сервер протокола контекста модели SQL (MCP), который предоставляет сущности базы данных в качестве средств MCP для агентов ИИ.

Вложенные свойства

Свойство dml-tools принимает логическое значение для включения или отключения всех инструментов или объекта для управления отдельными инструментами:

Средство aggregate-records принимает логическое значение или объект с дополнительными параметрами:

Format

{
  "runtime": {
    "mcp": {
      "enabled": <true> (default) | <false>,
      "path": <string> (default: "/mcp"),
      "description": <string>,
      "dml-tools": {
        "describe-entities": <true> | <false>,
        "create-record": <true> | <false>,
        "read-records": <true> | <false>,
        "update-record": <true> | <false>,
        "delete-record": <true> | <false>,
        "execute-entity": <true> | <false>,
        "aggregate-records": {
          "enabled": <true> | <false>,
          "query-timeout": <integer; default: 30>
        }
      }
    }
  }
}

Example

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

Чтобы включить или отключить все средства DML одновременно, установите "dml-tools"true или falseотключите их.

При отключении средства на уровне среды выполнения средство никогда не отображается в ответе MCP tools/list и не может вызываться независимо от разрешений на уровне сущности. Дополнительные сведения о отдельных средствах DML см. в разделе "Язык обработки данных" (DML).

Использование интерфейса командной строки

dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true
dab configure --runtime.mcp.dml-tools.aggregate-records.enabled true

Работоспособность (среда выполнения)

Конфигурация конечной точки глобальной проверки работоспособности (/health).

Вложенные свойства

Поведение в разработке и рабочей среде

Format

{
  "health": {
    "enabled": <true> (default) | <false>,
    "roles": [ <string> ], // required in production
    "cache-ttl-seconds": <integer; default: 5>,
    "max-query-parallelism": <integer; default: 4>
  }
}

Example

{
  "health": {
    "enabled": true,
    "roles": ["admin", "support"],
    "cache-ttl-seconds": 10,
    "max-query-parallelism": 6
  }
}