數據 API 產生器組態架構參考

數據 API 產生器的引擎需要組態檔。 數據 API 產生器組態檔提供結構化且全面的方法來設定 API，詳細說明環境變數到實體特定組態的所有專案。 這個 JSON 格式的檔會以 $schema 屬性開頭。 此設定會驗證檔。

屬性 database-type 和 connection-string 確保與資料庫系統緊密整合，從 Azure SQL Database 到 Cosmos DB NoSQL API。

組態檔可以包含下列選項：

• 資料庫服務和聯機資訊
• 全域和運行時間組態選項
• 一組公開的實體
• 驗證方法
• 存取身分識別所需的安全性規則
• API 與資料庫之間的名稱對應規則
• 無法推斷的實體之間的關聯性
• 特定資料庫服務的獨特功能

語法概觀

以下是組態檔中主要「區段」的快速分解。

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

最上層屬性

以下是資料表格式的最上層屬性描述：

範例組態

以下是只包含單一簡單實體所需屬性的範例組態檔。 此範例旨在說明最少的案例。

{
  "$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 檔案。 架構提供三個 常見的環境值;Development、Staging和 Production;但您可以選擇使用您選擇的任何環境值。 數據 API 產生器所使用的環境必須使用 DAB_ENVIRONMENT 環境變數來設定。

請考慮您想要基準組態和開發特定組態的範例。 此範例需要兩個組態檔：

若要使用開發特定的組態，您必須將 DAB_ENVIRONMENT 環境變數設定為 Development。

環境特定的組態檔會覆寫基底組態檔中的屬性值。 在此範例中，如果在這兩個檔案中設定 connection-string 值，則會使用來自 *.Development.json 檔案的值。

請參閱此矩陣，以根據任一檔案中指定或未指定該值的位置，進一步瞭解所使用的值。

如需使用多個組態檔的範例，請參閱 搭配環境使用資料 API 產生器。

組態屬性

本節包含可供組態檔使用的所有可能組態屬性。

圖式

每個組態檔都會以 $schema 屬性開頭，並指定驗證 JSON 架構。

格式

{
  "$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取得。

以下是一些有效的架構值範例。

數據源

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

性能

資料庫類型

列舉字串，用來指定要作為數據源的資料庫類型。

格式

{
  "data-source": {
    "database-type": <string>
  }
}

類型值

type 屬性表示後端資料庫的種類。

連接字串

字串 值，其中包含連線至目標資料庫服務的有效連接字串。 要連線到後端資料庫的 ADO.NET 連接字串。 如需詳細資訊，請參閱ADO.NET 連接字串。

格式

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

線上恢復功能

偵測暫時性錯誤之後，數據 API 產生器會自動重試資料庫要求。 重試邏輯會遵循 指數輪詢 策略，其中重試次數上限 五個。 使用此公式計算後續要求之後的重試輪詢持續時間（假設目前的重試嘗試 r）：$r^2$

您可以使用此公式，以秒為單位計算每次重試嘗試的時間。

Azure SQL 和 SQL Server

數據 API 產生器會使用 SqlClient 連結庫，使用您在組態檔中提供的連接字串連線到 Azure SQL 或 SQL Server。 這裡提供所有支援的連接字串選項清單：SqlConnection.ConnectionString 屬性。

當數據 API 產生器裝載於 Azure 中時，數據 API 產生器也可以使用受控服務識別 （MSI） 連線到目標資料庫。 當您未在連接字串中指定使用者名稱或密碼時，DefaultAzureCredential 連結庫中定義的 Azure.Identity 會用來使用已知的身分識別進行連線。 如需詳細資訊，請參閱 範例。

• 使用者指派的受控識別 （UMI）：在取代使用者指派的受控識別用戶端標識符時，將 驗證 和 使用者識別碼 屬性附加至連接字元串：Authentication=Active Directory Managed Identity; User Id=<UMI_CLIENT_ID>;。
• 系統指派的受控識別 （SMI）：附加 驗證 屬性，並從連接字串排除 UserId 和 密碼 自變數：Authentication=Active Directory Managed Identity;。 UserId 和 密碼 連接字串屬性的缺席，將會發出 DAB 使用系統指派的受控識別進行驗證的訊號。

如需使用 Azure SQL 或 SQL Server 設定受控服務識別的詳細資訊，請參閱 Microsoft Entra for Azure SQL中的 受控識別。

例子

用於連接字串的值在很大程度上取決於您案例中使用的資料庫服務。 您一律可以選擇將連接字串儲存在環境變數中，並使用 @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;"

選項

特定資料庫連線的額外索引鍵/值參數選擇性區段。

是否需要 options 區段，在很大程度上相依於所使用的資料庫服務。

格式

{
  "data-source": {
    "options": {
      "<key-name>": <string>
    }
  }
}

options： { set-session-context： boolean }

針對 Azure SQL 和 SQL Server，數據 API 產生器可以利用 SESSION_CONTEXT，將使用者指定的元數據傳送至基礎資料庫。 這類元數據可透過存取令牌中存在的宣告提供給數據 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"]
        }
      ]
    }
  }
}

