다음을 통해 공유

Runtime

런타임 동작을 결정하는 구성 설정입니다.

페이지 매김 설정

Property Default Description
runtime.pagination.max 페이지 크기 페이지당 최대 레코드 정의
runtime.pagination.default-page-size 응답당 기본 레코드 설정

REST 설정

Property Default Description
runtime.rest.path "/api" REST 엔드포인트의 기본 경로
runtime.rest.enabled true 모든 엔터티에 대해 REST 요청을 사용하거나 사용하지 않도록 설정할 수 있습니다.
runtime.rest.request-body-strict true true인 경우 요청 본문에서 불필요한 필드를 허용하지 않습니다.

GraphQL 설정

Property Default Description
runtime.graphql.allow-introspection true 기본 GraphQL 스키마 쿼리 허용
runtime.graphql.path "/graphql" GraphQL 엔드포인트의 기본 경로
runtime.graphql.enabled true 모든 엔터티에 대해 GraphQL 요청을 사용하거나 사용하지 않도록 설정할 수 있습니다.
runtime.graphql.depth-limit null GraphQL 쿼리의 최대 허용 깊이
runtime.graphql.multiple-mutations.create.enabled false 모든 엔터티에 대해 다중 만들기 변형 허용

호스트 설정

Property Default Description
runtime.host.max-response-size-mb 158 단일 결과에서 허용되는 데이터베이스 응답의 최대 크기(MB)
runtime.host.mode "production" 실행 모드; "production" 또는 "development"

CORS 설정

Property Default Description
runtime.host.cors.origins [] 허용되는 CORS 원본
runtime.host.cors.allow-credentials false Access-Control-Allow-Credentials 헤더에 대한 값 설정

인증 설정

Property Default Description
runtime.host.authentication.provider null 인증 공급자
runtime.host.authentication.jwt.audience null JWT 대상 그룹
runtime.host.authentication.jwt.issuer null JWT 발급자

캐시 설정

Property Default Description
runtime.cache.enabled false 전역적으로 응답 캐싱 사용
runtime.cache.ttl-seconds 5 전역 캐시의 TL(Time to Live) (초)

텔레메트리 설정

Property Default Description
runtime.telemetry.application-insights.connection-string null Application Insights 연결 문자열
runtime.telemetry.application-insights.enabled false Application Insights 원격 분석을 사용하거나 사용하지 않도록 설정
runtime.telemetry.open-telemetry.endpoint null OpenTelemetry 수집기 URL
runtime.telemetry.open-telemetry.headers {} OpenTelemetry 내보내기 헤더
runtime.telemetry.open-telemetry.service-name "dab" OpenTelemetry 서비스 이름
runtime.telemetry.open-telemetry.exporter-protocol "grpc" OpenTelemetry 프로토콜("grpc" 또는 "httpprotobuf")
runtime.telemetry.open-telemetry.enabled true OpenTelemetry 사용 또는 사용 안 함
runtime.telemetry.log-level.namespace null 네임스페이스별 로그 수준 재정의
runtime.health.enabled true 상태 검사 엔드포인트를 전역적으로 사용하거나 사용하지 않도록 설정
runtime.health.roles null 포괄적인 상태 엔드포인트에 허용되는 역할
runtime.health.cache-ttl-seconds 5 상태 검사 보고서 캐시 항목의 TL(Time to Live) (초)
runtime.health.max 쿼리 병렬 처리 4 최대 동시 상태 검사 쿼리(범위: 1-8)

형식 개요

{
  "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`),
    "max-query-parallelism": <integer> (default: `4`)
  }
}

모드(호스트 런타임)

Parent Property Type Required Default
runtime host enum(production | development) ❌ 아니요 production

개발 동작

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

Format

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

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

Parent Property Type Required Default
runtime.host max-response-size-mb integer ❌ 아니요 158

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

Value Result
설정되지 않음 기본값 사용
null 기본값 사용
integer 모든 양의 32비트 정수
<= 0 지원되지 않음

Format

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

GraphQL(런타임)

Parent Property Type Required Default
runtime graphql object ❌ 아니요 -

전역 GraphQL 구성.

중첩 속성

