2024年04月04日玄貓（BlackCat）

Falcon框架建構API實作自動化

本文介紹如何使用 Falcon 框架建構 RESTful API，實作資料編解碼、Splunk 查詢及 Token 驗證等功能，並提供 Python、PowerShell 和 CURL 的呼叫範例，最後示範整合 Splunk API 與 Alexa 語音助手進行語音互動的應用場景。

Web 開發 API 設計

Falcon API Python PowerShell CURL Splunk

Falcon 框架輕量高效，適合建構 RESTful API。本文示範如何利用 Falcon 建立支援資料編解碼、Splunk 查詢和 Token 驗證的 API。程式碼範例包含 Python 實作的 Encode/Decode 類別，處理 HTTP POST 請求並回傳 JSON 格式結果。路由設定將 URL 路徑對映至對應處理類別。此外，文章提供 Python、PowerShell 和 CURL 呼叫 API 的程式碼範例，方便測試與整合。最後，文章展示了結合 Splunk API 和 Alexa 語音助手，實作語音查詢 Splunk 資料的應用案例，展現 Falcon 框架在網路自動化觸發應用中的實用性。

自動化觸發器之網頁框架 Chapter 5

第2節：定義 Encode() 與 Decode() 類別

Encode() 類別實作

Encode() 函式的程式碼如下所示：

class Encode:
    def on_post(self, req, resp):
        data = req.bounded_stream.read()
        try:
            data = json.loads(data)["encode"]
        except:
            print("缺少 encode 鍵值")
            resp.body = "缺少 encode 鍵值"
            return
        encoded = encode(data).split(':')[1]
        resp.body = json.dumps({"encoded": encoded})

Decode() 類別實作

Decode() 函式的程式碼如下所示：

class Decode:
    def on_post(self, req, resp):
        data = req.bounded_stream.read()
        try:
            data = json.loads(data)["decode"]
        except:
            print("缺少 decode 鍵值")
            resp.body = "缺少 decode 鍵值"
            return
        decoded = decode(data)
        resp.body = json.dumps(decoded)

程式碼解析

在上述程式碼中，我們定義了兩個類別：Encode 和 Decode。這兩個類別都包含一個 on_post 方法，用於處理 HTTP POST 請求。請求的資料會被讀取並嘗試解析為 JSON 格式。如果解析失敗或缺少必要的鍵值，伺服器會回傳錯誤訊息。否則，將執行相應的編碼或解碼操作，並將結果以 JSON 格式回傳給客戶端。

第3節：例項化 Falcon API 框架並對映可呼叫 URL

實作 Falcon API 框架

# 建立 falcon.API 例項，可由 gunicorn 呼叫
app = falcon.API()
encod = Encode()
decod = Decode()
# 將 URL 對應到類別
app.add_route("/decode", decod)
app.add_route('/encode', encod)

對映 URL 到函式

在上述程式碼中，我們建立了一個 falcon.API 的例項，並建立了 Encode 和 Decode 類別的例項。然後，我們使用 add_route 方法將特定的 URL 路徑對映到對應的類別例項上。

驗證 API 結果

情境1：呼叫 Splunk API

我們將一個 Splunk 查詢陳述式傳遞給 Splunk API 方法，並顯示回應的輸出：

# python_splunk_call.py
import requests
import urllib

endpoint = "endpointip"

def getresult(query):
    url = "http://" + endpoint + "/splunk/runquery"
    payload = '{"query":"' + query + '"}'
    r = requests.post(url=url, data=payload)
    output = r.json()
    print(output)

# 傳遞編碼後的 Splunk 查詢陳述式
getresult("""search%20index%3D%22main%22%20earliest%3D0%20%7C%20where%20interface_name%3D%22Loopback45%22%20%7C%20dedup%20interface_name%2Crouter_name%20%7C%20where%20interface_status%3D%22up%22%20%7C%20stats%20values%28interface_name%29%20values%28interface_status%29%20by%20router_name%20%7C%20table%20router_name""")

情境2：生成與驗證 Token

我們生成一個 token 用於驗證，並在後續的 API 呼叫中傳遞該 token 以驗證使用者身份：

# python_token_test.py
import requests
import urllib

endpoint = "endpointip"

def generatetoken(uname, password):
    url = "http://" + endpoint + "/token/generate"
    payload = '{"username":"' + uname + '","password":"' + password + '"}'
    print(payload)
    r = requests.post(url=url, data=payload)
    output = r.json()
    print(output)

# 使用不正確的使用者名稱和密碼組合生成 token
generatetoken("abhishek", "testpass123")
# 使用正確的使用者名稱和密碼組合生成 token
generatetoken("John", "testpass")

# python_token_test2.py
import requests
import urllib

endpoint = "testip"

def authenticatetoken(token):
    url = "http://" + endpoint + "/token/test"
    payload = '{"token":"' + token + '"}'
    print(payload)
    r = requests.post(url=url, data=payload)
    output = r.json()
    print(output)

# 驗證不正確的 token
authenticatetoken("rpXS2rtGGGGGaq2V0jqH$WNC2NCjHJe3BmMy.Wylq7eubA52Yj7UhCkDTQqv6nCM")
# 驗證正確的 token
authenticatetoken("rpXS2rtXaq2V0jqH$WNC2NCjHJe3BmMy.Wylq7eubA52Yj7UhCkDTQqv6nCM")

結果與分析

在上述範例中，我們展示瞭如何使用 Falcon 網頁框架建立 API 並實作編碼、解碼、Splunk 查詢以及 token 生成與驗證等功能。這些範例展示瞭如何透過 API 呼叫執行不同的操作，並傳回相應的結果。

透過使用 Falcon 網頁框架，我們可以輕鬆地建立 RESTful API，並實作各種自動化任務。此外，Falcon 的高效能和靈活性使其成為建立複雜網頁服務的理想選擇。

