Runtime

決定運行時間行為的組態設定。

分頁設定

REST 設定

GraphQL 設定

主機設定

CORS 設定

驗證設定

快取設定

遙測設置

格式概觀

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer|null> (default: `100000`),
      "default-page-size": <integer|null> (default: `100`)
    },
    "rest": {
      "path": <string> (default: "/api"),
      "enabled": <true>|<false>,
      "request-body-strict": <true>|<false> (default: `true`)
    },
    "graphql": {
      "path": <string> (default: "/graphql"),
      "enabled": <true>|<false>,
      "allow-introspection": <true>|<false>,
      "depth-limit": <integer|null> (default: `null`),
      "multiple-mutations": {
        "create": {
          "enabled": <true>|<false> (default: `false`)
        }
      }
    },
    "host": {
      "mode": <"production"> (default) | <"development">,
      "max-response-size-mb": <integer|null> (default: `158`),
      "cors": {
        "origins": [ "<string>" ],
        "allow-credentials": <true>|<false> (default: `false`)
      },
      "authentication": {
        "provider": <string> (default: "AppService"),
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  },
  "cache": {
    "enabled": <true>|<false> (default: `false`),
    "ttl-seconds": <integer> (default: `5`)
  },
  "telemetry": {
    "application-insights": {
      "connection-string": "<string>",
      "enabled": <true>|<false> (default: `true`)
    },
    "open-telemetry": {
      "endpoint": "<string>",
      "headers": "<string>",
      "service-name": <string> (default: "dab"),
      "exporter-protocol": <"grpc"> (default) | <"httpprotobuf">,
      "enabled": <true>|<false> (default: `true`)
    },
    "log-level": {
      // namespace keys
      "<namespace>": <"trace"|"debug"|"information"|"warning"|"error"|"critical"|"none"|null>
    }
  },
  "health": {
    "enabled": <true>|<false> (default: `true`),
    "roles": [ "<string>" ],
    "cache-ttl-seconds": <integer> (default: `5`),
    "max-query-parallelism": <integer> (default: `4`)
  }
}

模式 （主機執行時間）

開發行為

• Enabled Nitro （先前稱為香蕉蛋糕流行） 用於 GraphQL 測試
• 已啟用用於 REST 測試的 Swagger UI
• 已啟用匿名健康情況檢查
• 增加記錄詳細資訊 （偵錯）

Format

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

回應大小上限 （主機執行時間）

設定任何指定結果的大小上限（以 MB 為單位）。 由於大型回應可能會使系統緊張， max-response-size-mb 因此會限制總大小（與數據列計數不同），以防止多載，尤其是文字或 JSON 等大型數據行。

Format

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

GraphQL （執行時間）

全域 GraphQL 組態。

巢狀屬性

屬性附註

• 該物業不允許 path 使用分道。
• 使用 depth-limit 來限制巢狀查詢。
• 設定 allow-introspection 為 false 以隱藏 GraphQL 架構。
• 用來 multiple-mutations 在單一突變中插入多個實體。

Format

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

範例：多個突變

Configuration

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

GraphQL 突變

mutation {
  createUsers(input: [
    { name: "Alice", age: 30, isAdmin: true },
    { name: "Bob", age: 25, isAdmin: false },
    { name: "Charlie", age: 35, isAdmin: true }
  ]) {
    id
    name
    age
    isAdmin
  }
}

REST （執行階段）

全域 REST 組態。

巢狀屬性

屬性附註

• 如果全域 enabled 為 false，則個別實體層級 enabled 並不重要。
• 屬性 path 不支援子路徑值，例如 /api/data。
• request-body-strict 引進有助於簡化 .NET POCO 物件。

Format

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

範例：request-body-strict

• default()只有在承載INSERT中的數據行值為 時，才會忽略null具有值的數據行。 因此，當是 時，INSERT資料default()列中的作業無法產生明確的request-body-strict值。truenull 為了達成此行為，需要一個 UPDATE 操作。
• 不論承載值為何，都不會忽略default()具有 UPDATE 的數據行。
• 計算數據行一律會被忽略。
• 自動產生的數據行一律會被忽略。

範例數據表

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

請求載荷

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

插入行為時機 request-body-strict = false

INSERT INTO Users (Name) VALUES ('Alice');
-- Default values for Age (18) and IsAdmin (0) are applied by the database.
-- IsMinor is ignored because it’s a computed column.
-- ExtraField is ignored.
-- The database generates the Id value.

回應負載

{
  "Id": 1,          // Auto-generated by the database
  "Name": "Alice",
  "Age": 18,        // Default applied
  "IsAdmin": false, // Default applied
  "IsMinor": true   // Computed
}

更新行為時機 request-body-strict = false

UPDATE Users
SET Name = 'Alice Updated', Age = NULL
WHERE Id = 1;
-- IsMinor and ExtraField are ignored.

回應負載

{
  "Id": 1,
  "Name": "Alice Updated",
  "Age": null,
  "IsAdmin": false,
  "IsMinor": false // Recomputed by the database (false when age is `null`)
}

CORS （主機執行時間）

全域 CORS 設定。

巢狀屬性

Format

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

提供者（驗證主機執行時間）

定義數據 API 產生器所使用的驗證方法。

僅限匿名 （驗證提供者）

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

當從 dab-config.json 檔案中省略整個 authentication 區段時，不會使用任何驗證提供者。 在此情況下，資料 API 產生器會以「無驗證」模式運作。 在此模式下，DAB 不會尋找任何權杖或 Authorization 標頭。 X-MS-API-ROLE在此配置中也會忽略標頭。

實體權限的範例。

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