Parent Property Type Required Default
runtime.graphql enabled boolean ❌ 아니요 None
runtime.graphql path string ❌ 아니요 "/graphql"
runtime.graphql depth-limit integer ❌ 아니요 없음(무제한)
runtime.graphql allow-introspection boolean ❌ 아니요 True
runtime.graphql multiple-mutations.create.enabled boolean ❌ 아니요 False

속성 정보

  • 하위 경로는 속성에 사용할 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> (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(런타임)

Parent Property Type Required Default
runtime rest object ❌ 아니요 -

전역 REST 구성.

중첩 속성

Parent Property Type Required Default
runtime.rest enabled boolean ❌ 아니요 None
runtime.rest path string ❌ 아니요 "/api"
runtime.rest request-body-strict boolean ❌ 아니요 True

속성 정보

  • 전역 enabled 인 false경우 개별 엔터티 수준은 enabled 중요하지 않습니다.
  • 속성은 path 다음과 같은 /api/data하위 경로 값을 지원하지 않습니다.
  • request-body-strict .NET POCO 개체를 간소화하기 위해 도입되었습니다.
request-body-strict Behavior
true 요청 본문의 추가 필드로 인해 예외가 발생합니다 BadRequest .
false 요청 본문의 추가 필드는 무시됩니다.

Format

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

Note

Static Web Apps(미리 보기)를 사용하여 데이터 API 작성기를 배포할 때 Azure 서비스는 URL에 다른 하위 경로를 /data-api 자동으로 삽입합니다. 이 동작은 기존 정적 웹앱 기능과의 호환성을 보장합니다. 결과 엔드포인트는 /data-api/api/<entity>. 이 참고는 Static Web Apps와만 관련이 있습니다.

예: 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(호스트 런타임)

Parent Property Type Required Default
runtime.host cors object ❌ 아니요 -

전역 CORS 구성.

Tip

CORS는 "원본 간 리소스 공유"를 의미합니다. 웹 페이지가 서비스를 제공한 도메인과 다른 도메인에 대한 요청을 수행할 수 있는지 여부를 제어하는 브라우저 보안 기능입니다.

중첩 속성

Parent Property Type Required Default
runtime.host.cors allow-credentials boolean ❌ 아니요 False
runtime.host.cors origins 문자열 배열 ❌ 아니요 None

Note

이 속성은 allow-credentials CORS 헤더를 Access-Control-Allow-Credentials 설정합니다.

Format

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

Note

와일드카드 * 는 에 대한 origins값으로 유효합니다.

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

Parent Property Type Required Default
runtime.host.authentication provider enum(AppService | EntraId | Custom | Simulator) ❌ 아니요 AppService

데이터 API 작성기에서 사용하는 인증 방법을 정의합니다.

익명 전용(인증 공급자)

{
 "host": {
    // omit the authentication section
 }
}

dab-config.json 파일에서 전체 authentication 섹션을 생략하면 인증 공급자가 사용되지 않습니다. 이 경우 데이터 API 작성기는 "인증 없음" 모드에서 작동합니다. 이 모드에서 DAB는 토큰 또는 Authorization 헤더를 찾지 않습니다. 이 X-MS-API-ROLE 구성에서는 헤더도 무시됩니다.

[! 참고] 엔진에 들어오는 모든 요청은 자동으로 즉시 시스템 역할이 anonymous할당됩니다. 그런 다음 액세스 제어는 각 엔터티에 대해 정의한 권한으로만 처리됩니다.

엔터티 권한의 예입니다.

{
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [
        {
          "role": "anonymous",
          "actions": [ "read" ]
        }
      ]
    }
  }
}

이 예제에서는 공급자가 구성되지 않으므로 authentication 들어오는 모든 요청은 자동으로 사용자의 요청으로 anonymous 간주됩니다. 엔터티에 permissions 대한 배열은 Book 역할에 작업을 수행할 anonymous 수 있는 기능을 명시적으로 부여 read 합니다. 액세스를 위해 구성 create 되지 않은 다른 엔터티에 대한 다른 작업(예: update, delete또는 anonymous액세스)을 수행하려는 시도는 거부됩니다.

