데이터 API 작성기 구성 스키마 참조

아티클
10/04/2024

데이터 API 작성기 엔진에는 구성 파일이 필요합니다. Data API Builder 구성 파일은 환경 변수에서 엔터티별 구성에 이르기까지 모든 것을 자세히 설명하는 API를 설정하는 구조적이고 포괄적인 접근 방식을 제공합니다. 이 JSON 형식 문서는 $schema 속성으로 시작합니다. 이 설정은 문서의 유효성을 검사합니다.

속성을 database-typeconnection-string Azure SQL Database에서 Cosmos DB NoSQL API에 이르기까지 데이터베이스 시스템과 원활하게 통합됩니다.

구성 파일에는 다음과 같은 옵션이 포함될 수 있습니다.

데이터베이스 서비스 및 연결 정보
전역 및 런타임 구성 옵션
노출된 엔터티 집합
인증 방법
ID에 액세스하는 데 필요한 보안 규칙
API와 데이터베이스 간의 이름 매핑 규칙
유추할 수 없는 엔터티 간의 관계
특정 데이터베이스 서비스에 대한 고유한 기능

구문 개요

다음은 구성 파일의 기본 "섹션"에 대한 빠른 분석입니다.

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

최상위 속성

다음은 테이블 형식의 최상위 속성에 대한 설명입니다.

재산	묘사
$schema	유효성 검사를 위한 JSON 스키마를 지정하여 구성이 필요한 형식을 준수하도록 합니다.
데이터 원본	데이터베이스 연결을 설정하는 데 필요한 데이터베이스 형식 및 연결 문자열대한 세부 정보를 포함합니다.
데이터 원본 파일	다른 데이터 원본을 정의할 수 있는 다른 구성 파일을 지정하는 선택적 배열입니다.
런타임	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 파일과 유사하게 여러 환경을 지원해야 하는 시나리오를 지원할 수 있습니다. 프레임워크는세 가지 공통 환경 값을 제공합니다. , 및 ; 그러나 선택한 환경 값을 사용하도록 선택할 수 있습니다. 데이터 API 작성기에서 사용하는 환경은 DAB_ENVIRONMENT 환경 변수를 사용하여 구성해야 합니다.

기준 구성 및 개발 관련 구성을 원하는 예제를 생각해 보세요. 이 예제에는 다음 두 개의 구성 파일이 필요합니다.

	환경
dab-config.json	기지
dab-config.Development.json	발달

개발별 구성을 사용하려면 DAB_ENVIRONMENT 환경 변수를 Development설정해야 합니다.

환경별 구성 파일은 기본 구성 파일의 속성 값을 재정의합니다. 이 예제에서 connection-string 값이 두 파일에 모두 설정된 경우 *.Development.json 파일의 값이 사용됩니다.

두 파일에서 해당 값이 지정되거나 지정되지 않은 위치에 따라 어떤 값이 사용되는지 더 잘 이해하려면 이 행렬을 참조하세요.

	기본 구성 지정됨	기본 구성 지정되지 않음
현재 환경 구성 지정됨	현재 환경	현재 환경
현재 환경 구성 지정되지 않음	기지	없음

여러 구성 파일을 사용하는 예제는환경에서 데이터 API 작성기 사용 참조하세요.

구성 속성

이 섹션에는 구성 파일에 사용할 수 있는 모든 가능한 구성 속성이 포함되어 있습니다.

스키마

부모	재산	형	필수	기본값
`$root`	`$schema`	문자열	✔️ 예	없음

각 구성 파일은 유효성 검사를 위해 $schema 지정하는 속성으로 시작합니다.

판