解釋：

1. 預存程式 （GetUser）：

   • 此程式會檢查 SESSION_CONTEXT，以驗證呼叫者是否有角色 admin 或符合所提供的 userId。
   • 未經授權的存取會導致錯誤。

2. JSON 組態：

   • 啟用 set-session-context，將使用者元數據從存取令牌傳遞至資料庫。
   • parameters 屬性會對應預存程式所需的 userId 參數。
   • permissions 區塊可確保只有已驗證的使用者才能執行預存程式。

數據源檔案

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

運行

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

性能

例子

以下是運行時間區段的範例，其中指定了多個常見的預設參數。

{
  "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 （執行時間）

此物件會定義是否啟用 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>
    }
  }
}

性能

已開啟 （GraphQL 執行時間）

定義要全域啟用或停用 GraphQL 端點。 如果全域停用，則不論個別實體設定為何，都無法透過 GraphQL 要求存取任何實體。

格式

{
  "runtime": {
    "graphql": {
      "enabled": <true> (default) | <false>
    }
  }
}

例子

在此範例中，所有實體都會停用 GraphQL 端點。

{
  "runtime": {
    "graphql": {
      "enabled": false
    }
  }
}

深度限制 （GraphQL 執行時間）

查詢允許的最大查詢深度。

GraphQL 能夠根據關聯性定義處理巢狀查詢是一項不可思議的功能，可讓使用者在單一查詢中擷取複雜的相關數據。 不過，當使用者繼續新增巢狀查詢時，查詢的複雜性會增加，這最終可能會危害資料庫和 API 端點的效能和可靠性。 為了管理這種情況，runtime/graphql/depth-limit 屬性會設定 GraphQL 查詢的最大允許深度（和突變）。 此屬性可讓開發人員取得平衡，讓使用者享有巢狀查詢的優點，同時限制以防止可能危及系統效能和品質的案例。

例子

{
  "runtime": {
    "graphql": {
      "depth-limit": 2
    }
  }
}

路徑 （GraphQL 執行時間）

定義 GraphQL 端點可供使用所在的 URL 路徑。 例如，如果此參數設定為 /graphql，GraphQL 端點會公開為 /graphql。 根據預設，路徑會 /graphql。

格式

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

例子

在這裡範例中，根 GraphQL URI /query。

{
  "runtime": {
    "graphql": {
      "path": "/query"
    }
  }
}

允許反省 （GraphQL 執行時間）

此布爾值旗標可控制在 GraphQL 端點上執行架構反省查詢的能力。 啟用反省可讓客戶端查詢架構，以取得可用數據類型、可執行的查詢種類，以及可用的突變。

這項功能在開發期間很有用，可用來瞭解 GraphQL API 的結構，以及自動產生查詢的工具。 不過，針對生產環境，可能會停用以遮蔽 API 的架構詳細數據並增強安全性。 根據預設，會啟用內省，允許立即和全面探索 GraphQL 架構。

格式

{
  "runtime": {
    "graphql": {
      "allow-introspection": <true> (default) | <false>
    }
  }
}

例子

在此範例中，已停用反省。

{
  "runtime": {
    "graphql": {
      "allow-introspection": false
    }
  }
}

多個突變 （GraphQL 執行時間）

設定 GraphQL 執行時間的所有多重突變作業。

格式

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": <true> (default) | <false>
        }
      }
    }
  }
}

性能

多個突變 - 建立 （GraphQL 執行時間）

設定 GraphQL 執行時間的多個建立作業。

格式

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": <true> (default) | <false>
        }
      }
    }
  }
}

性能

例子

下列示範如何在 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 （執行時間）