StaticWebApps(인증 공급자) [사용되지 않음]

{
 "host": {
  "authentication": {
   "provider": "StaticWebApps"
  }
 }
}

이 공급자는 Static Web Apps 미리 보기 기능이 Data Connections 2025년 11월에 사용 중지되었기 때문에 더 이상 사용되지 않습니다. 여전히 작동하지만 Azure Static Web Apps에서 인증의 레거시 구현을 위해 설계되었습니다. 개발자는 Azure의 광범위한 "간편한 인증" 플랫폼을 사용하여 더 나은 장기 지원 및 일관성을 위해 공급자로 마이그레이션 AppService 해야 합니다.

[! 참고] 마이그레이션은 구성 파일에서 공급자 이름을 변경하는 것만큼 간단하지 않습니다. 및 StaticWebApps 공급자는 AppService 역할을 처리하기 위해 헤더 내에서 x-ms-client-principal 서로 다른 JSON 구조를 기대합니다.

AppService(인증 공급자)

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

이 공급자는 Azure Container Apps와 같은 Azure App Service에서 호스트되는 애플리케이션용입니다. Azure 호스팅 환경은 인증을 처리한 다음 요청 헤더를 통해 사용자의 ID 정보를 애플리케이션에 전달합니다. Azure 플랫폼에서 관리하는 간단하고 기본 제공 인증 솔루션을 원하는 개발자를 위한 것입니다.

이 공급자는 헤더의 JWT 토큰을 Authorization 사용하지 않습니다. App Service 플랫폼에서 삽입하는 특수 헤더 X-MS-CLIENT-PRINCIPAL를 사용합니다. 이 헤더에는 사용자의 ID 세부 정보가 포함된 base64로 인코딩된 JSON 개체가 포함되어 있습니다.

익명: 공급자가 AppService 구성되었지만 헤더 없이 X-MS-CLIENT-PRINCIPAL 요청이 도착하는 경우 요청은 시스템 역할에 anonymous할당됩니다.

헤더에서 X-MS-CLIENT-PRINCIPAL 디코딩된 JSON은 일반적으로 다음과 같습니다.

{
  "auth_typ": "aad",
  "claims": [
    {"typ": "roles", "val": "admin"},
    {"typ": "roles", "val": "contributor"}
  ],
  "name_typ": "...",
  "role_typ": "..."
}

역할은 배열 내에 claims 포함됩니다.

X-MS-API-ROLE 헤더 정보

  • 역할 및 동작: X-MS-API-ROLE 헤더는 사용자가 현재 요청에 대해 가정하려는 역할을 지정하는 데 사용됩니다. 이 헤더의 값은 개체 배열 claims 에 있는 X-MS-CLIENT-PRINCIPAL 역할 값 중 하나와 일치해야 합니다.
  • 필요한가요?: 아니요. 헤더가 X-MS-API-ROLE 없는 경우 요청은 시스템 역할의 authenticated 컨텍스트에서 처리됩니다. 즉, 사용자가 로그인된 것으로 인식되지만 토큰에서 특정 애플리케이션 정의 역할로 인식되지는 않습니다.
  • 일치 시 동작: 헤더가 제공되고 해당 값이 클라이언트 보안 주체의 X-MS-API-ROLE역할과 일치하는 경우 claims 사용자는 요청에 대해 해당 역할을 가정합니다.
  • 불일치에 대한 동작: X-MS-API-ROLE 헤더가 제공되지만 값이 클라이언트 보안 주체의 역할과 일치하지 않으면 요청이 상태 코드로 403 Forbidden 거부됩니다. 이렇게 하면 사용자가 할당되지 않은 역할을 클레임할 수 없습니다.

EntraId(인증 공급자)

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

이 공급자는 Microsoft Entra에서 사용자 및 애플리케이션 ID를 사용하여 엔드포인트를 보호합니다. 사용자 또는 다른 서비스가 Entra 테넌트 내에서 보안 액세스가 필요한 모든 서비스에 적합합니다.

[! 참고] 공급자는 EntraId 이전에 이름이 지정 AzureAd되었습니다. 이전 이름은 여전히 작동하지만 개발자는 구성 AzureAd 을 마이그레이션하는 EntraId것이 좋습니다.

