• 什麼是 Postman
• Check Point Management API
  • 快速閱讀 API 文件
• 操作步驟
  • 1. 下載並安裝 Postman
  • 2. 下載並匯入 Postman Collection
    • 下載並解壓
    • 匯入套件
  • 3. 檢視匯入 API
  • 4. 調整設定
    • 忽略 SSL 憑證驗證
    • 設定環境變數（Environment Variable）
    • 調整 API 請求
  • 5. 執行 API 請求
• Check Point GAIA API
• 附錄
  • Pythen Script(原廠提供範本)
    • gaia_show-user.py
• 參考

因為是初心者快速指南所以只列出重點或者就只看看重點吧！

什麼是 Postman

Postman 是一個執行 API 請求的測試工具。讓我們對於 API 進行不同的請求方式，快速且輕鬆地達成目標。

Check Point Management API

Check Point 提供多樣的 [API Reference] 可供參考使用，請根據需求選用。這裡就選擇 Management API 作為目標吧。

Management API 應該主要是用來建立使用於 SmartConsole GUI 中 Security Policy 的相關物件(Object)，除了使用下面提到的 web-service 方式，也可直接使用 mgmt_cli/clish 命令的方式來進行 API 請求。 如果有誤請回報，謝謝！

• Management API Overview

  R81.10 adds a new way to read information and to send commands to the Check Point management server. Just like it is possible to create objects, work on the security policy using the SmartConsole GUI, it is now possible to do the same using command line tools and through web-services.

• 使用 Management API 方式
  • 從 SmartConsole GUI 應用程序內的對話框中輸入 API 命令。
  • 使用 mgmt_cli 輸入 API 命令。（Windows、Linux/Gaia 版本中均可使用）。
  • 使用 Gaia secure shell (clish) 輸入 API 命令。
  • 使用 Web 服務（web-services） 通過 https 連接發送 API 命令。<<< [選定方式]

快速閱讀 API 文件

由於我不是 Check Point 專家，這裡就僅針對 API 請求作最基本的登入驗證測試，對於 API 實際應用及功能，可以再找 Check Point 專家討論。

這裡就對於 [login] API 做基礎說明。

除了 API 文件可以從 [網頁] 查詢外，如果有 Check Point 設備的話，也可以用瀏覽器輸入 https://{ CHECKPOINT_IPADDRESS}/api_docs 取得相同資訊。

• 在 API 說明文件中，先在上方選擇 API 版本，接著點選 Web Services，在左側區域選擇 API Reference > Session Management > login。
  

  • 一般 API 請求需要了解 Request URL，以下是 login 的 API 請求 URL。其中 POST 是請求動作。

    POST https://<mgmt-server>:<port>/web_api/login

  • 再來要注意的是 Request Headers，這裡通常會指定請求的內容類型(content-type)，目前大多都是 JSON 格式。
  • 如果請求動作是 POST/PUT/DELETE，通常還需要搭配 Request body，在 API 說明中便會列出必要 (Required) 提供的請求內容。login API 請求需要以 JSON 格式提供 user,password，以便進行帳號驗證取得 API 存取權限。另一種常見的方式就是用 api-key。

• 了解如果執行請求，接著就要了解回應 (Respones) 內容。
  

  • 每個請求回應都會有回應狀態碼 (HTTP Return code)，分別有成功(On Success) 和失敗(On Failure)，一般成功回應碼會是 200，但請參考文件確認。
  • 回應的結果會顯示在 Respone body，會以 JSON 格式顯示，當然每個回應內容會根據 API 請求而有所不同。
    • 以 login 回應結果來看，提供了紅色框線部份的資訊，其中我們要關注的是 sid(Session ID)，因為之後的 API 請求會需要取得該值引入 Request Header: X-chkp-sid 完成請求。

• 原廠 API 說明文件也提供操作範例 (Sample)。
  

如果對於 python 程式熟悉的話，可以參考 [附錄：Pythen-Script原廠提供範本]。

