创建Azure Cosmos DB容器时offerThroughput作用与配置差异

这几个写法的差异本质是SDK多版本迭代留下的参数别名、吞吐量模式区分、参数挂载位置不同带来的行为区别，逐个对应说明：

• 写法A：仅传入容器id，不传任何吞吐量相关参数
  这种写法不会主动指定容器级专属吞吐量，会走两层默认逻辑：如果所在数据库开启了共享吞吐量，新建容器会直接继承数据库的共享吞吐量配额；如果数据库没有配置共享吞吐量，SDK不会向服务端传递任何吞吐量参数，由服务端兜底创建手动吞吐量模式、400RU/s的专属吞吐量容器，这个默认值是服务端侧规则，不是SDK设置的。
• 写法B：容器定义对象中传入throughput: 400
  这是v3版SDK早期版本支持的简写参数，效果是创建手动吞吐量模式、固定400RU/s的专属吞吐量容器，不开启自动扩缩容。这个参数目前是兼容保留的别名，手动吞吐量场景下和写法D的最终效果完全一致。
• 写法C：容器定义对象中传入maxThroughput: 400
  这个参数专门用于创建自动扩缩容模式的容器，传入的400是自动扩缩容的RU上限，服务端会自动将扩缩容下限设为最大值的10%也就是40RU/s，容器实际运行时吞吐量会根据负载在40-400RU/s区间自动弹性调整。注意传入值需要符合自动扩缩容的档位规则，1000RU以内最小步长是100RU，超过1000RU后按1000RU步长递增。
• 写法D：第二个请求选项参数中传入offerThroughput: 400
  这是当前正式版SDK推荐的标准手动吞吐量配置参数，挂载在createIfNotExists方法的第二个请求配置对象上，效果是创建手动吞吐量模式、固定400RU/s的专属吞吐量容器，和写法B的最终执行效果一致，区别是这个参数位置是SDK设计上的标准请求选项位，写法B是早期版本把请求配置揉进容器实体定义的兼容逻辑。

offerThroughput 参数的具体作用 #

这个参数是Cosmos DB底层Offer（吞吐量配额）资源模型在SDK中的透传字段，作用非常明确：创建容器或者数据库时，指定手动吞吐量模式下的固定RU配额。
使用时需要注意几个规则：

• 仅适用于手动吞吐量场景，传入值必须符合手动吞吐量档位要求：最低400RU，400-10000RU区间步长为100RU，超过10000RU后步长为1000RU
• 如果同时在容器定义里传了throughput、又在请求选项里传了offerThroughput，SDK会优先取请求选项里的offerThroughput值
• 这个参数不能和自动扩缩容相关参数（比如maxThroughput、autoscaleMaxThroughput）同时传入，否则会直接触发SDK侧的参数校验错误

踩坑提示：createIfNotExists 方法只有在检测到容器不存在、实际触发创建流程时，才会应用传入的吞吐量配置。如果容器已经存在，无论你传入什么吞吐量参数，都不会修改现有容器的吞吐量配置。

内容的提问来源于stack exchange，提问作者Paul Smith