本節概述 REST 端點的全域設定。 這些設定可作為所有實體的預設值，但可以在個別實體的個別設定中覆寫。

格式

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

性能

已開啟 （REST 執行時間）

布爾值旗標，決定 REST 端點的全域可用性。 如果停用，則不論個別的實體設定為何，都無法透過 REST 存取實體。

格式

{
  "runtime": {
    "rest": {
      "enabled": <true> (default) | <false>,
    }
  }
}

例子

在此範例中，所有實體都會停用 REST API 端點。

{
  "runtime": {
    "rest": {
      "enabled": false
    }
  }
}

路徑 （REST 執行時間）

設定用來存取所有公開 REST 端點的 URL 路徑。 例如，將 path 設定為 /api 可讓 REST 端點在 /api/<entity>存取。 不允許子路徑。 此欄位是選擇性的，/api 為預設值。

格式

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

例子

在這裡範例中，根 REST API URI /data。

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

要求本文嚴格 （REST 執行時間）

此設定可控制 REST 突變作業的要求本文嚴格程度（例如，POST、PUT、PATCH） 的驗證方式。

• true （預設值）：要求本文中未對應至數據表數據行的額外欄位會造成 BadRequest 例外狀況。
• false：會忽略額外的字段，而且只會處理有效的數據行。

此設定 不會 套用至 GET 要求，因為一律會忽略其要求本文。

具有特定數據行組態的行為

• 只有在承載中的值 null時，才會忽略具有 default（） 值的數據行 INSERT。 不論承載值為何，在 UPDATE 期間都不會忽略具有 default（） 的數據行。
• 計算數據行一律會被忽略。
• 自動產生的數據行一律會被忽略。

格式

{
  "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 語句：

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

主機 （執行時間）

運行時間組態內的 [host] 區段提供數據 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>"
        }
      }
    }
  }
}

性能

例子

以下是針對開發裝載所設定的運行時間範例。

{
  "runtime": {
    "host": {
      "mode": "development",
      "cors": {
        "allow-credentials": false,
        "origins": ["*"]
      },
      "authentication": {
        "provider": "Simulator"
      }
    }
  }
}

模式 （主機執行時間）

定義數據 API 產生器引擎是否應該以 development 或 production 模式執行。 預設值是 production。

一般而言，基礎資料庫錯誤會藉由將記錄的預設詳細層級設定為在開發中執行時 Debug，以詳細公開。 在生產環境中，記錄的詳細資料層級會設定為 Error。

格式

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

值

以下是此屬性允許的值清單：

行為

• 只有 development 模式才可使用 Swagger。
• 只有在 development 模式中，才能使用香蕉蛋糕流行。

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

設定任何指定結果的大小上限（以 MB 為單位）。 此設定可讓使用者設定其主機平臺記憶體在從基礎數據源串流數據時可以處理的數據量。

當使用者要求大型結果集時，可能會使資料庫和數據 API 產生器變得緊張。 為了解決此問題，max-response-size-mb 可讓開發人員限制以 MB 為單位的回應大小上限，作為數據源的數據流。 此限制是以整體數據大小為基礎，而不是數據列數目。 由於數據行的大小可能會有所不同，因此某些數據行（例如文字、二進位、XML 或 JSON）每個數據行最多可以容納 2 GB，使得個別數據列可能非常大。 此設定可協助開發人員藉由限制回應大小並防止系統多載來保護其端點，同時維持不同數據類型的彈性。

允許的值

格式

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

CORS （主機執行時間）

數據 API 產生器引擎主機的跨原始來源資源分享 （CORS） 設定。

格式

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

性能

允許認證 （主機執行時間）

如果為 true，請設定 Access-Control-Allow-Credentials CORS 標頭。

格式

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": <true> (default) | <false>
      }
    }
  }
}

來源 （主機執行時間）

設定具有 CORS 允許來源清單的陣列。 此設定允許所有來源的 * 通配符。

格式

{
  "runtime": {
    "host": {
      "cors": {
        "origins": ["<array-of-strings>"]
      }
    }
  }
}

例子

以下是一個主機範例，可讓 CORS 不需來自所有來源的認證。

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": false,
        "origins": ["*"]
      }
    }
  }
}

驗證 （主機執行時間）

設定數據 API 產生器主機的驗證。

格式

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

性能

驗證和客戶責任

