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有兩種獲取方式

1. 通過requests_params={'params': {'expandSubcollections': 'true'}}參數從Collection或者Resource中直接獲取，可參見本頁1.5和2.1節。
2. 通過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，那么我只需要知道：

1. server所屬於什么對象？Collection和Resource
2. 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()

具體不再贅述。對於一些常見的用法，更詳細的說明會在下一篇文章中介紹。