{
  "$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`	도구의 알파 버전에서 구성 스키마를 사용합니다.
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 이전의 Data 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 Database	없음
`mssql`	Azure SQL MI	없음
`mssql`	SQL Server	SQL 2016
`sqldw`	Azure SQL Data Warehouse	없음
`postgresql`	PostgreSQL	v11
`mysql`	MySQL	v8
`cosmosdb_nosql`	NoSQL용 Azure Cosmos DB	없음
`cosmosdb_postgresql`	PostgreSQL용 Azure Cosmos DB	없음

연결 문자열

부모	재산	형	필수	기본값
`data-source`	`connection-string`	문자열	✔️ 예	없음

대상 데이터베이스 서비스에 연결할 유효한 연결 문자열을 포함하는 문자열 값입니다. 백 엔드 데이터베이스에 연결할 ADO.NET 연결 문자열입니다. 자세한 내용은ADO.NET 연결 문자열을 참조하세요.

판

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

연결 복원력

데이터 API 작성기에서는 일시적인 오류를 감지한 후 데이터베이스 요청을 자동으로 다시 시도합니다. 재시도 논리는 최대 재시도 횟수가 5개지수 백오프 전략을 따릅니다. 이 수식을 사용하여 후속 요청을 계산한 후의 재시도 백오프 기간(현재 재시도 시도가 r가정): $r^2$

이 수식을 사용하여 각 재시도 시간을 초 단위로 계산할 수 있습니다.

	초
첫 번째	`2`
두 번째	`4`
세 번째	`8`
네 번째	`16`
다섯 번째	`32`

Azure SQL 및 SQL Server

데이터 API 작성기에서는 SqlClient 라이브러리를 사용하여 구성 파일에 제공하는 연결 문자열을 사용하여 Azure SQL 또는 SQL Server에 연결합니다. 지원되는 모든 연결 문자열 옵션 목록은 SqlConnection.ConnectionString 속성.

데이터 API 작성기는 Azure에서 데이터 API 작성기를 호스팅할 때 MSI(관리 서비스 ID)를 사용하여 대상 데이터베이스에 연결할 수도 있습니다. DefaultAzureCredential 라이브러리에 정의된 Azure.Identity 연결 문자열에 사용자 이름 또는 암호를 지정하지 않을 때 알려진 ID를 사용하여 연결하는 데 사용됩니다. 자세한 내용은 예제를 참조하세요.

UMI(사용자 할당 관리 ID): 사용자 할당 관리 ID의 클라이언트 ID인 대체하면서 인증 및 Authentication=Active Directory Managed Identity; User Id=<UMI_CLIENT_ID>; 속성을 연결 문자열에 추가합니다.
시스템 할당 관리 ID(SMI): 인증 속성을 추가하고 연결 문자열에서 UserId 및 암호 인수를 제외합니다. Authentication=Active Directory Managed Identity;. UserId 및 암호 연결 문자열 속성이 없으면 DAB가 시스템 할당 관리 ID를 사용하여 인증하도록 알릴 수 있습니다.

Azure SQL 또는 SQL Server를 사용하여 관리 서비스 ID를 구성하는 방법에 대한 자세한 내용은 Microsoft Entra for Azure SQL관리 ID를 참조하세요.

예제

연결 문자열에 사용되는 값은 주로 시나리오에 사용되는 데이터베이스 서비스에 따라 달라집니다. 항상 환경 변수에 연결 문자열을 저장하고 @env() 함수를 사용하여 액세스하도록 선택할 수 있습니다.

	값	묘사
Azure SQL Database 문자열 값 사용	`Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;`	Azure SQL Database 계정에 대한 연결 문자열입니다. 자세한 내용은 azure SQL Database 연결 문자열참조하세요.
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 연결 문자열 참조하세요.
NoSQL 문자열 값 Azure Cosmos DB 사용	`AccountEndpoint=<endpoint>;AccountKey=<key>;`	NoSQL용 Azure Cosmos DB 계정에 대한 연결 문자열입니다. 자세한 내용은NoSQL 연결 문자열에 대한 Azure Cosmos DB 참조하세요.
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 같은 "옵션"은 PostgreSQL API가 아닌 Azure Cosmos DB의 NoSQL 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 활용하여 사용자 지정 메타데이터를 기본 데이터베이스로 보낼 수 있습니다. 이러한 메타데이터는 액세스 토큰에 있는 클레임을 통해 Data 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`	부울	❌ 아니요	False

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`	❌ 아니요	문자열	/api
`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 설정하면 /api/<entity>REST 엔드포인트에 액세스할 수 있습니다. 하위 경로는 허용되지 않습니다. 이 필드는 선택 사항이며 /api 기본값으로 사용됩니다.

메모

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

판

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

중요하다

사용자가 제공한 하위 경로는 이 속성에 대해 허용되지 않습니다.

예제

이 예제에서는 루트 REST API URI가 /data.

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

팁

Author 엔터티를 정의하는 경우 이 엔터티의 엔드포인트는 /data/Author.

요청 본문 Strict(REST 런타임)

부모	재산	형	필수	기본값
`runtime.rest`	`request-body-strict`	부울	❌ 아니요	참

이 설정은 REST 변형 작업에 대한 요청 본문(예: POST, PUT, PATCH)의 유효성을 검사하는 방법을 제어합니다.

true(기본값): 요청 본문에 테이블 열에 매핑되지 않는 추가 필드로 인해 BadRequest 예외가 발생합니다.
false: 추가 필드가 무시되고 유효한 열만 처리됩니다.

이 설정은 요청 본문이 항상 무시되므로 요청에 적용되지 .

특정 열 구성을 사용하는 동작

기본값() 값이 있는 열은 페이로드의 값이 null경우에만 INSERT 동안 무시됩니다. 기본값()이 있는 열은 페이로드 값에 관계없이 UPDATE 동안 무시되지 않습니다.
계산 열은 항상 무시됩니다.
자동 생성된 열은 항상 무시됩니다.

판

{
  "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 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 섹션에서는 Data 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`	문자열	❌ 아니요	"production"

데이터 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)은 각각 최대 2GB까지 보유할 수 있으므로 개별 행이 매우 커질 수 있습니다. 이 설정을 통해 개발자는 다양한 데이터 형식에 대한 유연성을 유지하면서 응답 크기를 제한하고 시스템 오버로드를 방지하여 엔드포인트를 보호할 수 있습니다.

