###### tags: `postman` `api`

# 使用 VMware HOL 線上實驗室提供的 Postman 做 API 實驗

[toc]

簡單來說，VMware HOL 線上實驗室提供了完整的環境，讓一般沒有實際（測試）環境的使用者，可以透過此一平台進行可實際操作及演練流程的架構及環境，另一個好處就是不用擔心把環境搞壞！

以下簡單的實驗目的，將會利用線上實驗室提供的虛擬機器及系統安裝的 **Postman** 軟體，進行以下實驗項目測試：
1. **Postman 請求 vSphere API 操作**
2. **取得網路交換器或連接埠組態資訊**
3. **取得虛擬機器組態資訊（VM ID, NIC 等）**
4. **變更單台虛擬機器網路設定**
5. **[進階] 變更多台虛擬機器網路設定（使用 JSON 搭配 Collection Runner）**

## 實驗需求

- VMware HOL 線上實驗室登入帳號（**免費註冊**）
- 連線 **HOL-2225-02-NET** 線上實驗室

## 實驗準備
本次實驗僅使用 **Region A** 環境資源。

### 登入實驗桌面
如果可以，請啟用右上方 **切換全螢幕** 功能。

實驗室環境桌面。

### 環境連線資訊
開啟桌面文件 **`README.txt`**，內容提供實驗所需連線帳戶資訊。本次實驗僅需使用 **Region A vCenter Server**。
:::info
- HOL-2225 系列的實驗室運行的環境相同。
- 應用此一實驗環境，可練習 NSX V2T 移轉程序（DFW-Only）。
:::

### 開啟應用程式
開啟以下應用程式:
- Google Chrome
- Postman

## 實驗設定

### 連線 vCSA
點選瀏覽器上方書籤列 **`Region A`** > **`vcsa-01a Web Client`** 登入 vCSA。


#### 選擇目標虛擬機器
從 Web Client 先選擇虛擬機器 **`web-02a`**，作為實驗對象。


以上資訊可以知道，目前 **`web-02a`** 連接於 **`Web-LS`** 網路，這個網路屬於 NSX-T 的**區段（Segment）**，並且是採用 VDS 7.0.2 版本，使得 NSX-T 可以應用 vSphere 原生的 VDS 來建立網路。

#### vCSA Web Client（vcsa-01a）
**Menu** > **Networking** > **RegionA01-0vDS** - **Web-LS**

選擇 **Ports** 選項，並選擇 **`web-02a`**，可以了解目前該虛擬機器連線資訊。

選擇 **VMs** 選項，目前 **`Web-LS`** 網路包含 2 組虛擬機器：**`web-01a`**, **`web-02a`**。

#### NSX-T Manager（nsxmgr-01a）
連線 **NSX-T Manager**，點選 **Networking** > **Connectivity** - **Segments** - **Web-LS**。

**System** > **Configuration** - **Fabric** > **Transport Zones** - **Overlay-TZ**


**System** > **Configuration** - **Fabric** > **Nodes** > **Host Transport Nodes**
可知 **`RegionA01-COMP01`** 套用 **`Profile: COMP01-TNP`**。

點選其中一台 Node 可檢視相關資訊。

**System** > **Configuration** - **Fabric** > **Profiles** > **Transport Node Profiles** - **COMP01-TNP**

點選這個 **Profile - COMP01-TNP** 檢視內容。
從這個組態可以知道使用 **VDS 類型**，而非 N-VDS 類型，這與在 vCSA Web Client 檢視的資訊相符。以下是該 Profile 詳細組態。
<img src='https://i.imgur.com/aJF4O5y.png' width=480>
<img src='https://i.imgur.com/oBdSpQl.png' width=480>

:::info
HOL 線上實驗室的確是技術學習養成的好地方！
:::

### Postman 環境設定
接著從開啟的 Postman 應用程式，透過之前的基礎學習，完成以下請求的建立，並存放於**集合（Collection）: 00-Web-02a Test LAB**。


:::info
以下將針對各請求設定作重點標記，相信先前的 Postman 基礎學習，應可達到一定的成果。
:::

