F5 api介面開發實戰手冊（二）

肉餅子蒸蛋發表於2021-06-04
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()

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

相關文章