數據 API 產生器的設計目的是在更廣泛的安全性管線內運作，而且在處理要求之前，必須先設定重要步驟。 請務必了解數據 API 產生器不會驗證直接呼叫者（例如 Web 應用程式），而是根據受信任的識別提供者所提供的有效 JWT 令牌（例如 Entra ID）來驗證使用者。 當要求到達數據 API 產生器時，它會假設 JWT 令牌有效，並針對您已設定的任何必要條件進行檢查，例如特定宣告。 然後會套用授權規則，以判斷使用者可以存取或修改的內容。

授權通過之後，數據 API 產生器會使用連接字串中指定的帳戶來執行要求。 由於此帳戶通常需要提高的許可權來處理各種使用者要求，因此必須將其訪問許可權降到最低，以降低風險。 建議您藉由設定前端 Web 應用程式與 API 端點之間的 Private Link，以及強化裝載數據 API 產生器的機器，來保護您的架構。 這些措施有助於確保您的環境保持安全、保護您的數據，以及將可能遭到惡意探索的弱點降至最低，以存取、修改或外洩敏感性資訊。

提供者 （主機執行時間）

authentication.provider 組態內的 host 設定會定義數據 API 產生器所使用的驗證方法。 它會決定 API 如何驗證嘗試存取其資源之使用者或服務的身分識別。 此設定可藉由支援針對不同環境和安全性需求量身打造的各種驗證機制，在部署和整合方面具有彈性。

格式

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

值

以下是此屬性允許的值清單：

JSON Web 令牌 （主機運行時間）

如果驗證提供者設定為 AzureAD （Microsoft Entra ID），則需要本節來指定 JSOn Web 令牌 （JWT） 令牌的對象和簽發者。 此數據可用來驗證您Microsoft Entra 租使用者的令牌。

如果驗證提供者 AzureAD Microsoft Entra ID，則為必要項。 本節必須指定 audience 和 issuer，以針對預期的 AzureAD 租使用者驗證接收的 JWT 令牌。

格式

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

性能

例子

數據 API 產生器 （DAB） 提供彈性的驗證支援，可與 Microsoft Entra Identity 和自定義 JSON Web 令牌 （JWT） 伺服器整合。 在此映像中，JWT 伺服器 代表在成功登入時向用戶端發出 JWT 令牌的驗證服務。 然後，用戶端會將令牌傳遞至 DAB，以詢問其宣告和屬性。

以下是 host 屬性的範例，因為您可能會在解決方案中做出的各種架構選擇。

Azure Static Web Apps

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

使用 StaticWebApps時，數據 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"
   }
  }
 }
}

驗證會委派給可發出存取令牌的支持識別提供者。 取得的存取令牌必須包含在數據 API 產生器的連入要求中。 然後，數據 API 產生器會驗證任何呈現的存取令牌，確保數據 API 產生器是令牌的預期物件。

Microsoft項目標識碼

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

物件 （主機執行時間）

JWT 令牌的物件。

格式

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

簽發者 （主機執行時間）

JWT 令牌的簽發者。

格式

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

分頁 （執行時間）

設定 REST 和 GraphQL 端點的分頁限制。

格式

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>,
      "default-page-size": <integer; default: 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 會傳回 value 陣列中的兩筆記錄，因為 default-page-size 設為 2。 如果有更多結果存在，數據 API 產生器會在回應中包含 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） 來調整每個查詢的結果數目。

範例 REST 查詢：

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

範例 GraphQL 查詢：

query {
  users(first: 5) {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
  }
}

頁面大小上限 （分頁運行時間）

設定 REST 或 GraphQL 所傳回的最上層記錄數目上限。 如果使用者要求超過 max-page-size，則結果會限制在 max-page-size。

允許的值

格式

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

預設頁面大小 （分頁執行時間）

設定啟用分頁但未提供明確頁面大小時傳回的最上層記錄預設數目。

允許的值

快取 （執行時間）

啟用和設定整個運行時間的快取。

格式

{
  "runtime": {
    "cache": <object>
  }
}

性能

例子

在此範例中，會啟用快取，且專案會在 30 秒後到期。

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

已開啟 （快取執行時間）

針對所有實體啟用全域快取。 預設為 false。

格式

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

例子

在此範例中，快取已停用。

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

秒內 TTL （快取執行時間）

以秒為單位設定快取專案的存留時間 （TTL） 值。 經過此時間之後，專案會自動從快取剪除。 預設值為 5 秒。