허용되는 값

값	결과
`null`	설정되지 않거나 명시적으로 `null`설정하면 기본값은 158메가바이트입니다.
`integer`	모든 양의 32비트 정수가 지원됩니다.
`< 0`	지원되지 않습니다. 1MB 미만으로 설정하면 유효성 검사 오류가 발생합니다.

판

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

CORS(호스트 런타임)

부모	재산	형	필수	기본값
`runtime.host`	`cors`	객체	❌ 아니요	없음

Data API Builder 엔진 호스트에 대한 CORS(원본 간 리소스 공유) 설정입니다.

판

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

속성

	필수	형
`allow-credentials`	❌ 아니요	부울
`origins`	❌ 아니요	문자열 배열

자격 증명 허용(호스트 런타임)

부모	재산	형	필수	기본값
`runtime.host.cors`	`allow-credentials`	부울	❌ 아니요	False

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 작성기는 신뢰할 수 있는 ID 공급자(예: Entra ID)에서 제공하는 유효한 JWT 토큰을 기반으로 직접 호출자(예: 웹 애플리케이션)를 인증하지 않고 최종 사용자를 인증한다는 것을 이해하는 것이 중요합니다. 요청이 Data API Builder에 도달하면 JWT 토큰이 유효하다고 가정하고 특정 클레임과 같이 구성한 필수 구성 요소에 대해 확인합니다. 권한 부여 규칙은 사용자가 액세스하거나 수정할 수 있는 항목을 결정하기 위해 적용됩니다.

권한 부여가 통과되면 데이터 API 작성기에서 연결 문자열에 지정된 계정을 사용하여 요청을 실행합니다. 이 계정에는 다양한 사용자 요청을 처리하기 위해 상승된 권한이 필요한 경우가 많으므로 위험을 줄이기 위해 액세스 권한을 최소화해야 합니다. 프런트 엔드 웹 애플리케이션과 API 엔드포인트 간에 Private Link를 구성하고 데이터 API 작성기를 호스트하는 컴퓨터를 강화하여 아키텍처를 보호하는 것이 좋습니다. 이러한 조치는 환경을 안전하게 유지하고, 데이터를 보호하고, 중요한 정보에 액세스, 수정 또는 유출하기 위해 악용될 수 있는 취약성을 최소화하는 데 도움이 됩니다.

공급자(호스트 런타임)

부모	재산	형	필수	기본값
`runtime.host.authentication`	`provider`	문자열	❌ 아니요	"StaticWebApps"

authentication.provider 구성 내의 host 설정은 Data API 작성기에서 사용하는 인증 방법을 정의합니다. API가 리소스에 액세스하려는 사용자 또는 서비스의 ID를 확인하는 방법을 결정합니다. 이 설정을 사용하면 다양한 환경 및 보안 요구 사항에 맞게 조정된 다양한 인증 메커니즘을 지원하여 배포 및 통합을 유연하게 수행할 수 있습니다.

공급자	묘사
`StaticWebApps`	Data API 작성기에서 Static Web Apps 환경 내에서 실행되는 경우에만 존재하는 HTTP 헤더 집합을 찾도록 지시합니다.
`AppService`	런타임이 AppService 인증을 사용하도록 설정하고 구성한 Azure AppService에서 호스트되는 경우(EasyAuth)
`AzureAd`	데이터 API 작성기("서버 앱")로 전송된 요청을 인증할 수 있도록 Microsoft Entra Identity를 구성해야 합니다. 자세한 내용은 Microsoft Entra ID 인증참조하세요.
`Simulator`	모든 요청을 인증된 것으로 처리하도록 Data API 작성기 엔진에 지시하는 구성 가능한 인증 공급자입니다. 자세한 내용은 로컬 인증참조하세요.