#### Collection: Web-02a Test LAB
:::success
**Authorization**
- Type: Basic Auth
- Username: [e-mail]
- Password: VMware1!
:::

:::success
**Variables**
| Variable | Value |
| --- | --- |
| vcsa_url | https://vcsa-01a.corp.local |
:::

#### Create vCSA session
:::success
**URL** **`POST`** `{{vcsa_url}}/api/session`
:::
:::success
**Authorization**
- Type: Inherit auth from parent
:::

:::success
**Tests 腳本**
- 將請求回應的結果儲存成集合變數 **`vcsa_session`**。
- 驗證狀態碼 `201`。
:::


#### Get Web-LS Object ID
:::danger
**注意**
- 當初並未注意到 HOL 裡面使用的 API 版本，應該是 **7.0 U2**，在最新的 API 版本 **7.0 U3**，部份的 URL 有做變動，這也會影響回應的資料結構，所以也需要將撰寫的腳本檔做些微的修正。
- 以下內容將不逐一進行修正。
- 請參考 [補充說明](#補充說明)。
:::

:::success
**URL** **`GET`** `{{vcsa_url}}/rest/vcneter/network?filter.name=Web-LS`
:::
:::success
**Params** 輸入以上 URL，Postman 將自動代入。
:::

:::success
**Authorization**
- Type: **API Key**
- 組態內容如下，Postman 會自動代入 **Headers**。

| Key | Value | Add to |
| --- | --- | --- |
| vmware-api-session-id | {{vcsa_session}} | Header |
:::

:::success
**Headers** 完成前項設定，將會自動代入。
:::

:::success
**Tests 腳本**
- 將請求回應的結果儲存成集合變數 **`web_ls_objectID`**。
- 驗證狀態碼 `200`
:::

:::danger
**注意**
- 因為 API 版本不同也會影響回應請求的資料結構。所以會影響撰寫的腳本檔內容。
- 以下內容將不逐一進行修正。
- 請參考 [補充說明](#補充說明)。
:::

#### Get VM-vDS Object ID
:::success
**URL** **`GET`** `{{vcsa_url}}/rest/vcneter/network?filter.name=VM-RegionA01-vDS`
:::

:::success
**Params** 輸入以上 URL，Postman 將自動代入。
:::

:::success
**Authorization** 與前一個請求相同
:::

:::success
**Headers** 完成前項設定，將會自動代入。
:::

:::success
**Tests 腳本**
- 將請求回應的結果儲存成集合變數 **`vmVds_objectID`**。
- 驗證狀態碼 `200`。
:::

#### Get Web-02a ID
:::success
**URL** **`GET`** `{{vcsa_url}}/rest/vcneter/vm?name=web-02a`
:::

:::success
**Params** 輸入以上 URL，Postman 將自動代入。
:::


:::success
**Authorization** 與前一個請求相同
:::

:::success
**Headers** 完成前項設定，將會自動代入。
:::

:::success
**Tests 腳本**
- 將請求回應的結果儲存成集合變數 **`web02_vmID`**。
- 驗證狀態碼 `200`。
:::

#### Get Web-02a Hardware NIC
:::success
**URL** **`GET`** `{{vcsa_url}}/rest/vcneter/vm/{{web02_vmID}}/hardware/ethernet`
:::

:::success
**Authorization** 與前一個請求相同
:::

:::success
**Headers** 完成前項設定，將會自動代入。
:::

:::success
**Tests 腳本**
- 將請求回應的結果儲存成集合變數 **`web02_hwNIC`**。
- 驗證狀態碼 `200`。
:::

#### Get Web-02a NIC Info
:::success
**URL** **`GET`** `{{vcsa_url}}/rest/vcneter/vm/{{web02_vmID}}/hardware/ethernet/{{web02_hwNIC}}`
:::

:::success
**Authorization** 與前一個請求相同
:::

:::success
**Headers** 完成前項設定，將會自動代入。
:::

:::success
**Tests 腳本**
- 將請求回應的結果儲存成集合變數 **`web02_hwNIC_distributedPort`**。因為 `web-02a` 網卡是連接至 VDS 上，所以要指定 **`distributed_port`**。
- 驗證狀態碼 `200`。
:::

#### Attach Web-02a VM to VM-vDS
:::success
**URL** **`PATCH`** `{{vcsa_url}}/rest/vcneter/vm/{{web02_vmID}}/hardware/ethernet/{{web02_hwNIC}}`
:::

:::success
**Authorization** 與前一個請求相同
:::

:::success
**Headers** 完成前項設定，將會自動代入。
:::

:::success
**Body**
- Type: RAW
- Format: JSON
- 修改組態 **`network`**:**`{{vmVds_objectID}}`**。
:::

:::success
**Tests 腳本**
- 驗證狀態碼 `200`。
:::

:::warning
**注意** 完成以上每個設定，請務必確認 **儲存（Save）** 組態。
:::

## 實驗測試
完成上述設定組態，接著要進行相關測試，以便驗證建立的 API 的請求是否正確。採用兩種方式進行測試驗證：
1. [**逐一執行請求**](https://hackmd.io/L8tct4Y2SyOmhyJZv8EjvA?both#%E9%80%90%E4%B8%80%E5%9F%B7%E8%A1%8C%E8%AB%8B%E6%B1%82): 依序執行請求，並確認請求回應及集合變數產生的正確性。
2. [**使用 Runner 執行**](https://hackmd.io/L8tct4Y2SyOmhyJZv8EjvA?both#%E4%BD%BF%E7%94%A8-Runner-%E5%9F%B7%E8%A1%8C): **Collection Runner** 可用指定的順序執行請求集。**Collection Runner** 也將記錄請求的測試結果，建立的腳本可在各請求之間傳遞數據及更改請求工作流程。集合運行可進行自動化 API 測試使用。

> 後續也將使用 **Runner** 使用 JSON 建立多筆資料來執行相同請求。

### 逐一執行請求
執行請求前，先確認所建立的集合變數只有 **`vcsa_url`**。接著依序執行請求，並確認回應資訊。

**`Create vCSA session` 執行結果**
- 取得 `Session ID`。

- 狀態碼正確。
<img src='https://i.imgur.com/WFi6XyI.png' width=280>

- 產生集合變數 `vcsa_session`。

**`Get Web-LS Object ID` 執行結果**
- 取得 `Web-LS` 資訊。

- 狀態碼正確。
<img src='https://i.imgur.com/zuMtZ3u.png' width=280>

- 產生集合變數 `web_ls_objectID`。

**`Get VM-vDS Object ID` 執行結果**
- 取得 `VM-RegionA01-vDS` 資訊。

- 狀態碼正確。
<img src='https://i.imgur.com/y36I4An.png' width=280>

- 產生集合變數 `vmVds_objectID`。

**`Get Web-02a ID` 執行結果**
- 取得 `web-02a` 資訊。

- 狀態碼正確。
<img src='https://i.imgur.com/IRYxjTY.png' width=280>

- 產生集合變數 `web02_vmID`。

**`Get Web-02a Hardware NIC 執行結果**
- 取得 `web-02a` NIC 資訊。

- 狀態碼正確。
<img src='https://i.imgur.com/omr8VYM.png' width=280>

- 產生集合變數 `web02_hwNIC`。

**`Get Web-02a NIC Info` 執行結果**
- 取得 `web-02a` NIC 連接資訊。

- 狀態碼正確。
<img src='https://i.imgur.com/bl1pMyu.png' width=280>

- 產生集合變數 `web02_hwNIC_distributedPort`。

**`Attach Web-02a VM to VM-vDS` 執行結果**
- 請求回應正常，並無任何錯誤訊息。

- 狀態碼正確。
<img src='https://i.imgur.com/lp2zMfi.png' width=280>

虛擬機器 `Web-02a` 確認網路已經變更至 `VM-RegionA01-vDS` 網路。

從 `VM-RegionA01-vDS` 檢視虛擬機器 `web-02a`。
<img src='https://i.imgur.com/lCM505V.png' width=480>

### 使用 Runner 執行
選擇集合 **`00-WEb-02a Test LAB`**，點擊右上方 **Run** 執行 **Runner**。

整個集合中的請求會放至 **RUN ORDER** 清單，可以勾選或取消要執行的請求，並可重新編輯執行順序。勾選 **Save responses** 選項，會將請求回應保存並做後續查看，但有可能會影響效能。其他選項保持預設，點擊 **`Run 00-Web-02a Test LAB`** 執行集合集請求。


執行完成顯示結果，總共執行集合集請求 1 次（**Iterations: 1**）。依序顯示各個請求的執行狀態，皆為正確執行狀態。

可以在顯示畫面上，點選任一個執行的請求。
<img src='https://i.imgur.com/HxgaIfW.png' width=480>

點擊後會顯示所保存的回應資料項目。
<img src='https://i.imgur.com/1oJcnz7.png' width=560>

點擊有興趣的回應項目，可檢視其內容。
<img src='https://i.imgur.com/X7nMZfX.png' width=480>

:::info
透過以上的測試，使用 **Collection Runner** 可以很簡單並彈性地完成集合請求，進而完成 API 自動化或重複性測試。
:::

## 進階測試
根據以上 **Collection Runner** 測試的結果，是否可以利用同一個集合集請求的功能（變更虛擬機器網路組態），將多台虛擬機器達到相同目的？其實原本是想透過撰寫腳本來達成，結果發現以 Postman 應用來看，使用 **Collection Runner** 應該會是最簡便可達成目標的。

為了使用同一集合集請求來應用不同虛擬機器，需要使用**參數化寫法**來定義變數，並且能夠透過通用的**資料格式**來傳遞不同的內容（變數值）。

根據以上需求嘗試以下方式達成目標：
- 將原有集合集請求改用**參數**撰寫，而非先前使用指定的方式。
- 使用 **JSON 格式** 輸入不同參數值。
- 透過 **Collection Runner** 搭配上述調整進行。

### 複製原有集合集請求
將原有 **00-Web-02a Test LAB** 集合複製成一份新的集合 **01-Web VMs Test LAB**。

### 調整請求參數設定
為了簡化測試，先以 `web-01a` 和 `web-02a` 作為目標虛擬機器。將原有指定的名稱修改為參數寫法。

原有 **`Get Web-02a ID`** 的請求 URL 如下：
:::success
**`GET`** `{{vcsa_url}}/rest/vcneter/vm?name=web-02a`
:::

將其改寫成 **`Get Web VM ID`** 的請求 URL 如下：
:::warning
**`GET`** `{{vcsa_url}}/rest/vcneter/vm?name=`**{{web_vm}}**
:::

根據此一原則進行相關修改。
- **{{web_vm}}**

- Collection Variable: **web_vmID**

- **{{web_vmID}}**

- Collection Variable: **web_hwNIC**



- Collection Variable: **web_hwNIC_distributedPort**

### 建立 JSON 檔案
目前主要的物件對象是 **{{web_vm}}**，所以建立以下內容的 JSON 檔 **`web_vm.json`**。

其他需求請按此要領建立即可。

[
    { 
        "web_vm": "web-01a",
        "source_network": "Web-LS",
        "target_network": "VM-RegionA01-vDS"
    },
    {
        "web_vm": "web-02a",
        "source_network": "Web-LS",
        "target_network": "VM-RegionA01-vDS"        
    }
]

當然，使用 **CSV** 檔案也是可以的

web_vm, source_network, target_network
web-01a, Web-LS, VM-RegionA01-vDS
web-02a, Web-LS, VM-RegionA01-vDS
...

### 執行測試
#### 匯入 JSON
點選修改後的集合 **01-Web VMs Test LAB** 並執行 **Runner**。
點擊 **`Data`** - **`Select File`**。
<img src='https://i.imgur.com/REzYkxD.png' width=360>

選擇新增的 **`web_vm.json`** 檔案。
<img src='https://i.imgur.com/Bv47sIp.png' width=480>

Postman 匯入檔案後可以進行預覽，點擊 **`Preview`**。

預覽結果顯示，會使用 `web-01a` 和 `web-02a` 作為 **`web_vm`** 的參數值，會執行 2 次集合集請求。這樣的方式似乎符合最初需求的預期。

#### 確認虛擬機器網路
<img src='https://i.imgur.com/4MUlgyk.png' width=560>

#### 執行 Runner
一切就緒，執行！
<img src='https://i.imgur.com/M7yofr0.png' width=360>

執行結果顯示如下。可以觀察到請求總共執行了 2 次，回應請求也根據腳本進行測試驗證完成。


點擊 **`Run Summary`**，可以快速了解這次請求執行的概要狀態。


回到 Web Client 檢視 `web-01a` 和 `web-02a` 的網路連接狀態。
<img src='https://i.imgur.com/qtDgltY.png' width=640>

的確順利變更虛擬機器的網路。
<img src='https://i.imgur.com/eXWuaLM.png' width=640>

## 心得
**VMware HOL 線上實驗室**
- VMware HOL 線上實驗室的內容及環境極為豐富，對於一般用戶沒有資源建置環境，透過線上實驗室依舊可以學習到 VMware 知識。
- HOL 的實驗項目，針對 VMware 各產品也提供清楚的操作及文件說明，除了用於線上實驗之外，對於平日管理 VMware 環境也有幫助。
- 所需配備只要一台可上網的筆電和瀏覽器，操作環境也跟 VCAP 應試相同，熟悉這個操作模式，對於準備考試也很有助益。

**Postman**
- 提供一個極為簡便接觸 API 的應用平台。
- 只要了解簡單的 API 操作流程及技巧，應該就可以輕鬆應用及測試 API。
- 透過 Collection Runner 並搭配 CSV/JSON 格式檔案，可輕鬆地完成自動化 API 測試，進一步可延展至日常 VMware 環境的管理。
> 進一步了解，請參考官方說明: [Using the Collection Runner](https://learning.postman.com/docs/running-collections/intro-to-collection-runs/)

## 後續練習
透過 **HOL-2225-03-NET** 線上實驗室，可以透過 Postman 協助準備 NSX V2T DFW-Only 的實驗。

**NSX-V API 應用**
- 建立並指派 Security Tag
- 建立 Security Group, IP(MAC) Set, Secvice, Service Group
- 建立 DFW 規則

**NSX-T API 應用**
- 完成基礎結構以完成移轉
> `POST https://{nsxt-mgr-ip}/api/v1/migration?action=finalize_infra`

**vSphere API**
- Migrate VM Workload with vMotion
- Cross vCenter Server vMotion?

當然，**Instant Clone** 除了用先前[分享](https://hackmd.io/@farmer87/instantclone-3)的 **`GOVC`** 達成，也是可以使用到 Postman 學習到的技巧，同樣透過 API 來完成。

## 補充說明
API URL 有時因版本不同會有所差異，也有可能會影響回應請求的資料結構。如果需要使用回應結果進行解析，使用不同版本的 API，必須注意這樣的差異。

以下就以 **`Get Network Object ID`** 做兩個不同版本的差異說明，請根據實際環境進行修正。

**API 請求 URL**
:::warning
**API v7.0 U2**
**`GET`** `{{vcsa_url}}/rest/vcneter/network?filter.name=DB-LS`
:::

:::success
**API v7.0 U3**
**`GET`** `{{vcsa_url}}/api/vcneter/network?name=DB-LS`
:::

**回應結果**

**v7.0 U2**
<img src='https://i.imgur.com/abbwGa2.png' width=320>

**v7.0 U3**
<img src='https://i.imgur.com/iLs3uRF.png' width=320>

兩者回應的格式皆是 **JSON**，但其結構有所不同。所以若要取出 **`network`** 作為 **`DB-LS_objectID`** 舉例。撰寫的 Test 腳本檔寫法只稍有不同，但皆能取得相同的參數值。

**使用 v7.0 U2**

db_ls_objectID = response.value[0].network

**使用 v7.0 U3**

db_ls_objectID = respones[0].network