格式

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

例子

在此範例中，會全域啟用快取，且所有專案會在 15 秒之後到期。

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

遙測 （執行時間）

此屬性會將Application Insights 設定為集中式 API 記錄。 深入瞭解 。

格式

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

Application Insights （遙測運行時間）

已啟用 （Application Insights 遙測）

連接字串 （Application Insights 遙測）

實體

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

性能

例子

例如，此 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'"
          }
        }
      ]
    }
  }
}

源

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

性能

例子

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。預存程式範例：

此範例示範如何將 User 實體與來源程式產生關聯 dbo.GetUsers。

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 屬性是選擇性的。

物件

要使用的資料庫物件名稱。 如果對象屬於 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"
      }
    }
  }
}

類型（實體）

type 屬性會識別實體背後的資料庫物件類型，包括 view、table和 stored-procedure。 此屬性為必要屬性，且沒有預設值。

格式

{
  "entities": {
    "<entity-name>": {
      "type": <"view" | "stored-procedure" | "table">
    }
  }
}

值

例子

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

索引鍵欄位

{entity}.key-fields 屬性對於檢視所支援的實體而言特別必要，因此 Data API Builder 知道如何識別及傳回單一專案。 如果 type 設定為 view 而不指定 key-fields，引擎會拒絕啟動。 這個屬性可以搭配數據表和預存程式使用，但不會在這些情況下使用。

格式

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

權限

本節會定義誰可以存取相關實體，以及允許哪些動作。 權限定義於角色和 CRUD 作業：create、read、update和 delete。 permissions 區段會指定哪些角色可以存取相關實體，以及使用哪些動作。

格式

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "actions": ["create", "read", "update", "delete", "execute", "*"]
        }
      ]
    }
  }
}

例子

範例 1：用戶實體上的匿名角色

在此範例中，anonymous 角色是以存取 User 實體上所有可能動作的存取權來定義。

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

範例 2：匿名角色的混合動作

此範例示範如何混合 User 實體的字串和物件數位動作。

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            { "action": "read" },
            "create"
          ]        
        }
      ]
    }
  }
}

匿名角色：允許匿名使用者讀取假設敏感性欄位以外的所有欄位（例如 secret-field）。 搭配使用 "include": ["*"] 與 "exclude": ["secret-field"] 會隱藏 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": []
}

性能

角色

字串，包含所定義許可權所套用之角色的名稱。 角色會設定應該在其中執行要求的許可權內容。 針對運行時間組態中定義的每個實體，您可以定義一組角色和相關聯的許可權，以決定如何透過 REST 和 GraphQL 端點存取實體。 角色不會加總。

數據 API 產生器會評估單一角色內容中的要求：

格式

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role">,
          "actions": ["create", "read", "update", "delete", "execute", "*"],
          "fields": {
            "include": <array of strings>,
            "exclude": <array of strings>
          }
        }
      ]
    }
  }
}

例子

此範例會定義名為 reader 的角色，只具有 User 實體 read 許可權。

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

當 顯示有效的存取令牌，並 包含 X-MS-API-ROLE HTTP 標頭時，您可以使用 <custom-role>，並指定存取令牌角色宣告中也包含的使用者角色。 以下是對 User 實體的 GET 要求範例，包括授權持有人令牌和 X-MS-API-ROLE 標頭，在 REST 端點基底 /api 使用不同語言 localhost。

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

動作 （string-array）

字串值的陣列，詳細說明相關聯角色允許的作業。 針對 table 和 view 資料庫物件，角色可以使用 create、read、update或 delete 動作的任何組合。 針對預存程式，角色只能有 execute 動作。

例子

此範例會為名為 contributor 的角色提供 create 和 read 許可權，以及 User 實體上名為 auditor 的角色 delete 許可權。

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "auditor",
          "actions": ["delete"]
        },
        {
          "role": "contributor",
          "actions": ["read", "create"]
        }
      ]
    }
  }
}

另一個範例：

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

動作 （object-array）

動作對象的陣列，詳細說明相關聯角色的允許作業。 針對 table 和 view 物件，角色可以使用 create、read、update或 delete的任何組合。 針對預存程式，只允許 execute。

格式

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <array of strings>,
              "policy": <object>
            }
          ]
        }
      ]
    }
  }
}

性能

例

