F5 api接口开发实战手册（二）

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

具有两种主要方法，查询和删除。主要介绍查询方法，如下所示为查询条件：

参数	说明
$filter	过滤条件，指定parttion后可以过滤对应的结果，目前只支持parttion
$select	指定结果中返回的属性，可以去掉不需要的属性，节省开销
$top	一般与$skip一起使用，指定想要获取的数量
$skip	一般与$top一起使用，指定想要跳过的条目数量
expandSubcollections	指定此字段为true后，将获取Resource下的Subcollections，否则仅返回一个链接。默认为否
option	此查询如果在tmsh命令行中可以设置选项，那么也可以设置于此
ver	指定rest api的版本，不指定则使用当前F5的默认版本。此选项可以避免F5升级导致api版本变动引起接口不可用

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对象

如果所获取的值超过了Resource的数量，则返回结果会少于$top中的值，最少为空列表

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'})

option选项所使用的通配符，与tmsh中用到的一致。

delete_collection使用另一种字典风格的参数结构会报错

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的详细信息

不指定partition，则默认为Common，下同

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()

注意，这与1.7删除Collection不是一回事，他们所导致的结果可能一样，但是这两种删除方式不同。

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的get_collection()方法与Collection相比，在requests_params中只支持$top，$skip，$select三种传参，其他方法本人没有试出来，可能并不起效。

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()

具体不再赘述。对于一些常见的用法，更详细的说明会在下一篇文章中介绍。