F5 rest api 各对象使用方式详解
本篇文章介绍rest api接口下Collection、Resource、Subcollections、SubResource的各种使用方法。如果您不了解这是什么，请查看上一篇F5 api接口开发实战（一）的最后一部分。
1、Collection
Collection是Resource的一个集合，比如ltm上的所有pool就是一个Collection。以ltm pools的Collection为例，其api深度为
poolCollection = bigipRest.tm.ltm.pools
具有两种主要方法，查询和删除。主要介绍查询方法，如下所示为查询条件：
1.1 获取全部Resource的全部属性
不指定任何参数，则默认获取全部
# 获取所有pool
pools = bigipRest.tm.ltm.pools.get_collection()
# 返回一个列表，其中每一项都是pool的Resource对象
debug上述代码，查看pool的Resource对象后可以发现它具有非常多的属性，这些属性都可以在1.2的方法中用于指定获取字段
1.2 获取指定属性
上述获取的pool Resource对象包含了全部属性，大部分是我们 不需要的，那么我们可以筛选有用字段，传入指定参数即可。
# 获取所有pool，但只需要包含name、loadBalancingMode和partition这三个参数
pools = bigipRest.tm.ltm.pools.get_collection(requests_params={'params': '$select=name,loadBalancingMode,partition'})
# 返回一个列表，其中每一项都是一个字典，只包含这三个键值对
查看上述结果可以发现，返回结果不再是Resource对象，而是一个只包含上述指定三个关键字的键值对，节省了网络和F5设备开销。
1.3 筛选返回结果
当我们想指定某个partition的结果时，可以使用过滤条件。
# 获取partition等于part1的所有pool
pools = bigipRest.tm.ltm.pools.get_collection(requests_params={'params': '$filter=partition+eq+part1'})
1.4 过滤结果条目数量
还可以对返回结果进行分页，指定top和skip字段
# 跳过前面5个，从第6个开始获取8个对象
pools = bigipRest.tm.ltm.pools.get_collection(requests_params={'params': '$top=8&$skip=5'})
# 返回一个列表，其中包含8个Resource对象
1.5 获取Resource下的Subcollections
debug上述代码，会发现返回的Resource对象中，只有指向下一层Subcollections的链接，而没有详细信息。比如，当我们使用1.2的方法获取全部pool时，返回的结果中每个pool对象只包含pool的属性，比如monitor、loadBalancingMode等，并不包含members的信息。此时我们可以指定expandSubcollections参数为true。
# 获取所有pool下members的信息
pools = bigipRest.tm.ltm.pools.get_collection(requests_params={'params': {'expandSubcollections': 'true'}})
# 返回结果中membersReference下多了一个items属性，其中包含了members的详细信息
1.6 组合查询
以上所有字段都可以组合查询，使用&连接不同参数即可。同时，也可以使用另一种风格的参数结构，如下所示
requests_params={'params': {'$select': 'name,loadBalancingMode,partition', '$top': 3,'$skip':5}}
1.7 删除Collection
一般情况下，请不要使用删除方法删除Collection，这可能会清除F5上的全部某项配置，是很危险的行为。使用删除时，简单地调用是不行的，必须指定options选项。
# 删除以bb为结尾的pool
res = bigipRest.tm.ltm.pools.delete_collection(requests_params={'params': 'options=*bb'})
# 删除全部pool
res = bigipRest.tm.ltm.pools.delete_collection(requests_params={'params': 'options=*'})
# 删除名字叫poolname的pool
res = bigipRest.tm.ltm.pools.delete_collection(requests_params={'params': 'options=poolname'})
2、Resource
Resource是一个配置项，比如一个ltm pool，一个monitor，一个node等。以ltm pool的Resource为例，其api深度为
poolResource = bigipRest.tm.ltm.pools.pool
具有查询、更新、新增、删除等方法。
2.1 加载Resource对象
# 根据名字和partition加载指定对象
pool = bigipRest.tm.ltm.pools.pool.load(name='poolname', partition='Common')
# 返回结果是一个pool的Resource对象
本方法同样支持expandSubcollections参数，如下
# 指定expandSubcollections加载指定对象
pool = bigipRest.tm.ltm.pools.pool.load(name='poolname', partition='Common', requests_params={'params': {'expandSubcollections': 'true'}})
# 返回Resource对象中的items属性包含members的详细信息
2.2 判断Resource存在性
# 根据名字和partition判断指定Resource是否存在
res = bigipRest.tm.ltm.pools.pool.exists(name='poolname', partition='Common')
# 返回结果是布尔值
2.3 新增Resource
# 指定名字和partition，创建Resource对象
pool = bigipRest.tm.ltm.pools.pool.create(name='poolname', partition='Common')
# 返回创建完毕的Resource对象
2.4 更新Resource
# 加载pool
pool = bigipRest.tm.ltm.pools.pool.load(name='poolname', partition='Common')
# 调用update方法修改负载均衡方式为最小连接数
pool.loadBalancingMode = 'least-connections-member'
pool.update()
# 也可以直接一步更新
pool.update(loadBalancingMode='least-connections-member')
2.5 删除Resource
# 加载pool
pool = bigipRest.tm.ltm.pools.pool.load(name='poolname', partition='Common')
# 调用delete方法删除
pool.delete()
2.6 刷新Resource
当加载一个Resource时，如果处于某种原因，这个Resource的配置在另外的地方被修改了（比如，通过另一个对象，通过web页面，通过tmsh命令行等），再获取这个Resource对象的配置就会不准。此时使用刷新方法即可解决。
# 加载pool
pool = bigipRest.tm.ltm.pools.pool.load(name='poolname', partition='Common')
print(pool.loadBalancingMode) #发现此时负载均衡方式为'least-connections-member'
# 在web页面上把负载均衡修改为round-robin
print(pool.loadBalancingMode) #依然为'least-connections-member'
# 刷新Resource对象
pool.refresh()
print(pool.loadBalancingMode) #变为'round-robin'，正确
3、Subcollections
Subcollections是属于Resource下的配置。比如某个ltm pool下的一组members就是Subcollections。
Subcollections有两种获取方式
- 通过
requests_params={'params': {'expandSubcollections': 'true'}}参数从Collection或者Resource中直接获取，可参见本页1.5和2.1节。 - 通过Resource对象获取
3.1 通过Resource对象获取Subcollections
# 加载pool
pool = bigipRest.tm.ltm.pools.pool.load(name='poolname', partition='Common')
# 从pool中获取members
members = pool.members_s.get_collection()
# 返回一个列表，其中每一项都是member的SubResource对象
Subcollections没有delete_collection()方法。
4、SubResource
SubResource是Subcollections下的单个资源，以ltm pool为例，SubResource即pool下的member。SubResource支持的方法与Resource类似，但首先需要先获取Resource。
# 加载pool
pool = bigipRest.tm.ltm.pools.pool.load(name='poolname', partition='Common')
# 后续的操作都在pool上进行
4.1 加载SubResource
# 根据名字和partition加载指定SubResource对象
member = pool.members_s.members.load(name='1.3.6.5:81', partition='Common')
# 返回member的SubResource对象
4.2 判断SubResource存在性
# 根据名字和partition判断member是否存在
res = pool.members_s.members.exists(name='1.3.6.15:81', partition='Common')
# 返回结果是布尔值
4.3 新增SubResource
# 新增members
pool.members_s.members.create(name='1.2.3.4:80', partition='Common')
# 返回新增member的SubResource对象
4.4 更新SubResource
# 加载member
member = pool.members_s.members.load(name='1.3.6.5:81', partition='Common')
# 修改member的属性
member.priorityGroup = 2
member.update()
4.5 删除SubResource
# 加载member
member = pool.members_s.members.load(name='1.3.6.5:81', partition='Common')
# 调用delete方法删除
pool.delete()
4.6 刷新SubResource
# 加载member
member = pool.members_s.members.load(name='1.3.6.5:81', partition='Common')
print(member.ratio) #发现此时比率为1
# 在web页面上把ratio修改为2
print(member.ratio) #依然为1
# 刷新member对象
member.refresh()
print(member.ratio) #变为2，正确
以上可以看出，SubResource的操作基本与Resource一致。
5、举一反三
上述通过以ltm pool 为例，说明了Collection、Resource、Subcollections、SubResource的各种用法。实际应用中，了解了上述的api结构，需要知道我当前配置资源的api深度和所属的对象类型，即可举一反三地了解到配置方法。
比如，我目前需要配置gtm的server，那么我只需要知道：
- server所属于什么对象？Collection和Resource
- server的api深度是多少？
bigipRest.tm.gtm.servers和bigipRest.tm.gtm.servers.server
那么，很简单，我对server做查询、更新、删除、新增操作时，就可以调用上面介绍的方法，比如：
# 获取全部server
servers = bigipRest.tm.gtm.servers.get_collection()
# 加载server对象
server = bigipRest.tm.gtm.servers.server.load(name='server1', partition='Common')
# 删除server对象
server.delete()
具体不再赘述。对于一些常见的用法，更详细的说明会在下一篇文章中介绍。