판

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

값

다음은 이 속성에 허용되는 값 목록입니다.

	묘사
`StaticWebApps`	Azure Static Web Apps
`AppService`	Azure App Service
`AzureAD`	Microsoft Entra ID
`Simulator`	시뮬레이터

JSON 웹 토큰(호스트 런타임)

부모	재산	형	필수	기본값
`runtime.host.authentication`	`jwt`	객체	❌ 아니요	없음

인증 공급자가 AzureAD(Microsoft Entra ID)로 설정된 경우 JSOn JWT(웹 토큰) 토큰의 대상 그룹 및 발급자를 지정하려면 이 섹션이 필요합니다. 이 데이터는 Microsoft Entra 테넌트에 대한 토큰의 유효성을 검사하는 데 사용됩니다.

인증 공급자가 Microsoft Entra ID에 대해 AzureAD 경우 필요합니다. 이 섹션에서는 audience 지정하고 issuer 인증을 위해 의도한 AzureAD 테넌트에 대해 수신된 JWT 토큰의 유효성을 검사해야 합니다.

설정	묘사
관객	토큰의 의도된 받는 사람을 식별합니다. 일반적으로 Microsoft Entra Identity(또는 ID 공급자)에 등록된 애플리케이션의 식별자를 사용하여 토큰이 실제로 애플리케이션에 대해 발급되었는지 확인합니다.
발급자	JWT를 발급한 토큰 서비스인 발급 기관의 URL을 지정합니다. 이 URL은 JWT를 가져온 ID 공급자의 발급자 URL과 일치하여 토큰의 원본에 대한 유효성을 검사해야 합니다.

판

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

속성

재산	필수	형	기본값
`audience`	❌ 아니요	문자열	없음
`issuer`	❌ 아니요	문자열	없음

예제

DAB(Data API Builder)는 Microsoft Entra Identity 및 사용자 지정 JWT(JSON Web Token) 서버와 통합하여 유연한 인증 지원을 제공합니다. 이 이미지에서 JWT Server 성공적으로 로그인할 때 클라이언트에 JWT 토큰을 발급하는 인증 서비스를 나타냅니다. 그런 다음 클라이언트는 DAB에 토큰을 전달하여 해당 클레임 및 속성을 심문할 수 있습니다.

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

다음은 솔루션에서 선택할 수 있는 다양한 아키텍처가 지정된 host 속성의 예입니다.

Azure Static Web Apps

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

StaticWebAppsData API 작성기는 Azure Static Web Apps가 요청을 인증하고 X-MS-CLIENT-PRINCIPAL HTTP 헤더가 존재할 것으로 예상합니다.

Azure App Service

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

인증은 액세스 토큰을 발급할 수 있는 지원되는 ID 공급자에게 위임됩니다. 획득한 액세스 토큰은 데이터 API 작성기에서 들어오는 요청에 포함되어야 합니다. 그런 다음 데이터 API 작성기에서 제공된 액세스 토큰의 유효성을 검사하여 Data API Builder가 토큰의 의도된 대상 그룹임을 확인합니다.

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 실행하면 default-page-size 2로 설정되므로 value 배열에 두 개의 레코드가 반환됩니다. 더 많은 결과가 있는 경우 Data API Builder는 응답에 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

모든 엔터티에 대해 전역적으로 캐싱을 사용하도록 설정합니다. 기본값은 false입니다.

판

{
  "runtime": {
    "cache":  {
      "enabled": <boolean>
    }
  }
}

예제

이 예제에서는 캐시를 사용할 수 없습니다.

{
  "runtime": {
    "cache": {
      "enabled": false
    }
  }
}

TTL(초)(캐시 런타임)

부모	재산	형	필수	기본값
`runtime.cache`	`ttl-seconds`	정수	❌ 아니요	5

캐시된 항목에 대한 TTL(Time to Live) 값을 초 단위로 구성합니다. 이 시간이 경과하면 캐시에서 항목이 자동으로 정리됩니다. 기본값은 5 초입니다.

판

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

예제

이 예제에서는 캐시를 전역적으로 사용하도록 설정하고 모든 항목은 15초 후에 만료됩니다.

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

