本文介绍如下内容:
APIM中的三种版本控制scheme;
案例:在APIM中配置API的版本控制;
案例:使用postman/Azure Portal/Developer Portal 测试带版本号的API;
视频介绍:
图文介绍:
APIM中的三种版本控制scheme;
当后端API出现大版本变更时,需要对APIM发布的API增加版本管理。在API组上点击“...”按钮,点击“add version”即可添加新的API版本。
API 版本管理有三种版本结构,分别为 Path, Query String 和 Header,
其中Path 和 Query String 体现在URL中,通过请求的url,我们能清楚的看到调用的是哪个版本的api,
Header 的方式则在URL中“隐藏了”调用的API版本信息。
对于这三种方式,您可以选择任意一种,也建议一旦选择了某一种,再接下来的V2/V3及后续的版本中,使用同样的版本结构。
第一种方案:Path,
假设增加的版本为v1,则Version Identifier 设置为v1,
使用该方案,需要在URL中增加/v1,如下图所示:
第二种方案:Header,
假设增加的版本为v1,则Version Identifier 设置为v1,同时需要设定Version header,该值为自定义的key,可以使用例如“api-version”,“api-v”等等字段,
在使用时,需要在header中增加相应的key 和value(version identifier)。
第三种方案:Query string,
假设增加的版本为v1,则Version Identifier 设置为v1,同时需要设定Version query parameter,该值为自定义的key,可以使用例如“api-version”,“api-v”等等字段,
在使用时,需要在url中增加相应的查询参数,格式为 ?version query parameter=version identifier,如下图所示:?api-version=v1
版本增加后,APIM会自动为我们创建一个Original的API版本,在用户未显示指定调用的API版本时,默认使用该版本,以保证用户之前的业务逻辑正常运行。
案例:在APIM中配置API的版本控制;
本例使用了Header方式,为了便于演示header 中 version信息对于后端API的调用,我们在Outbound processing中增加了Set headers policy,
对于 Original ,我们增加了 api-version =original的header;对于V1,我们增加了api-version=v1的header;
这样设置之后,如果用户在request header中设置api-version=v1,则我们会在response 的header中得到api-version=v1的值,如果用户没有设置request中的api-version,则response的header中应该返回api-version=original。
对于 Original ,我们增加了 api-version =original的header;
对于V1,我们增加了api-version=v1的header;
案例:使用postman/Azure Portal/Developer Portal 测试带版本号的API;
在postman中调用 apim的api,不加api-version信息,则默认调用的是original版本:
在postman中调用 apim的api-version=v1的api,则默认调用的是v1版本:
如果版本号标定错误,如下图故意标定了V3的版本,但实际上APIM中并没有V3的版本,则会返回404错误。
在Azure Portal中测试,调用V1,默认在header中增加了api-version=v1的设置,
则在结果中返回的是由V1的后端API返回的结果:
在开发人员门户测试APIM的版本功能:
调用V1 版本的API:
developer portal的测试页面自动在header 中增加了 api-version :