이 공급자는 Microsoft Entra에서 발급한 헤더에 Authorization 표준 JWT 전달자 토큰을 예상합니다. 특정 애플리케이션에 대해 토큰을 구성해야 합니다(클레임 사용 audience ). 사용자 또는 서비스 주체에 대한 역할은 토큰 내의 클레임에 있어야 합니다. 코드는 기본적으로 클레임을 roles 찾습니다.

익명: 공급자가 EntraId 구성되었지만 헤더 없이 Authorization 요청이 도착하는 경우 요청은 시스템 역할에 anonymous할당됩니다.

디코딩된 JWT 페이로드는 다음과 같습니다.

{
  "aud": "...", // Audience - your API
  "iss": "https://login.microsoftonline.com/{tenant-id}/v2.0", // Issuer
  "oid": "...", // User or principal object ID
  "roles": [
    "reader",
    "writer"
  ],
  // ... other claims
}

X-MS-API-ROLE 헤더 정보

  • 역할 및 동작: X-MS-API-ROLE 헤더는 사용자가 요청에 대해 가정하려는 역할을 지정하는 데 사용됩니다. 이 헤더의 값은 JWT 토큰 클레임에 있는 roles 역할 값 중 하나와 일치해야 합니다.
  • 필요한가요?: 아니요. 헤더가 X-MS-API-ROLE 없는 경우 요청은 시스템 역할의 authenticated 컨텍스트에서 처리됩니다. 즉, 사용자가 로그인된 것으로 인식되지만 토큰에서 특정 애플리케이션 정의 역할로 인식되지는 않습니다.
  • 일치 시 동작: 헤더가 X-MS-API-ROLE 제공되고 클레임의 역할 roles 과 일치하는 경우 사용자의 컨텍스트가 해당 역할로 설정됩니다.
  • 불일치의 동작: X-MS-API-ROLE 헤더가 제공되지만 해당 값이 클레임의 역할 roles 과 일치하지 않으면 요청이 상태 코드로 403 Forbidden 거부됩니다. 이렇게 하면 사용자가 할당되지 않은 역할을 클레임할 수 없습니다.

사용자 지정(인증 공급자)

{
 "host": {
  "authentication": {
   "provider": "Custom",
   "jwt": {
    "audience": "<client-id-or-api-audience>",
    "issuer": "https://<your-domain>/oauth2/default"
   }
  }
 }
}

이 공급자는 JWT를 발급하는 타사 ID 공급자(예: Auth0, Okta 또는 사용자 지정 ID 서버)와 데이터 API 작성기를 통합하려는 개발자를 위한 것입니다. 필요한 audience 토큰과 issuer 토큰을 유연하게 구성할 수 있습니다.

공급자는 Custom 헤더에 표준 JWT 전달자 토큰을 기대합니다 Authorization . 공급자의 EntraId 주요 차이점은 유효한 issueraudience 데이터 API 작성기 구성 파일에서 구성한다는 것입니다. 공급자는 신뢰할 수 있는 기관에서 토큰을 발급했는지 확인하여 토큰의 유효성을 검사합니다. 사용자의 역할은 JWT 페이로드 내의 roles 클레임에 있어야 합니다.

[! 참고] 경우에 따라 타사 ID 공급자에 따라 개발자는 데이터 API 작성기에서 예상하는 구조와 일치하도록 JWT의 구조를 강제 변환해야 합니다(아래 참조).

익명: 공급자가 Custom 구성되었지만 헤더 없이 Authorization 요청이 도착하는 경우 요청은 시스템 역할에 anonymous할당됩니다.

공급자에 대한 custom 디코딩된 JWT 페이로드는 다음과 같습니다.

{
  "aud": "my-api-audience", // Must match configuration
  "iss": "https://my-custom-issuer.com/", // Must match configuration
  "sub": "user-id",
  "roles": [
    "editor",
    "viewer"
  ],
  // ... other claims
}