此範例只會授與 User 實體上 auditor 角色 read 許可權，並具有欄位和原則限制。

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["last_login"]
              },
              "policy": {
                "database": "@item.IsAdmin eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

行動

指定資料庫物件上允許的特定作業。

值

格式

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": "<role>",
          "actions": [
            {
              "action": "<string>",
              "fields": {
                "include": [/* fields */],
                "exclude": [/* fields */]
              },
              "policy": {
                "database": "<predicate>"
              }
            }
          ]
        }
      ]
    }
  }
}

例

以下是 anonymous 使用者可以從 User 數據表 execute 預存程式和 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"
            }
          ]
        }
      ]
    }
  }
}

領域

允許資料庫物件存取特定欄位的細微規格。 角色設定是具有兩個內部屬性的物件類型，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": []
            }
        }
    ]
}

政策

每個 policy定義的 action 區段會定義專案層級安全性規則（資料庫原則），以限制從要求傳回的結果。 子區段 database 表示要求執行期間評估的資料庫原則表達式。

格式

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <object>,
              "policy": {
                "database": <string>
              }
            }
          ]
        }
      ]
    }
  }
}

性能

描述

database 原則：轉譯成查詢述詞資料庫的 OData 類似表示式會評估，包括像是 eq、lt和 gt等運算符。 為了讓要求傳回結果，從資料庫原則解析的要求查詢述詞必須在針對資料庫執行時評估為 true。

predicate 是評估為TRUE或 FALSE 的表達式。 述詞用於 WHERE 子句和 HAVING 子句的搜尋 條件、FROM 子句的聯結條件，以及需要布爾值的其他建構。 （Microsoft Learn Docs）

資料庫原則

撰寫資料庫原則表達式時，可以使用兩種類型的指示詞來管理資料庫原則：

以下是一些範例資料庫原則：

• @claims.userId eq @item.OwnerId
• @claims.userId gt @item.OwnerId
• @claims.userId lt @item.OwnerId

數據 API 產生器會將 UserId 宣告的值與資料庫欄位的值 OwnerId進行比較。 結果承載只包含滿足要求元數據和資料庫原則表達式 的記錄。

局限性

數據表和檢視支援資料庫原則。 預存程式無法設定原則。

資料庫原則不會防止要求在資料庫內執行。 此行為是因為這些行為會在傳遞至資料庫引擎的產生查詢中解析為述詞。

actions 建立、讀取、更新，以及 刪除，才支援資料庫原則。 由於預存過程調用中沒有述詞，因此無法附加它們。

支援的 OData 類似運算符

如需詳細資訊，請參閱二元運算符。

如需詳細資訊，請參閱 一元運算子。

實體功能變數名稱限制

• 規則：必須以字母或底線 （_） 開頭，後面接著最多 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 端點內數據模型的清晰性和輔助功能。

例子

請考慮使用宣告和專案指示詞的數據 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）。 這可確保員工只能存取自己的記錄，除非他們屬於人力資源部門。 原則可以根據動態條件強制執行數據列層級安全性。

資料庫

每個 policy定義的 action 區段會定義專案層級安全性規則（資料庫原則），以限制從要求傳回的結果。 子區段 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。

撰寫資料庫原則表達式時，可以使用兩種類型的指示詞來管理資料庫原則：

例子

例如，基本原則表達式可以評估數據表中的特定欄位是否為 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"
              }
            }
          ]
        }
      ]
    }
  }
}

局限性

• 數據表和檢視支援資料庫原則。 預存程式無法設定原則。
• 資料庫原則無法用來防止要求在資料庫內執行。 這項限制是因為資料庫原則會在產生的資料庫查詢中解析為查詢述詞。 資料庫引擎最終會評估這些查詢。
• actions create、read、update和 delete僅支援資料庫原則。
• 資料庫原則 OData 運算式語法僅支持這些案例。
  • 二元運算符，包括但不限於;and、or、eq、gt和 lt。 如需詳細資訊，請參閱BinaryOperatorKind。
  • 一元運算子，例如 -（負值）和 not 運算符。 如需詳細資訊，請參閱UnaryOperatorKind。
• 資料庫原則也有與域名相關的限制。
  • 以字母或底線開頭的實體功能變數名稱，後面最多127個字母、底線或數位。
  • 此需求是每個 OData 規格。 如需詳細資訊，請參閱 OData 通用架構定義語言。

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

性能

例子

這兩個範例在功能上是相等的。

