Microsoft Graph REST API 弃用指南：用 OData Revisions 注解与 Deprecation/Sunset 响应头管理 API 生命周期

API设计【免费下载链接】api-guidelinesMicrosoft REST API Guidelines项目地址https://gitcode.com/gh_mirrors/ap/api-guidelines点击查看免费下载本文基于 Microsoft Graph REST API Guidelines 仓库graph/articles/deprecation.md的官方弃用指南系统讲解在 Microsoft Graph 生态中如何以 OData 标准注解标记已弃用的模型元素、如何通过 HTTP 响应头向客户端传递弃用与移除时间以及弃用流程与版本化、破坏性变更判定之间的配合关系。读完本文你将掌握 Revisions 注解五个核心字段的语义与书写规范、注解的可施加对象与级联规则、Deprecation/Sunset 响应头的完整格式并能独立为一个即将退休的 API 元素设计合规的弃用方案。弃用的前提什么时候必须走弃用流程弃用不是独立动作而是 API 演进Versioning流程的后半段。在 Microsoft Graph REST API Guidelines 的「API contract and nonbackward compatible changes」章节中官方对变更做了明确分级非破坏性变更Non-breaking changes如新增 nullable 或有默认值的属性、在可演化枚举evolvable enum的哨兵成员之后追加成员、改变属性顺序、调整不透明字符串如资源 ID的长度或格式等通常不需要弃用。破坏性变更Breaking changes如改变资源 URL 或基本请求/响应、删除/重命名/不兼容地改变已声明属性的类型、删除或重命名 API 及参数、新增必填请求头、为不可演化枚举新增成员、给既有类型新增Nullablefalse属性、改变顶层错误码、对既有集合引入服务端分页等。当 API 确实需要引入破坏性变更时就必须为被替换的旧元素创建新版本并将旧元素标记为弃用。Microsoft Graph 的版本化做法是为元素添加一个唯一命名的新版本优先取自然的新名称若原名仍最贴切则在原名后追加_v2后缀然后用注解把旧版本标记为 deprecated——这正是本文要详细展开的弃用标注机制。此外弃用的时间承诺也有硬性约束见 GuidelinesGraph.mdGA 版本v1.0 端点中的 API 一旦被弃用旧元素必须至少继续支持 36 个月若能证明无使用量最短可缩减为 24 个月。beta 端点允许在评估依赖与客户影响后执行破坏性变更与弃用官方建议先在 beta 端点验证新元素版本再推广到 GA 端点。Revisions 注解弃用的官方标注方式在 OData 的 CSDLCommon Schema Definition Language模型中弃用通过Org.OData.Core.V1.Revisions术语Term以注解形式声明。每次弃用需要在一个Record中提供五个字段字段含义与格式要求Date元素被标记为弃用的日期Version用于组织 ChangeLog变更日志格式为YYYY-MM/Category其中YYYY-MM是弃用公告所在的月份Category是该项变更归属的分类Kind取值固定为Deprecated枚举成员Org.OData.Core.V1.RevisionKind/DeprecatedDescription面向人类的变更描述用于 ChangeLog、文档等处RemovalDate元素最早可被移除的日期其中Version字段的设计很关键它把「弃用公告月份」与「变更分类」绑定在一起使得 ChangeLog 可以按时间轴与主题分类快速检索某次弃用RemovalDate则为客户端提供明确的迁移截止线与前述「GA 至少支持 36 个月或 24 个月且有非使用证明」的承诺相互印证。注解的施加对象与级联规则该注解可以施加于以下任一元素类型Type实体集Entity Set单例Singleton属性Property导航属性Navigation Property函数Function动作Action其中存在一条重要的级联规则如果一个类型被标记为弃用则该类型的成员成员属性、导航属性等无需再逐一标注弃用对该类型的任何引用也无需额外标注。也就是说弃用标注应该施加在语义层级最高的位置——弃用了类型就等于弃用了它所有的成员与使用点避免冗余注解与不一致。属性弃用完整示例解析以下 XML 来自 deprecation.md 的官方示例展示了如何在实体类型outlookTask上通过Org.OData.Core.V1.Revisions注解完成一次完整弃用声明EntityType NameoutlookTask BaseTypeMicrosoft.OutlookServices.outlookItem ags:IsMastertrue ags:WorkloadNameTask ags:EnabledForPassthroughtrue Annotation TermOrg.OData.Core.V1.Revisions Collection Record PropertyValue Property Date Date2022-03-30/ PropertyValue Property Version String2022-03/Tasks_And_Plans/ PropertyValue Property Kind EnumMemberOrg.OData.Core.V1.RevisionKind/Deprecated/ PropertyValue Property Description StringThe Outlook tasks API is deprecated and will stop returning data on June 30, 2024. Please use the new To Do API./ PropertyValue Property RemovalDate Date2024-06-30/ /Record /Collection /Annotation /EntityType逐字段对照官方规范Date2022-03-30即该 API 被正式标记为弃用的日期。Version2022-03/Tasks_And_Plans公告月份为 2022 年 3 月分类为Tasks_And_PlansChangeLog 可据此归类检索。KindOrg.OData.Core.V1.RevisionKind/Deprecated指明本条修订的性质是弃用。Description明确告知开发者「Outlook tasks API 已弃用将于 2024 年 6 月 30 日停止返回数据请改用新的 To Do API」——好的描述应同时给出弃用事实、停服时间、替代方案三要素。RemovalDate2024-06-30即该元素最早可被移除的日期。注意Revisions术语的值为一个Collection意味着可以容纳多个Record同一元素可记录多次修订例如先标记弃用、后续再补充修订。集合属性的侧边并存弃用实战keyCredentials → keyCredentials_v2collections.md 第 11.1 节给出了一个在集合属性上应用同一注解的真实场景当application实体的keyCredentials集合属性需要演化时模型被更新为「新老两个集合并列」并把旧属性标记为弃用EntityType Nameapplication Key PropertyRef Nameid / /Key Property Nameid TypeEdm.String Nullablefalse / Property NamekeyCredentials TypeCollection(self.keyCredential) Annotation TermOrg.OData.Core.V1.Revisions Collection Record PropertyValue Property Date Date2020-08-20/ PropertyValue Property Version String2020-08/KeyCredentials/ PropertyValue Property Kind EnumMemberOrg.OData.Core.V1.RevisionKind/Deprecated/ PropertyValue Property Description StringkeyCredentials has been deprecated. Please use keyCredentials_v2 instead./ PropertyValue Property RemovalDate Date2022-08-20/ /Record /Collection /Annotation /Property NavigationProperty NamekeyCredentials_v2 TypeCollection(self.keyCredential_v2) ContainsTargettrue / /EntityType这个示例补充了三个重要实践细节注解直接施加在属性Property上而_v2新集合被建模为含ContainsTargettrue的导航属性使新集合具备独立寻址与删除能力客户端可用DELETE /applications/{applicationId}/keyCredentials_v2/{keyId}移除单个元素。在过渡期内keyCredentials与keyCredentials_v2被视为同一份数据的两个「视图」workload 必须保持两者一致且拒绝在同一请求中同时更新两个集合返回400 Bad Request。RemovalDate2022-08-20与Date2020-08-20之间恰好相隔两年符合最短支持期的时间承诺示例。运行时信号Deprecation 与 Sunset 响应头模型注解解决的是「契约层」的声明而运行时还需要把弃用状态传达给实际调用方。当请求 URL 引用到已弃用的模型元素时网关gateway会在响应中自动追加两个响应头规范出处Deprecation Header 草案Deprecation头携带该元素被标记为弃用的日期Sunset头携带「弃用日期之后两年」的日期即预期移除时间。官方示例如下见 deprecation.mdDeprecation: Wed, 30 Mar 2022 11:59:59 GMT Sunset: Thursday, 30 June 2024 23:59:59 GMT Link: https://docs.microsoft.com/en-us/graph/changelog#2022-03-30_name ; reldeprecation; typetext/html; titlename,https://docs.microsoft.com/en-us/graph/changelog#2022-03-30_state ; reldeprecation; typetext/html; titlestate三点解读Deprecation头的日期2022-03-30与注解中Date字段一致二者互为印证Sunset头给出的是「两年后」此处为 2024-06-30与注解RemovalDate一致即服务方承诺的移除时间窗。Link头通过reldeprecation语义把客户端引导到 ChangeLog 中对应月份、对应分类的变更条目#2022-03-30_name、#2022-03-30_state与注解Version字段的YYYY-MM/Category结构一一对应——这正是Version字段存在的意义让运行时响应头与文档化 ChangeLog 可互相检索。三个头共同构成对客户端的完整通知何时弃用Deprecation、何时失效Sunset、去哪里了解细节Link。对比参考Azure 指南的 azure-deprecating 头同为微软生态Azure 的 REST API 指南第 816 行起「Deprecating Behavior Notification」节采用了另一种响应头方案azure-deprecating头以分号分隔的字符串声明「什么将被弃用、何时失效、去哪里了解」例如azure-deprecating: API version 2009-27-07 will retire on 2022-12-01 (https://azure.microsoft.com/updates/video-analyzer-retirement);TLS 1.0 1.1 will retire on 2020-10-30 (https://azure.microsoft.com/updates/azure-active-directory-registration-service-is-ending-support-for-tls-10-and-11/)对比可见Microsoft Graph 采用「注解声明 Deprecation/Sunset/Link 三头」的结构化方案弃用日期、移除日期、变更详情链接分别在独立字段/头中表达便于客户端程序化解析而 Azure 方案把信息压缩进单一头值的字符串中。设计自己的 API 弃用机制时可据此权衡结构化与紧凑性。弃用流程的上下游配套弃用标注并非孤立机制它与仓库中多个模式文档协同工作可演化枚举evolvable enumsevolvable-enums.md 明确指出改变unknownFutureValue哨兵成员的位置属于破坏性变更必须遵循 弃用流程。枚举的扩展方向是在哨兵之后追加成员因此正常情况下枚举本身不易触犯弃用但若确实需要改变哨兵位置或重构枚举成员顺序则必须走本文所述的 Revisions 注解流程。动作/函数actions/functionsoperations.md 规定为既有 action/function 新增必填非空参数属于破坏性变更未经符合弃用指南的版本化处理不允许直接实施——即新增参数要伴随新操作版本并对旧版本执行弃用标注。GA/beta 双端点策略结合 GuidelinesGraph.md弃用标注的Date应选择公告月份RemovalDate必须满足 GA 端点的 36/24 个月支持承诺beta 端点则可更灵活地先行验证。弃用标注自检清单完成一次合规弃用建议逐项核对五字段齐全Date、VersionYYYY-MM/Category、KindDeprecated、Description含替代方案指引、RemovalDate均已填写。位置正确注解施加于类型、实体集、单例、属性、导航属性、函数或动作之一若类型已弃用不重复标注其成员与使用点。时间合规RemovalDate距Date满足 GA 端点的支持期要求36 个月或 24 个月且有非使用证明。运行时信号就绪引用弃用元素的请求能收到Deprecation、Sunset与带reldeprecation的Link响应头且与注解字段一致。替代路径明确Description与 ChangeLogVersion分类指向清晰的新版本/替代 API客户端可据此平滑迁移。通过「CSDL 注解 运行时响应头 ChangeLog 分类」三层机制Microsoft Graph 把 API 弃用从一次突发的破坏性变更转化为一种可预期、可检索、可程序化感知的标准化生命周期流程——这也是大型 REST 生态管理接口演进的参考范式。赞分享API设计【免费下载链接】api-guidelinesMicrosoft REST API Guidelines项目地址https://gitcode.com/gh_mirrors/ap/api-guidelines点击查看免费下载相关推荐BaiduPCS-Go 下载只有 100KB/s三步自查、四步提速SVIP 限速恢复指南BaiduPCS Go 下载只有 100KB/s三步自查、四步提速SVIP 限速恢复指南 先说你可能遇到的场景用 BaiduPCS Go 拉一个几十 GBCLI网络3 步用触控板管理 MacBook 窗口Loop 窗口管理实操3 步用触控板管理 MacBook 窗口Loop 窗口管理实操 你正在 MacBook 上写文档旁边还开着浏览器、终端和备忘录几个窗口叠在一块儿。想把浏览桌面应用Electron.NET 应用生命周期管理Electron.App API 完整实战指南Electron.NET 应用生命周期管理Electron.App API 完整实战指南 导读 Electron.App 是 Electron.NET 中控制桌面应用跨平台上一篇Marp 入门指南用 Markdown 写出可直接放映的幻灯片下一篇GHelper 使用入门10MB 单文件 exe5 分钟接管华硕笔记本性能模式创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考