X-MS-API-ROLE 헤더 정보

  • 역할 및 동작: 헤더는 X-MS-API-ROLE 공급자와 EntraId 똑같이 작동합니다. 사용자가 할당된 역할 중 하나를 선택할 수 있습니다. 이 헤더의 값은 사용자 지정 JWT 토큰의 roles 클레임에 있는 역할 중 하나와 일치해야 합니다.
  • 필요한가요?: 아니요. 헤더가 X-MS-API-ROLE 없는 경우 사용자는 시스템 역할에 있는 authenticated 것으로 처리됩니다.
  • 일치 시 동작: 헤더의 값이 JWT 클레임의 X-MS-API-ROLE 역할과 일치하는 경우 roles 사용자의 컨텍스트는 권한 부여를 위해 해당 역할로 설정됩니다.
  • 불일치의 동작: X-MS-API-ROLE 헤더의 값이 클레임의 역할 roles 과 일치하지 않으면 요청이 상태 코드로 403 Forbidden 거부됩니다. 이렇게 하면 사용자가 할당되지 않은 역할을 클레임할 수 없습니다.

시뮬레이터(인증 공급자)

이 공급자는 개발자가 Entra Identity 또는 EasyAuth와 같은 전체 인증 공급자를 설정하지 않고도 구성, 특히 authorization 정책을 쉽게 테스트할 수 있도록 설계되었습니다. 사용자를 시뮬레이션합니다 authenticated .

공급자는 Simulator JWT 토큰을 사용하지 않습니다. 인증이 시뮬레이션됩니다. 이 공급자를 사용하는 경우 모든 요청은 인증된 사용자로부터 오는 것처럼 처리됩니다.

X-MS-API-ROLE 헤더 정보

  • 역할 및 동작: X-MS-API-ROLE 헤더는 을 사용할 때 역할을 지정하는 Simulator유일한 방법입니다. 역할 목록이 있는 토큰이 없으므로 시스템은 이 헤더에 전송된 역할을 암시적으로 신뢰합니다.
  • 필요한가요?: 아니요.
  • 부재 중 동작: 헤더가 X-MS-API-ROLE 없는 경우 요청은 시스템 역할의 authenticated 컨텍스트에서 처리됩니다.
  • 현재 상태의 X-MS-API-ROLE 동작: 헤더가 있는 경우 헤더 값에 지정된 역할의 컨텍스트에서 요청이 처리됩니다. 클레임 목록에 대한 유효성 검사가 없으므로 개발자는 정책을 테스트하는 데 필요한 모든 역할을 시뮬레이션할 수 있습니다.

프로덕션의 시뮬레이터

설정된 authentication.providerSimulatorruntime.host.modeproduction경우 데이터 API 작성기는 시작되지 않습니다.

"host": {
  "mode": "production", // or "development"
  "authentication": {
    "provider": "Simulator" 
  }
}

JWT(인증 호스트 런타임)

Parent Property Type Required Default
runtime.host.authentication jwt object ❌ 아니요 -

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

데이터 API 작성기에서 JSON 웹 토큰 지원 다이어그램

중첩 속성

Parent Property Type Required Default
runtime.host.authentication.jwt audience string ❌ 아니요 None
runtime.host.authentication.jwt issuer string ❌ 아니요 None

Format

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

페이지 매김(런타임)

Parent Property Type Required Default
runtime pagination object ❌ 아니요 -

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

중첩 속성

Parent Property Type Required Default
runtime.pagination max-page-size int ❌ 아니요 100,000
runtime.pagination default-page-size int ❌ 아니요 100
runtime.pagination next-link-relative boolean ❌ 아니요 false

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

Value Result
integer 모든 양의 32비트 정수가 지원됩니다.
0 지원되지 않습니다.
-1 기본값은 지원되는 최대값입니다.
< -1 지원되지 않습니다.

기본 페이지 크기 지원 값

Value Result
integer 현재 max-page-size보다 작은 모든 양의 정수입니다.
0 지원되지 않습니다.
-1 기본값은 현재 max-page-size 설정입니다.
< -1 지원되지 않습니다.

페이지 next-link-relative 매김 nextLink 값은 true절대 URL 대신 상대 URL을 사용합니다.

