IBM Cloud命令行使用指南(Call API篇)

这里将介绍使用IBM Cloud的命令行调用IBM IaaS平台的API来对IBM Cloud平台的基础架构进行日常的管理，查询和维护。

 

首先，在大家能够使用命令行Call API之前，需要先设置好自己的命令行(CLI)环境。可以是自己笔记本上的Windows或Mac OS，也可以是专门在云上开的用于管理的Linux虚拟机环境，笔者就是在IBM云上开了这样一个2C4G的虚拟机，机器开在IBM达拉斯机房，从国内远程登录到达拉斯机房的速度和网络稳定性还算比较满意。读者有需要的也可以考虑在IBM香港，韩国或日本的机房开这样一个虚拟机，国内连接这几个地方的网络都还比较稳定（此处只谈SSH等远程登录方式），进入IBM环境之后，再连往IBM的其他数据中心的时候，我们可以走IBM内网连接，这样既能保证网络性能，又能保证网络质量。当然，我们的CLI的API Call其实也没用到内网，上面又扯多了。

 

有关如何设定CLI运行环境，请参考下面的URL：

https://blog.csdn.net/koolincn/article/details/104492312

 

Section 1 – 获取机器列表信息

 

我们先来看看直接命令行获取账号下物理机信息的命令以及输出：

slcli hardware list

这个命令是获取的所有物理机信息，如需要过滤，则需要通过Linux Shell的过滤功能来实现。 获取虚拟机的命令如下： slcli virtual list

 

我们再来看一下使用API获取账号下物理机信息的命令与输出：

命令：slcli call-api Account getHardware --filter 'hardware.datacenter.name IN fra05' --mask=id,hostname,primaryIpAddress,primaryBackendIpAddress,datacenter.name

我们可以看到，调用API可以有更多的选择去输出想要的字段，通过对结果添加mask ②来实现。通过添加filter ①（过滤）实现对整个输出结果集的筛选，我们这里的筛选条件是FRA05机房，与上面直接命令行的过滤一致，但是直接命令行的筛选会把含有fra05字串的所有记录都过滤出来，没有Call API的filter来得精准。

 

大家或许也注意到了，API调用的输出中，红框圈出③的关于数据中心名词一列，其格式似乎与其他列不一致，这是由于我们mask中用到的datacenter.name这个字段中的datacenter他自己本身包含有多个Local的字段，我们现在只是让其输出了其中的一个，所以在格式上，他还是保留了需要输出自己其他字段的格式。我们可以看下我们让他输出其他字段时的效果。

命令：slcli call-api Account getHardware --filter 'hardware.datacenter.name IN fra05' --mask=id,hostname,primaryIpAddress,primaryBackendIpAddress,datacenter[id,name,longName]

这里我们输出了datacenter的其他字段。有读者应该也注意到了，我在前后两次使用mask的时候的写法稍有出入（datacenter.name和datacenter[id,name,longName]），针对于mask这一选项，这两种写法都可以支持。  但是对于fillter项，只支持 . (点) 的形式，并不支持[]形式(当然，这个限制只在命令行的API CALL中存在，如果你是使用其他编程语言进行调用的话，不管是mask或filter，这两种格式都支持)。

 

Section 2 – API中的mask和filter的用法和解释

 

在继续更多的例子之前，先来简单解释一下上面用到的filter和mask之间的区别和用法：

filter用于对记录集进行过滤和筛选，这相当于我们使用EXCEL表格时候的针对记录的筛选功能。而mask是对已经筛选过的记录集要显示的字段进行选取，通过mask来显示我们需要的列信息，不必要显示其他不需要的。

 

看到这里，很多读者也许会问，你所调用的API的方法列表从哪里获取，这些字段名字的信息从哪里可以查询，以及字段的层级如何区分等等，下面就来先讲解一下如何在filter和mask里面设定对应的字段名字。

有关IBM云平台的基础架构的所有API信息，可以从下面这个URL获取：

https://sldn.softlayer.com/reference/softlayerapi/

 

IBM云基础架构有提供非常完整的API服务，分别针对有不同的Level，每个服务下面又都有提供多种方法供调用，来满足用户对整个基础架构的管理和维护的需求。

我们可以看到上图左边的部分，有各个层级的服务提供，里面的服务其实都可以直接初始化，然后调用里面对应的方法，服务其实不分层级（看上去Account服务下面还有Account_Address, Account_Address_Type等等）。右侧的是分别对应不同服务的各种数据类型。不同服务的数据类型是在我们调用服务之后可以进行过滤或返回的数据，可以对这些数据进行前面讲到的filter和mask操作。

我们先来看一下mask怎么设定，就拿之前我们调用的Account服务里面的getHardware方法来说，

他返回值是Hardware数据类型，我们可以点击”SoftLayer_Hardware[]”，可以查询都有哪些返回值。

每一个方法的返回值基本都有“Local”(本地)，和”Relational”(关联)形式. 通常“Local”类型的数据类型没有子项，而“Relational“类型一般情况下会有子项，类似我们前面针对getHardware方法的返回结果进行mast，mask里面的id,hostname等都是本地类型，而PrimaryIpAddress,primaryBackendIpAddress,datacenter[id,name,longName]等都是“Relational”类型，里面的PrimaryIpAddress,primaryBackendIpAddress没有子项，而datacenter包含更多子项目，datacenter是Location服务下面的数据类型。

 

有了这个理解，我们可以设定mask，返回更多信息，如查看对应机器所在的数据中心PoD（PoD即数据中心里面的机房，一个数据中心里面通常会有多个机房（PoD），每个PoD一般情况下由4000~5000台物理机组成），参考下面的mask设置：