操作步驟

1. 下載並安裝 Postman

請根據需求閱讀以下 Postman 官方資訊，自行下載並安裝 Postman。

• Download Postman
• Installing and updating Postman

執行 Postman

• Postman 目前有桌面版 [下載] 和網路版 [連結]。網路版功能多所限制，建議安裝桌面版本。
• 註冊帳號
  若有以下的需求，建議可以[註冊]一組 Postman 帳號使用。
  • 在 Postman Workspaces 中組織您的所有 API 開發
  • 跨設備同步您的 Postman 數據
  • 將您的數據備份到 Postman 雲
  • 免費！

2. 下載並匯入 Postman Collection

Postman Collection 基本上就當作是 API 請求及相關元件的集合。Check Point 原廠已經幫各位準備好相關的 API 精選集（Check Point R8X Postman Collection），請根據需求版本至 CheckMates [下載] 對應的套件。

• Postman Collections (links to all available) and the basics
• API v 1.8 R81.10 Postman Collection

下載並解壓

Check Point API 精選集

根據使用設備選定 API v1.8 R81.10，下載 [postman_collection-1.8.json.zip] 後解壓備用。

匯入套件

• Create workspaces
• Importing data into Postman

建立新的工作區（Workspace）

• 開啟 Postman，點擊上方 Workspaces > Create Workspace。
  

• 選擇 Blank workspace > Next。
  

• 輸入名稱(Name)，選擇 Personal > Create。
  

匯入 API 套件

• 確認位於新建立的工作區，點擊上方的 import。
  

• 將先前下載解壓的 API 套件拖拉至此，Postman 會自動開始匯入 API 相關資料。
  

• 匯入成功。
  

• 點選左側 Collections，檢視匯入的 API 套件。
  

3. 檢視匯入 API

• 確認匯入 API 成功後，選擇 01 Session Management > POST login，進行第一個 API 請求的檢視及準備。
  

• API 請求 POST {{server}}/v1.8/login
  

• {{server}} 使用 Postman 變數，等會使用環境變數 (Environment Variable) 指定。
• v1.8 表示 API 版本，待會也透過環境變數 (Environment Variable) {{api_version}} 指定。
• API 請求變更為 {{server}}/{{api_version}}/login。

• Body 部份，帶入 API 驗證帳號資訊（JSON 格式）

• Test 部份，Check Point 原廠已經寫好測試用的腳本程序了。只要放心執行 SEND 請求就可以。

API 請求執行完成後，Test 腳本會根據請求回應，將取得的 Session ID(sid) 參數值設定成為環境變數 session。

4. 調整設定

忽略 SSL 憑證驗證

點擊右上方

圖示，選擇 Settings。

在 General 項目，取消 SSL certificate verification 功能。

設定環境變數（Environment Variable）

建立 Check Point 環境變數

參考下圖建立環境變數，並設定初始值（Initial Value），記得儲存 (Save)。點擊右上方下拉選單，使用新建立的環境變數。之後 API 請求就會先參照這裡的參數，帶入指定的參數值。

調整 API 請求

使用環境變數設定，參考下圖紅色標註，重新調整原本的 API 請求寫法。

5. 執行 API 請求

正確完成上述設定，只要輕鬆點擊 Send，就可以送出指定的 API 請求。順利的話，中間下方在 Body 功能項會顯示請求回應內容。

還記得執行成功，Test 腳本會將取得的 Session ID(sid) 設定成為環境變數 session，可作為之後 API 請求使用。

Check Point GAIA API

Check Point 還有 GAIA API，可以參考 [原廠資訊]。

這個 API 應該就像在專家模式(Expert Mode) 下執行命令一樣。可以透過 mgmt_cli 命令 和 web-service 方式進行 API 請求。如果有誤請回報，謝謝！

既然已經有之前 API 請求的

使用經驗，這裡可以參考 [show-user API] 說明，自行完成 API 請求操作。

• API 請求說明
  