{
  "entities": {
    "Author": {
      "graphql": true
    }
  }
}

{
  "entities": {
    "Author": {
      "graphql": {
        "enabled": true
      }
    }
  }
}

在此範例中，定義的實體 Book，表示我們正在處理資料庫中書籍的相關數據集。 GraphQL 區段中 Book 實體的組態提供清楚的結構，說明如何在 GraphQL 架構中呈現和互動。

Enabled 屬性：Book 實體可透過 GraphQL（"enabled": true），這表示開發人員和使用者可以透過 GraphQL 作業查詢或變動書籍數據。

Type 屬性：實體是以單一名稱表示，"Book" 和 GraphQL 架構中的複數名稱 "Books"。 這項區別可確保在查詢單一書籍或多本書時，架構會提供直覺式命名的類型（單一專案Book，Books 清單），以提高 API 的可用性。

Operation 屬性：作業會設定為 "query"，指出透過 GraphQL 與 Book 實體的主要互動是要查詢（擷取）數據，而不是變動（建立、更新或刪除）。 此設定與一般使用模式一致，其中書籍數據比修改更頻繁。

{
  "entities": {
    "Book": {
      ...
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "Book",
          "plural": "Books"
        },
        "operation": "query"
      },
      ...
    }
  }
}

類型 （GraphQL 實體）

這個屬性會指定 GraphQL 架構內實體的命名慣例。 它同時支援純量字串值和物件類型。 物件值會指定單數和複數形式。 此屬性提供架構可讀性和用戶體驗的細微控制。

格式

{
  "entities": {
    <entity-name>: {
      "graphql": {
        "type": <string>
      }
    }
  }
}

{
  "entities": {
    <entity-name>: {
      "graphql": {
        "type": {
          "singular": <string>,
          "plural": <string>
        }
      }
    }
  }
}

性能

例子

若要更充分地控制 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 實體）

對於對應至預存程式的實體，operation 屬性會指定可存取預存程式之 GraphQL 作業類型（查詢或突變）。 此設定允許架構的邏輯組織，並遵循 GraphQL 最佳做法，而不會影響功能。

如果遺漏，則預設為 operationmutation。

格式

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "operation": "query" (default) | "mutation"
      }
    }
  }
}

值

以下是此屬性允許的值清單：

例子

當 operationmutation時，GraphQL 架構會類似：

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

當 operationquery時，GraphQL 架構會類似：

GraphQL 架構會類似：

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

已開啟 （GraphQL 實體）

啟用或停用 GraphQL 端點。 控制實體是否可透過 GraphQL 端點取得。 切換 enabled 屬性可讓開發人員選擇性地從 GraphQL 架構公開實體。

格式

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "enabled": <true> (default) | <false>
      }
    }
  }
}

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

性能

例子

這兩個範例在功能上是相等的。

{
  "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 實體）

這個屬性可作為 REST API 內實體可見度的切換。 藉由將 enabled 屬性設定為 true 或 false，開發人員可以控制特定實體的存取權，以啟用符合應用程式安全性和功能需求的量身打造 API 介面。

格式

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>
      }
    }
  }
}

路徑 （REST 實體）

path 屬性會指定用來透過 REST API 存取實體的 URI 區段。 此自定義可讓您在預設實體名稱之外提供更具描述性或簡化的端點路徑，以增強 API 導覽性和用戶端整合。 根據預設，路徑會 /<entity-name>。

格式

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "path": <string; default: "<entity-name>">
      }
    }
  }
}

例子

此範例會使用 Author 端點公開 /auth 實體。

{
  "entities": {
    "Author": {
      "rest": {
        "path": "/auth"
      }
    }
  }
}

方法（REST 實體）

methods 屬性特別適用於預存程式，定義程式可以響應的 HTTP 動詞命令（例如 GET、POST）。 方法可精確控制透過 REST API 公開預存程式的方式，確保與 RESTful 標準和用戶端期望的相容性。 本節強調平臺對彈性和開發人員控制的承諾，允許針對每個應用程式的特定需求量身打造的精確且直覺式的 API 設計。

如果省略或遺失，則預設為 methodsPOST。

格式

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "methods": ["GET" (default), "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" ]
      }
    }
  }
}

對應（實體）

mappings 區段可讓您設定資料庫物件欄位的別名或公開名稱。 已設定的公開名稱同時套用至 GraphQL 和 REST 端點。

