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

모드(호스트 런타임)

개발 동작

• GraphQL 테스트에 니트로(이전의 바나나 케이크 팝) 사용
• REST 테스트에 Swagger UI 사용
• 익명 상태 검사 사용
• 로깅 세부 정보 표시 증가(디버그)

Format

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

최대 응답 크기(호스트 런타임)

지정된 결과에 대한 최대 크기(메가바이트)를 설정합니다. 대용량 응답은 시스템에 max-response-size-mb 부담을 줄 수 있으므로 오버로드를 방지하기 위해 총 크기(행 개수와 다름)의 한도를 지정합니다. 특히 텍스트 또는 JSON과 같은 큰 열이 있습니다.

Format

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

GraphQL(런타임)

전역 GraphQL 구성.

중첩 속성

속성 정보

• 하위 경로는 속성에 대해 path 허용되지 않습니다.
• 중첩된 쿼리를 제한하는 데 사용합니다 depth-limit .
• GraphQL 스키마를 숨기도록 allow-introspection 설정합니다false.
• 단일 변형에 여러 엔터티를 삽입하는 데 사용합니다 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 구성.

중첩 속성

속성 정보

• 전역 enabled 인 false경우 개별 엔터티 수준은 enabled 중요하지 않습니다.
• 속성은 path 다음과 같은 /api/data하위 경로 값을 지원하지 않습니다.
• request-body-strict .NET POCO 개체를 간소화하기 위해 도입되었습니다.

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

공급자(인증 호스트 런타임)

인증 방법을 선택합니다. 각 공급자는 ID의 유효성을 다르게 검사합니다. 단계별 설정은 다음 표의 방법 가이드를 참조하세요.

공급자 요약

인증되지 않음(기본값)

설정되거나 공급자가 지정되지 않은 경우 Unauthenticated DAB는 JWT를 검사하거나 유효성을 검사하지 않습니다. 모든 요청은 역할로 anonymous 실행됩니다. Azure API Management 또는 애플리케이션 게이트웨이와 같은 프런트 엔드 서비스는 요청이 DAB에 도달하기 전에 인증 또는 액세스 정책을 계속 처리할 수 있지만 DAB는 계속해서 권한을 anonymous부여합니다.

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

AppService

Azure App Service EasyAuth에서 삽입한 ID 헤더를 신뢰합니다.

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

EntraID

Microsoft Entra ID에서 발급한 JWT 토큰의 유효성을 검사합니다.

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

Custom

타사 ID 공급자에서 JWT 토큰의 유효성을 검사합니다.

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

시뮬레이터

로컬 개발 및 테스트를 위한 인증을 시뮬레이션합니다.

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

역할 선택

시뮬레이터를 제외한 모든 공급자의 경우 헤더는 X-MS-API-ROLE 인증된 사용자의 클레임에서 사용할 역할을 선택합니다. 생략하면 요청은 시스템 역할을 사용합니다 Authenticated . 역할 평가에 대한 자세한 내용은 권한 부여 개요를 참조하세요.

JWT(인증 호스트 런타임)

전역 JWT(JSON 웹 토큰) 구성입니다.

중첩 속성

* 둘 다 audience 개체 issuer 가 jwt 있을 때 필요합니다. jwt 개체 자체는 공급자 EntraIDAzureADCustom또는 .

Format

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

페이지 매김(런타임)

REST 및 GraphQL 엔드포인트에 대한 전역 페이지 매김 제한입니다.

중첩 속성

지원되는 최대 페이지 크기 값

기본 페이지 크기 지원 값

다음 링크 상대 동작

페이지 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(REST) 또는 $limit (GraphQL)을 설정 first 하여 -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 DAB는 true로컬 메모리 내 캐시 외에도 구성된 분산 캐시 공급자를 사용합니다. 캐시 수준으로 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(원격 분석)

원격 분석 열기로 로깅을 구성합니다.

중첩 속성

여러 헤더가 , (쉼표)로 구분됩니다.

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- 데이터 API 작성기에서 제공되는 로그를 구분하기 위해 Log Analytics에 전달된 레이블입니다.
• flush-interval-seconds- 원격 분석 데이터의 일괄 처리 전송 사이의 시간 간격(초)입니다.
• custom-table-name- 데이터가 저장되는 Azure Log Analytics의 사용자 지정 테이블 이름입니다.
• dcr-immutable-id- 데이터 수집 방법을 정의하는 데이터 수집 규칙의 변경할 수 없는 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(런타임)

데이터베이스 엔터티를 AI 에이전트용 MCP 도구로 노출하는 MCP(SQL 모델 컨텍스트 프로토콜) 서버를 구성합니다.

중첩 속성

이 속성은 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"truefalse사용하거나 사용하지 않도록 설정하려면

런타임 수준에서 도구를 사용하지 않도록 설정하면 도구가 MCP tools/list 응답에 표시되지 않으며 엔터티 수준 권한에 관계없이 호출할 수 없습니다. 개별 DML 도구에 대한 자세한 내용은 DML(데이터 조작 언어) 도구를 참조하세요.

CLI 사용

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