Value Example
false(기본값) "nextLink": "https://localhost:5001/api/users?$after=..."
true "nextLink": "/api/users?$after=..."

Format

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

Note

값이 보다 max-page-size크면 결과는 .로 max-page-size제한됩니다.

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

캐시(런타임)

Parent Property Type Required Default
runtime cache object ❌ 아니요 -

전역 캐시 구성.

중첩 속성

Parent Property Type Required Default
runtime.cache enabled boolean ❌ 아니요 False
runtime.cache ttl-seconds integer ❌ 아니요 5

Tip

엔터티 수준 cache.ttl-seconds 속성은 기본적으로 이 전역 값으로 설정됩니다.

Format

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

Important

전역 enabled 인 false경우 개별 엔터티 수준은 enabled 중요하지 않습니다.

원격 분석(런타임)

Parent Property Type Required Default
runtime telemetry object ❌ 아니요 -

전역 원격 분석 구성.

중첩 속성

Parent Property Type Required Default
runtime.telemetry log-level dictionary ❌ 아니요 None
runtime.telemetry application-insights object ❌ 아니요 -
runtime.telemetry open-telemetry object ❌ 아니요 -

네임스페이스당 로깅 세부 정보를 구성합니다. 이는 표준 .NET 로깅 규칙을 따르고 세분화된 제어를 허용하지만 데이터 API 작성기 내부를 잘 알고 있다고 가정합니다. 데이터 API 작성기는 오픈 소스입니다. https://aka.ms/dab

Format

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

Tip

log-level 는 개발 및 프로덕션 모두에서 핫 다시 로드될 수 있습니다. 현재 프로덕션에서 핫 다시 로드를 지원하는 유일한 속성입니다.

Example

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

Application Insights(원격 분석)

Parent Property Type Required Default
runtime.telemetry application-insights object ❌ 아니요 -

Application Insights에 대한 로깅을 구성합니다.

중첩 속성

Parent Property Type Required Default
runtime.telemetry.application-insights enabled boolean ❌ 아니요 False
runtime.telemetry.application-insights connection-string string ✔️ 예 None

Format

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

OpenTelemetry(원격 분석)

Parent Property Type Required Default
runtime.telemetry open-telemetry object ❌ 아니요 -

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

중첩 속성

Parent Property Type Required Default
runtime.telemetry.open-telemetry enabled boolean ❌ 아니요 true
runtime.telemetry.open-telemetry endpoint string ✔️ 예 None
runtime.telemetry.open-telemetry headers string ❌ 아니요 None
runtime.telemetry.open-telemetry service-name string ❌ 아니요 "dab"
runtime.telemetry.open-telemetry exporter-protocol enum(grpc | httpprotobuf) ❌ 아니요 grpc

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

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 대해 자세히 알아보세요.

Note

gRPC(4317)는 더 빠르고 스트리밍을 지원하지만 더 많은 설정이 필요합니다. HTTP/protobuf(4318)는 더 간단하고 디버그하기 쉽지만 효율성은 떨어집니다.

상태(런타임)

Parent Property Type Required Default
runtime health object ❌ 아니요 -

전역 상태 검사 엔드포인트 (/health) 구성입니다.

중첩 속성

Parent Property Type Required Default 범위/메모
runtime.health enabled boolean ❌ 아니요 true
runtime.health roles 문자열 배열 ✔️ 예* null *프로덕션 모드에서 필요
runtime.health cache-ttl-seconds integer ❌ 아니요 5 최소: 0
runtime.health max-query-parallelism integer ❌ 아니요 4 최소: 1, 최대: 8(고정)

개발 및 프로덕션의 동작

Condition 개발 동작 프로덕션 동작
health.enabled = 거짓 403 상태 403 상태
health.enabled = 참입니다 역할에 따라 다름 역할에 따라 다름
roles 생략 또는 null 상태 표시됨 403 상태
현재 역할이 없음 roles 403 상태 403 상태
의 현재 역할 roles 상태 표시됨 상태 표시됨
roles 포함 anonymous 상태 표시됨 상태 표시됨

Format

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

Note

전역 enabled 인 false경우 개별 엔터티 수준은 enabled 중요하지 않습니다.

Example

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