--mask=id,hostname,primaryIpAddress,primaryBackendIpAddress,backendRouters[hostname],frontendRouters[hostname]

返回结果如下：

其中的fcr01a/fcr01b说明此物理机器连接的是PoD的前端路由（front customer router）（a和b互为备份）。bcr01a/bcr01b则是后端路由，负责内网通讯。

 

再来看一下filter的设定。filter的设定的最高层级是所调用服务的数据类型，而不是调用服务里面方法作为最高层级。如上面的hardware.datacenter.name，这里，hardware是我们调用的Account这个service的数据类型：

然后再进入到hardware所在的Hardware[]数据类型下指定需要进行filter的子项，这一点是filter于mask不同的地方。

 

在我们需要查看某个服务里面的某个方法是否支持filter或mask，以及是否需要参数时候，我们可以点击进入该方法的使用页面查看：

上面这个方法，调用时需要进行用户验证，支持mask，但不支持filter操作。

 

又如：

该方法支持filter和mask，且无需其他额外参数。

 

Section – 3 更多信息查询样例

 

批量获取账号下，指定机房的物理机器的后端网络信息，帮助我们更清晰的了解物理机在数据中心所在的位置，以便于更好的设计应用的各个组件的部署，来提高应用的性能和高可用性。（当然这些信息在Portal上也能够查询到，但是只能单个机器点击进入详细页面才能拿到，如果机器数量较多的话，Portal上的操作就显得有些繁琐和不便了，在这里，再向大家推荐一篇文章，讲诉IBM机房布局的架构，以及针对不同类型的应用，如何合理部署不同 组件到IBM机房的不同PoD，以及RACK：

https://blog.csdn.net/sheisqueen1/article/details/106943361）

命令：slcli  call-api Account getHardware --filter 'hardware.datacenter.name=fra05' --mask=mask[id,hostname,networkComponents[name,networkHardware[hostname]],operatingSystem[passwords[password],softwareLicense[softwareDescription[name]]]]

 

根据给定ip地址查询物理机器，显示物理机器的详细信息：

命令：slcli call-api Hardware_Server findByIpAddress 10.123.220.39

也可以加上mask，如：

slcli call-api Hardware_Server findByIpAddress 10.123.220.39 --mask=hostname,id,networkComponents[name,networkHardware[hostname]]

 

需要创建物理机，使用 Hardware服务下面的getCreateObjectOptions方法获取创建对象时可输入的选项，然后使用Hardware_Server下面的createObject方法可以创建物理机器，当然，由于物理机器里面涉及的硬件组件种类和选项非常繁多，所以需要输入的参数相对还是比较复杂的。

 

有时候，我们直接使用命令行方式进行一些操作不仅没有调用API方式那样繁琐，反而来得更为简单。像这种情况，我们可以将两者结合着使用。就比如我们需要创建对应机器的问题工单时，使用命令行直接进行操作比调用API的方式更加简单。命令如下：

slcli ticket create --title 'Test Ticket' --subject-id 1021 --body 'Hi, we have server issues' --hardware 1855127 --priority 4

 

但是上面这条命令里面需要输入的subject id，我们有时候不是非常清除，不同的硬件/网络问题，都对应不同的subject id，如果subject id没有指定清楚，会影响后端工程师分配不同人员，影响工单处理的时间和效率。但是我们不清楚id号，这时我们可以调用Ticket_Subject服务下面的getAllObjects方法来获取所有的subject id：

 

Section – 4 意外的收获

 

前一段时间，在看API的时候，发现了一个在新的用户Portal上被移除的一项能力。查看不同数据中心接入的网络运营商，以及各个运营商的带宽，并且可以查询到各个机房的物理地点，这个或许对一些用户更清楚的了解IBM网络带宽的能力，以及如果要与IBM云进行专线连接的话，可以看当地城市的IBM机房所在的地址是否合适。

下面就来看一下如何获取这些信息，我们调用的是Network_Backbone服务下面的getBackbonesForLocationName这个方法。

命令：

slcli call-api Network_Backbone getBackbonesForLocationName dal13 --mask=name,capacity,capacityUnits,type,location[longName,locationAddress[address1,city,description]]

后面的mask我们可以根据自己的需要看是否调整

细心的你可能已经注意到了，我搜索的是dal13这个数据中心的运营商带宽信息，为什么里面显示的是dal04的信息，IBM通常将负责和运营商网络接入的数据中心称之为PoP（网络接驳点），PoP节点通常只负责网络的接入，机房里面没有实体机供应给客户，而有实体机提供的数据中心的网络是连接到PoP后再与互联网通讯，有时候实体机数据中心同时也有PoP能力（一些比较小的数据中心），而这里，dal13的网络出口是接入到dal04，然后再出去的。所以我们在查看dal13的时候，显示的是dal04中的运营商信息。

 

上面这个命令需要输入参数，数据中心的短名称。所以，如果有些时候，我们不太清楚哪个数据中心的短名称是什么，可以通过调用Location服务里面的getDatacenters方法来查看。

命令：

slcli call-api Location getDatacenters

 

最后，我要说明一下，在命令行中调用API，虽然能够实现一下较为复杂的能力，但是由于他有一定的局限性，比如，在filter中，不支持比较复杂的过滤条件，如起始日期和终止日期，以及一些更为复杂的判断等等（如下图），大家如要实现完整的功能，还得使用程序进行API调用。

 

到此，相信大家对IBM基础架构平台的API，以及命令行下调用API应该有了一个初步的了解，这篇文章只是一个抛砖引玉，大家如果对IBM Cloud平台的API感兴趣的话，可以参考API网站： https://sldn.softlayer.com/python/ ，在那里你将找到更多程序调用API的样例。同时也欢迎广大读者朋友一起沟通交流。