資料模型版本設定Data Model versioning

OData 服務 (例如 Power BI 資料模型) 所公開的資料模型會定義 OData 服務與其用戶端之間的合約。The Data Model exposed by an OData Service, such as the Power BI data model, defines a contract between the OData service and its clients. 服務只能擴充其模型到不會中斷現有用戶端的程度。Services are allowed to extend their model only to the degree that it does not break existing clients. 重大變更 (例如移除屬性或變更現有屬性的類型) 需要提供新的服務版本,其位於新模型的不同服務根 URL。Breaking changes, such as removing properties or changing the type of existing properties, require that a new service version is provided at a different service root URL for the new model.

下列資料模型新增視為安全,並且不需要對其進入點進行版本設定的服務。The following Data Model additions are considered safe and do not require services to version their entry point.

  • 加入可為 null 或具有預設值的屬性;如果與現有的動態屬性同名,其類型 (或基底類型) 必須與現有的動態屬性相同Adding a property that is nullable or has a default value; if it has the same name as an existing dynamic property, it must have the same type (or base type) as the existing dynamic property
  • 加入可為 null 或具有以集合為值的導覽屬性;如果與現有的動態導覽屬性同名,其類型 (或基底類型) 必須與現有的動態導覽屬性相同Adding a navigation property that is nullable or collection-valued; if it has the same name as an existing dynamic navigation property, it must have the same type (or base type) as the existing dynamic navigation property
  • 將新的實體類型加入模型Adding a new entity type to the model
  • 將新的複雜類型加入模型Adding a new complex type to the model
  • 加入新的實體集Adding a new entity set
  • 加入新的單一值Adding a new singleton
  • 加入動作、函式、動作匯入或函式匯入Adding an action, a function, an action import, or function import
  • 加入可為 null 的動作參數Adding an action parameter that is nullable
  • 加入類型定義或列舉Adding a type definition or enumeration
  • 將任何註釋加入不須經用戶端了解就能正確與服務互動的模型項目Adding any annotation to a model element that does not need to be understood by the client to interact with the service correctly

用戶端「應該」為服務對其模型進行這類累加的變更有所準備。Clients *SHOULD _ be prepared for services to make such incremental changes to their model. 用戶端尤其應該準備好接收屬性與服務先前未定義的衍生類型。In particular, clients should be prepared to receive properties and derived types not previously defined by the service.

服務「不應該」變更相依於已驗證使用者的資料模型。Services _ SHOULD NOT* change their data model depending on the authenticated user. 如果是使用者或使用者群組相依的資料模型,所有變更都必須是安全變更,如同在此節中比較完整模型與授權受限使用者可見的模型時所定義。If the data model is user or user group dependent, all changes MUST be safe changes as defined in this section when comparing the full model to the model visible to users with limited authorizations.

如需 OData 資料模型標準的詳細資訊,請參閱 OData 4.0 版第 1 部分:Protocol Plus Errata 02For more about OData Data Model standards, see OData Version 4.0 Part 1: Protocol Plus Errata 02.

請參閱See also

Power BI REST API 概觀Overview of Power BI REST API