Runtime

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

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

Параметры REST

Параметры GraphQL

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

Параметры CORS

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

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

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

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

{
  "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: "AppService"),
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  },
  "cache": {
    "enabled": <true>|<false> (default: `false`),
    "ttl-seconds": <integer> (default: `5`)
  },
  "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`)
    },
    "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`)
  }
}

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

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

• Включено 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> (default) | <false>
        }
    }
  }
}

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

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> (default) | <false>,
        "origins": ["<array-of-strings>"]
      }
    }
  }
}

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

Определяет метод проверки подлинности, используемый построителем API данных.

Format

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "AppService" | ...
      }
    }
  }
}

Пример: Служба приложений

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

Пример: идентификатор Microsoft Entra

{
 "host": {
  "authentication": {
   "provider": "AzureAD",
   "jwt": {
    "audience": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "issuer": "https://login.microsoftonline.com/98765f43-21ba-400c-a5de-1f2a3d4e5f6a/v2.0"
   }
  }
 }
}

Пример: симулятор (только для разработки)

{
 "host": {
  "mode": "development", // Simulator is not intended for production
  "authentication": {
   "provider": "Simulator"
  }
 }
}

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

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

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

Format

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

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

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

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

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

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

Format

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

Пример: разбиение по страницам в 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 {
      ...
    }
  }
}

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

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

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

Format

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

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

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

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

Настраивает детализацию ведения журнала для каждого пространства имен. Это следует стандартным соглашениям по ведению журналов .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.

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

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

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

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

Format

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

Example

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