格式

{
  "entities": {
    "<entity-name>": {
      "mappings": {
        "<field-1-name>": "<field-1-alias>",
        "<field-2-name>": "<field-2-alias>",
        "<field-3-name>": "<field-3-alias>"
      }
    }
  }
}

例子

在此範例中，資料庫物件 sku_titledbo.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）。 此別名有數個用途：

• Clarity and Consistency：不論基礎資料庫架構為何，它都能在 API 中使用清楚且一致的命名。 例如，資料庫中的 BookID 會以 API 中的 id 表示，讓開發人員與端點互動更直覺。

• GraphQL 合規性：藉由提供別名域名的機制，可確保透過 GraphQL 介面公開的名稱符合 GraphQL 命名需求。 注意名稱很重要，因為 GraphQL 有嚴格的名稱規則（例如，沒有空格，必須以字母或底線開頭等等）。 例如，如果資料庫功能變數名稱不符合這些準則，則可以透過對應將它別名為符合規範的名稱。

• 彈性：這個別名會在資料庫架構與 API 之間新增一層抽象概念，讓其中一個變更不需要變更另一個。 例如，如果對應保持一致，資料庫中的域名變更不需要更新 API 檔或客戶端程序代碼。

• 功能變數名稱模糊化：對應允許混淆功能變數名稱，這有助於防止未經授權的使用者推斷資料庫架構或所儲存數據的敏感性資訊。

• 保護專屬資訊：藉由重新命名字段，您也可以保護可能透過資料庫原始功能變數名稱提示的專屬名稱或商業規則。

關聯性（實體）

本節對應包含一組關聯性定義，可對應實體與其他公開實體的相關方式。 這些關聯性定義也可以選擇性地包含用來支援及強制執行關聯性之基礎資料庫物件的詳細數據。 本節中定義的物件會公開為相關實體中的 GraphQL 欄位。 如需詳細資訊，請參閱 資料 API 產生器關聯性分解。

[relationships] 區段概述實體如何在數據 API 產生器內互動，詳細說明這些關聯性的關聯和潛在資料庫支援。 每個關聯性 relationship-name 屬性都是必要屬性，而且在指定實體的所有關聯性中必須是唯一的。 自定義名稱可確保清楚、可識別的連接，並維護從這些組態產生的 GraphQL 架構完整性。

格式

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

性能

例子

考慮關聯性時，最好比較 一對多之間的差異、多對一，以及 多對多 關聯性。

一對多

首先，讓我們考慮一個與公開 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]!
}

多對一

接下來，請考慮 多對一，以將基數設定為 one。 公開的 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]!
}

基數

指定目前來源實體是否只與目標實體或多個單一實例相關。

值

以下是此屬性允許的值清單：

目標實體

在設定中定義為關聯性目標的實體名稱。

來源欄位

選擇性參數，用來定義用於對應 來源 實體中用來連線至目標實體中相關專案的欄位。

目標欄位

選擇性參數，用來定義用於對應 目標 實體中用來連線至來源實體中相關專案的欄位。

連結物件或實體

對於多對多關聯性，資料庫對象或實體的名稱，其中包含定義其他兩個實體之間關聯性所需的數據。

連結來源欄位

與來源實體相關的資料庫物件或實體欄位名稱。

鏈接目標欄位

與目標實體相關的資料庫物件或實體欄位名稱。

快取 （實體）

啟用及設定實體的快取。

格式

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

性能

例子

在此範例中，會啟用快取，且專案會在 30 秒後到期。

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

已開啟 （快取實體）

啟用實體的快取。

資料庫物件支援

HTTP 標頭支援

格式

{
  "entities": {
    "<entity-name>": {
      "cache": {
        "enabled": <boolean> (default: false)
      }
    }
  }
}

例子

在此範例中，快取已停用。

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": false
      }
    }
  }
}

秒內 TTL （快取實體）

以秒為單位設定快取專案的存留時間 （TTL） 值。 經過此時間之後，專案會自動從快取剪除。 預設值為 5 秒。

格式

{
  "entities": {
    "<entity-name>": {
      "cache": {
        "ttl-seconds": <integer; inherited>
      }
    }
  }
}

例子

在此範例中，會啟用快取，且專案會在 15 秒之後到期。 省略時，此設定會繼承全域設定或預設值。

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

相關內容

• Functions 參考
• 命令行介面 （CLI） 參考