• API 請求範例
  

• Postman 操作

  • Request URL & Headers 設定
    
  • Request body 設定
    
  • Response 結果
    
  • Postman Console 檢視
    

• 失敗原因 最常遇到的原因就是 Session 過期，因此在 Request Headers 引入的 X-chkp-sid 有錯誤造成的，解決方式只要再次執行一次 login API 請求，重新取得正確的 Session ID 就可以了！

或是使用 Postman Run Collection 一次執行 2 個 API 請求。

結論

• Check Point 原廠提供多樣化的 API，不管在文件說明及操作範例，都提供豐富資訊！
• 若是善加應用或許可簡化組態或強化自動化管理功能。
• API 測試採用 Postman 的確是輕易入門的作法，而且原廠也提供了對應的精選集！

附錄

Pythen Script(原廠提供範本)

import requests, json

def api_call(ip_addr, port, command, json_payload, sid):
    url = 'https://' + ip_addr + ':' + port + '/web_api/' + command
    if sid == '':
        request_headers = {'Content-Type' : 'application/json'}
    else:
        request_headers = {'Content-Type' : 'application/json', 'X-chkp-sid' : sid}
    r = requests.post(url,data=json.dumps(json_payload), headers=request_headers)
    return r.json()


def login(user,password):
    payload = {'user':user, 'password' : password}
    response = api_call('192.168.65.2', 443, 'login',payload, '')
    return response["sid"]

sid = login('my_username','secret')
print("session id: " + sid)

new_host_data = {'name':'new host name', 'ip-address':'192.168.1.1'}
new_host_result = api_call('192.168.65.2', 443,'add-host', new_host_data ,sid)
print(json.dumps(new_host_result))

publish_result = api_call('192.168.65.2', 443,"publish", {},sid)
print("publish result: " + json.dumps(publish_result))

logout_result = api_call('192.168.65.2', 443,"logout", {},sid)
print("logout result: " + json.dumps(logout_result))	

gaia_show-user.py

根據原廠提供 python 腳本範例，撰寫簡單的 show-user API 請求的 python 程式。

• python 程式範例

#!/usr/bin/python3

import requests
import json
import urllib3
urllib3.disable_warnings()

checkpoint_ip = '10.7.155.117'
api_user = 'apiUser'
api_pass = '*************'
gaia_api_version = 'v1.7'

def gaia_api_call(ip_addr, port, version, command, json_payload, sid):
    url = 'https://' + ip_addr + ':' + str(port) + '/gaia_api/' + version + '/' + command
    if sid == '':
        request_headers = {'Content-Type' : 'application/json'}
    else:
        request_headers = {'Content-Type' : 'application/json', 'X-chkp-sid' : sid}
    r = requests.post(url,data=json.dumps(json_payload), headers=request_headers, verify=False)
    return r.json()

def login(user, password):
    payload = {"user": user, "password": password}
    response = gaia_api_call(checkpoint_ip, 443, gaia_api_version, 'login', payload, '')
    return response["sid"]

sid = login(api_user,api_pass)
print("[Session ID] " + sid)

## show-user
show_user_payload = {"name": api_user}
show_user_result = gaia_api_call(checkpoint_ip, 443, gaia_api_version, 'show-user', show_user_payload ,sid)

print("\n[RESULT] Show User [" + api_user + "]")
print(json.dumps(show_user_result, indent=4))

logout_result = gaia_api_call(checkpoint_ip, 443, gaia_api_version, "logout", {},sid)
print("\n[LOGOUT RESULT]\n" + json.dumps(logout_result, indent=4))	

• 執行結果
  

參考

• Check Point APIs Homepage
• Management API Reference
• GAIA API Reference
• Postman Collections and the basics

  Check Point R8X Postman Collections available on CheckMates community

  • API v 1.8 R81.10 [LINK]
  • API v 1.9 R81.20 [LINK]
• postman_collection R81.10(v2)
• Postman Test Scripts
• Postman Test Examples

---