此圖示說明瞭使用 Falcon 網頁框架建立 API 的流程：

@startuml
skinparam backgroundColor #FEFEFE
skinparam defaultTextAlignment center
skinparam rectangleBackgroundColor #F5F5F5
skinparam rectangleBorderColor #333333
skinparam arrowColor #333333

title 此圖示說明瞭使用 Falcon 網頁框架建立 API 的流程：

rectangle "HTTP POST" as node1
rectangle "路由處理" as node2
rectangle "執行相應操作" as node3
rectangle "JSON 格式" as node4

node1 --> node2
node2 --> node3
node3 --> node4

@enduml

此圖示呈現了客戶端傳送 HTTP POST 請求到 Falcon API，再由對應的類別例項處理請求並傳回結果給客戶端的流程。

網路自動化觸發的網頁框架應用

網頁框架驗證與互動

在前面的章節中，我們已經建立了一個網頁框架並將其佈署在伺服器上。現在，讓我們透過不同的範例來瞭解如何呼叫API。以下將展示如何使用Python、PowerShell以及CURL命令來與我們的網頁框架進行互動。

Python 實作範例

import requests

endpoint = "端點 IP 位址"

def get_encode(query):
    url = "http://" + endpoint + "/encode"
    payload = '{"encode":"' + query + '"}'
    r = requests.post(url=url, data=payload)
    output = r.json()
    for value in output.values():
        encoded_value = value
    return encoded_value

def get_decode(encoded_string):
    url = "http://" + endpoint + "/decode"
    payload = '{"decode":"' + encoded_string + '"}'
    r = requests.post(url=url, data=payload)
    output = r.json()
    print(output)

encoded_value = get_encode("abhishek[:]password")
print(encoded_value)
get_decode(encoded_value)

程式碼解析：

匯入必要的函式庫：使用 requests 函式庫來傳送 HTTP 請求。
定義端點：設定網頁框架的端點 IP 位址。
編碼函式 (get_encode)：傳送一個 POST 請求到 /encode 端點，包含需要編碼的字串。
解碼函式 (get_decode)：傳送一個 POST 請求到 /decode 端點，包含需要解碼的字串。
執行編碼和解碼：呼叫 get_encode 和 get_decode 函式，印出結果。

PowerShell 實作範例

$endpoint = "端點 IP"

function Encode-String($value) {
    $url = "http://" + $endpoint + "/encode"
    $payload = @{
        encode = $value
    }
    $body = (ConvertTo-Json $payload)
    $return_val = Invoke-RestMethod -Uri $url -Method Post -Body $body -ContentType 'application/json'
    return $return_val.encoded
}

function Decode-String($value) {
    $url = "http://" + $endpoint + "/decode"
    $payload = @{
        decode = $value
    }
    $body = (ConvertTo-Json $payload)
    $return_val = Invoke-RestMethod -Uri $url -Method Post -Body $body -ContentType 'application/json'
    Write-Host $return_val
}

$encoded_string = Encode-String 'abhishek[:]password'
Write-Host ($encoded_string)
Decode-String $encoded_string

程式碼解析：

定義端點：設定網頁框架的端點 IP 位址。
編碼函式 (Encode-String)：使用 Invoke-RestMethod 傳送 POST 請求到 /encode 端點。
解碼函式 (Decode-String)：使用 Invoke-RestMethod 傳送 POST 請求到 /decode 端點。
執行編碼和解碼：呼叫 Encode-String 和 Decode-String 函式，印出結果。

CURL 命令列工具

在 Linux 平台上，可以使用 CURL 工具來驗證 API 互動。以下展示如何使用 CURL 命令來進行編碼和解碼操作。

編碼操作

curl -X POST \
  http://端點IP位址/encode \
  -H 'Content-Type: application/json' \
  -d '{"encode":"abhishek[:]password"}'

解碼操作

curl -X POST \
  http://端點IP位址/decode \
  -H 'Content-Type: application/json' \
  -d '{"decode":"編碼後的字串"}'

Postman 工具驗證

Postman 是一個常用的 API 測試工具。以下展示如何使用 Postman 來呼叫我們的編碼和解碼 API。

編碼 API

開啟 Postman，建立一個新的 POST 請求。
輸入網址：http://端點IP位址/encode
在 Body 中選擇 raw，並輸入 JSON 資料：{"encode":"abhishek[:]password"}
送出請求，查看回應結果。

解碼 API

開啟 Postman，建立一個新的 POST 請求。
輸入網址：http://端點IP位址/decode
在 Body 中選擇 raw，並輸入 JSON 資料：{"decode":"編碼後的字串"}
送出請求，查看回應結果。

網頁框架的實際應用案例

與 Splunk API 結合的語音互動

透過將我們的網頁框架與 Splunk API 結合，可以實作語音互動式的網路操作。例如，使用 Alexa 語音助手來查詢路由器介面的狀態。

建立 Alexa Skill：建立一個名為 “checksplunk” 的 Skill。
設定 Invocation：設定呼叫命令為 “check Splunk”。
定義 Intents 和 Slots：定義自然語言問題和變數。
連線 Ops API：透過 AWS Lambda 函式連線 Ops API，實作語音互動功能。

Lambda 函式實作（Node.js）

const Alexa = require('ask-sdk-core');

const LaunchHandler = {
  canHandle(handlerInput) {
    return handlerInput.requestEnvelope.request.type === 'LaunchRequest';
  },
  handle(handlerInput) {
    var speechText = "歡迎來到 Splunk Center！今天您想做什麼？"
    return handlerInput.responseBuilder
      .speak(speechText)
      .reprompt(speechText)
      .getResponse();
  },
};