원격 분석(런타임)

부모	재산	형	필수	기본값
`runtime`	`telemetry`	객체	❌ 아니요	없음

이 속성은 API 로그를 중앙 집중화하도록 Application Insights를 구성합니다. 자세한알아봅니다.

판

{
  "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. 저장 프로시저 예제:

이 예제에서는 원본 프로시전 dbo.GetUsersUser 엔터티를 연결하는 방법을 보여줍니다.

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 속성은 뷰에서 지원되는 엔터티에 특히 필요하므로 Data API Builder는 단일 항목을 식별하고 반환하는 방법을 알고 있습니다. type key-fields지정하지 않고 view 설정되면 엔진이 시작을 거부합니다. 이 속성은 테이블 및 저장 프로시저와 함께 사용할 수 있지만 이러한 경우에는 사용되지 않습니다.

중요하다

개체의 형식이 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 속성은 저장 프로시저에서 지원되는 엔터티에 사용됩니다. 저장 프로시저에 필요한 매개 변수 이름 및 데이터 형식의 적절한 매핑을 보장합니다.

중요하다

개체의 매개 변수가 필요한 경우 속성은 필요합니다.

판

{
  "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)를 제외한 모든 필드를 읽을 수 있습니다. "exclude": ["secret-field"] "include": ["*"] 사용하면 다른 모든 필드에 대한 액세스를 허용하면서 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`(문자열 배열) 또는 `actions`(개체 배열)	✔️ 예	개체 또는 문자열 배열

역할

부모	재산	형	필수	기본값
`entities.permissions`	`role`	문자열	✔️ 예	없음

정의된 사용 권한이 적용되는 역할의 이름을 포함하는 문자열입니다. 역할은 요청을 실행해야 하는 권한 컨텍스트를 설정합니다. 런타임 구성에 정의된 각 엔터티에 대해 REST 및 GraphQL 엔드포인트를 통해 엔터티에 액세스할 수 있는 방법을 결정하는 역할 및 관련 권한 집합을 정의할 수 있습니다. 역할은 가산적이지 않습니다.

Data API Builder는 단일 역할의 컨텍스트에서 요청을 평가합니다.

역할	묘사
`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>
          }
        }
      ]
    }
  }
}

예제

이 예제에서는 User 엔터티에 대한 read 권한만 있는 reader 명명된 역할을 정의합니다.

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

유효한 액세스 토큰이 표시되고 X-MS-API-ROLE HTTP 헤더가 포함된<custom-role> 사용하여 액세스 토큰의 역할 클레임에도 포함된 사용자 역할을 지정할 수 있습니다. 다음은 다른 언어를 사용하는 localhost REST 엔드포인트 기본 /api 권한 부여 전달자 토큰과 X-MS-API-ROLE 헤더를 포함하여 User 엔터티에 대한 GET 요청의 예입니다.

http
C#
javaScript/TypeScript
Python

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())

작업(문자열 배열)

부모	재산	형	필수	기본값
`entities.permissions`	`actions`	oneOf [string, array]	✔️ 예	없음

연결된 역할에 허용되는 작업을 자세히 설명하는 문자열 값의 배열입니다. table 및 view 데이터베이스 개체의 경우 역할은 create, read, update또는 delete 작업의 조합을 사용할 수 있습니다. 저장 프로시저의 경우 역할은 execute 작업만 가질 수 있습니다.

행동	SQL 작업
`*`	와일드카드(실행 포함)
`create`	하나 이상의 행 삽입
`read`	하나 이상의 행 선택
`update`	하나 이상의 행 수정
`delete`	하나 이상의 행 삭제
`execute`	저장 프로시저 실행

메모

저장 프로시저의 경우 와일드카드(*) 작업은 execute 작업으로만 확장됩니다. 테이블 및 뷰의 경우 create, read, update및 delete확장됩니다.

예제

이 예제에서는 User 엔터티에 auditor 역할에 대한 contributor 역할 및 delete 권한에 대한 create 및 read 권한을 제공합니다.

{
  "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 사용자가 저장 프로시저를 executeUser 테이블에서 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 정책: eq, lt및 gt같은 연산자를 포함하여 데이터베이스가 평가하는 쿼리 조건자로 변환되는 OData와 유사한 식입니다. 요청에 대해 결과를 반환하려면 데이터베이스 정책에서 확인된 요청의 쿼리 조건자가 데이터베이스에 대해 실행할 때 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 Static Web Apps 인증(EasyAuth)을 구성하면 데이터베이스 정책(identityProvider, userId, userDetails및 userRoles)에서 제한된 수의 클레임 유형을 사용할 수 있습니다. 자세한 내용은 Azure Static Web App의 클라이언트 주체 데이터 설명서를 참조하세요.

다음은 몇 가지 데이터베이스 정책 예제입니다.

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

자세한 내용은 이진 연산자참조하세요.

연산자	묘사	샘플 구문
`-`	Negate(숫자)	`"@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 엔드포인트 내에서 데이터 모델의 명확성과 접근성을 향상시킵니다.

예제

클레임 및 항목 지시문을 모두 활용하는 Data 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"
      }
    }
  }
}