在此範例中，由於未設定任何 authentication 提供者，因此所有傳入的要求都會自動視為來自 anonymous 使用者。 permissions實體的Book陣列會明確授與anonymous角色執行作業的能力read。 任何嘗試執行其他動作 （例如 create、 updatedelete、 ） 或存取未設定存取的其他anonymous實體的嘗試都會被拒絕。

AppService （驗證提供者）

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

此提供者適用於裝載在 Azure App Service 上的應用程式，例如 Azure 容器應用程式。 Azure 裝載環境會處理驗證，然後透過要求標頭將使用者的身分識別資訊傳遞至應用程式。 它專為想要由 Azure 平台管理、簡單且開箱即用的認證解決方案的開發者設計。

此提供者不會使用標頭中的 Authorization JWT 權杖。 它依賴 App Service 平臺插入的特殊標頭 X-MS-CLIENT-PRINCIPAL。 此標頭包含一個 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 中的使用者和應用程式身分識別來保護端點。 它非常適合使用者或其他服務需要在 Entra 租用戶內安全存取的任何服務。

此提供者預期標頭中有 Authorization 標準 JWT 持有人權杖，由 Microsoft Entra 發出。 必須針對特定應用程式設定權杖 （使用 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"
   }
  }
 }
}

此提供者適用於想要將資料 API 產生器與發行 JWT 的第三方身分識別提供者 （例如 Auth0、Okta 或自訂身分識別伺服器） 整合的開發人員。 它提供了配置預期audienceissuer和權杖的靈活性。

Custom提供者預期標頭中有Authorization標準 JWT 持有人權杖。 與提供者的主要 EntraId 差異在於，您在資料 API 產生器的組態檔中設定有效的 issuer 和 audience 。 提供者會檢查授信機構是否發出權杖，以驗證權杖。 使用者的角色預期位於 JWT 承載內的宣告中 roles 。

匿名：如果已設定提供者，但要求到達時沒有標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要求。 此驗證確保使用者無法聲稱未被指派的角色。

模擬器 （驗證提供者）

此提供者旨在讓開發人員輕鬆測試其設定，尤其是 authorization 政策，而無需設定完整的身份驗證提供者，例如 Entra Identity 或 EasyAuth。 它模擬用戶 authenticated 。

Simulator提供者不使用 JWT 權杖。 模擬身份驗證。 使用這個提供者時，Data API 建構器會將所有請求視為來自已認證的使用者。

關於 X-MS-API-ROLE 接頭

• 角色和行為：X-MS-API-ROLE標頭是使用 .Simulator 由於沒有具有角色清單的權杖，因此系統會隱含信任在此標頭中傳送的角色。
• 是否必需？：沒有。
• 不在場時的行為：如果標頭不存在，則 X-MS-API-ROLE 會在系統角色的內容 authenticated 中處理請求。
• 存在時的行為：如果標頭存在，則 X-MS-API-ROLE 會在標頭值中指定的角色內容中處理請求。 沒有針對宣告清單進行驗證，因此開發人員可以模擬測試其政策所需的任何角色。

生產中的模擬器

如果 authentication.provider 設定為 Simulatorruntime.host.mode 而 是 production，資料 API 建構器將無法啟動。

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

JWT （驗證主機執行時間）

全域 JSON Web 令牌 （JWT） 設定。

巢狀屬性

Format

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

分頁 （執行階段）

REST 和 GraphQL 端點的全域分頁限制。

巢狀屬性

支援的最大頁面大小值

默認頁面大小支援的值

下一連結相對行為

當 next-link-relative 為 true時，分頁 nextLink 值使用相對網址而非絕對網址。

Format

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

範例：REST 中的分頁

Request

GET https://localhost:5001/api/users

回應負載

{
  "value": [
    {
      "Id": 1,
      "Name": "Alice",
      "Age": 30,
      "IsAdmin": true,
      "IsMinor": false
    },
    {
      "Id": 2,
      "Name": "Bob",
      "Age": 17,
      "IsAdmin": false,
      "IsMinor": true
    }
  ],
  "nextLink": "https://localhost:5001/api/users?$after=W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
}

要求下一頁

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

範例：GraphQL 中的分頁

要求承載 （查詢）

query {
  users {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

回應負載

{
  "data": {
    "users": {
      "items": [
        {
          "Id": 1,
          "Name": "Alice",
          "Age": 30,
          "IsAdmin": true,
          "IsMinor": false
        },
        {
          "Id": 2,
          "Name": "Bob",
          "Age": 17,
          "IsAdmin": false,
          "IsMinor": true
        }
      ],
      "hasNextPage": true,
      "endCursor": "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
    }
  }
}

要求下一頁

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

範例：在 max-page-size 要求中存取

將 [REST] 或 max-page-size [GraphQL] 設定$limit為 first，-1以使用 值。

REST

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

GraphQL

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

快取 （執行階段）

全域快取組態。

巢狀屬性

Format

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

遙測 （執行階段）

全域遙測設定。

巢狀屬性

設定每個命名空間的記錄詳細資訊。 這會遵循標準 .NET 記錄慣例並允許細微控制，不過它假設對數據 API 產生器內部有一些熟悉。 資料 API 產生器是開放原始碼： https://aka.ms/dab

Format

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

Example

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

Application Insights （遙測）

設定記錄至 Application Insights。

巢狀屬性

Format

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

OpenTelemetry （遙測）

設定記錄以開啟遙測。

巢狀屬性

多個標頭會 , 以逗號分隔。

Format

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

Example

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

深入瞭解 OTEL_EXPORTER_OTLP_HEADERS。

健康情況 （執行階段）

全域 健康情況檢查端點 （/health） 組態。

巢狀屬性

開發與生產環境的行為

Format

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

Example

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