엔터티 정의: Employee 엔터티는 REST 및 GraphQL 인터페이스에 대해 구성되며, 이러한 엔드포인트를 통해 데이터를 쿼리하거나 조작할 수 있음을 나타냅니다.

원본 구성: 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 일치하는 사용자(필드 별칭)로 데이터 액세스를 제한합니다. 직원이 HR 부서에 속하지 않는 한 자신의 레코드에만 액세스할 수 있습니다. 정책은 동적 조건에 따라 행 수준 보안을 적용할 수 있습니다.

데이터베이스

부모	재산	형	필수	기본값
`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 Static Web Apps 인증(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 스키마에서 엔터티를 나타내고 상호 작용하는 방법에 대한 명확한 구조를 제공합니다.

사용 속성: Book 엔터티는 GraphQL("enabled": true)을 통해 사용할 수 있습니다. 즉, 개발자와 사용자가 GraphQL 작업을 통해 책 데이터를 쿼리하거나 변경할 수 있습니다.

Type 속성: 엔터티는 GraphQL 스키마에서 단수 이름 "Book" 및 복수 이름 "Books" 나타냅니다. 이렇게 구분하면 단일 책이나 여러 권의 책을 쿼리할 때 스키마가 직관적으로 명명된 형식(목록에 대한 BookBooks)을 제공하여 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`	기본 저장 프로시저는 돌연변이로 노출됩니다.

예제

operation mutation경우 GraphQL 스키마는 다음과 유사합니다.

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

operation query경우 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_title 데이터베이스 개체의 dbo.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 설명서 또는 클라이언트 쪽 코드에 대한 업데이트가 필요하지 않습니다.
필드 이름 난독 처리: 매핑을 사용하면 필드 이름을 난독 처리할 수 있으므로 권한이 없는 사용자가 데이터베이스 스키마 또는 저장된 데이터의 특성에 대한 중요한 정보를 유추하지 못하도록 방지할 수 있습니다.
소유 정보 보호: 필드 이름을 바꾸면 데이터베이스의 원래 필드 이름을 통해 암시될 수 있는 소유 이름 또는 비즈니스 논리를 보호할 수도 있습니다.

관계(엔터티)

부모	재산	형	필수	기본값
`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]!
}

다대일

다음으로 카디널리티를 설정하는 다대일 것이 좋습니다. 노출된 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`	원본은 대상의 0대 다 레코드와 관련할 수 있습니다.

대상 엔터티

부모	재산	형	필수	기본값
`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`	부울	❌ 아니요	False

엔터티에 대한 캐싱을 사용하도록 설정하고 구성합니다.

판

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`	❌ 아니요	부울	False
`ttl-seconds`	❌ 아니요	정수	5

예제

이 예제에서는 캐시가 활성화되고 항목이 30초 후에 만료됩니다.

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

사용(캐시 엔터티)

부모	재산	형	필수	기본값
`entities.{entity}.cache`	`enabled`	부울	❌ 아니요	False

엔터티에 대한 캐싱을 사용하도록 설정합니다.

데이터베이스 개체 지원

개체 유형	캐시 지원
테이블	✅ 예
보기	✅ 예
저장 프로시저	✖️ 아니요
컨테이너	✖️ 아니요

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(Time to Live) 값을 초 단위로 구성합니다. 이 시간이 경과하면 캐시에서 항목이 자동으로 정리됩니다. 기본값은 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 런타임)

판

예제

요청 본문 Strict(REST 런타임)

특정 열 구성을 사용하는 동작

판

예제

예제 구성

request-body-strict: false 있는 INSERT 동작

request-body-strict: false 사용하여 업데이트 동작

호스트(런타임)

판

속성

예제

모드(호스트 런타임)

판

`request-body-strict: false` 있는 INSERT 동작

`request-body-strict: false` 사용하여 업데이트 동작