前言

在Day 29：物聯網幽靈的RESTful API 謎題．芝麻開門中提到：用Flask來建立一個RESTful API，並且要按照「宿舍訪客名單 API 的需求規格」需求規格，用 Flask 跟 PyMongo來實作API，然後用Postman來測試它的功能和效能。
這個程式碼的目的是建立一個宿舍訪客名單的網路服務，讓使用者可以透過網路來查詢、新增、修改或刪除訪客的資料。

回顧

• 零、設定環境
• 一、引入 Flask 和 PyMongo 套件
• 二、建立 Flask 應用程式
• 三、設定 MongoDB 連線資訊
• 四、建立 HTTPBasicAuth 物件
• 五、設定帳號密碼驗證機制
• 六、定義路由和 HTTP 方法，並使用 auth.login_required 要求驗證

目標

這次的目標是實作以下內容：

• 六、定義路由和 HTTP 方法，並用 auth.login_required decorator 要求驗證
  • 6-1 如果是 GET 方法，則取得所有或特定的訪客資料
  • 6-2 如果是 POST 方法，則新增一筆訪客資料

六、定義路由和 HTTP 方法

用 auth.login_required decorator 要求驗證

我們在第29天中有提到，這就像是管理員要先定義好一些規則，例如：

• 如果有人要查詢或新增訪客資料，他們要用網址 http://192.168.1.100:5000/visitors 來跟管理員聯絡，並且告訴他們是要查詢（GET）還是新增（POST）。
• 如果有人要修改或刪除特定的訪客資料，他們要用網址 http://192.168.1.100:5000/visitors/ 來跟管理員聯絡，並且告訴他們是要修改（PUT）還是刪除（DELETE），以及要操作哪一筆資料（id）。

# 定義路由和 HTTP 方法，並使用 auth.login_required decorator要求驗證
@app.route("/visitors", methods=["GET", "POST"])
@auth.login_required
def visitors():

• @app.route("/visitors", methods=["GET", "POST"])：
  • 這一行是告訴 ‘/visitors’ 允許的method有什麼（"GET", "POST"）。
  • 即使沒有使用GET功能，也不能拿掉，因為GET是預設，用在URL，這樣才知道要去哪個網站、呈現哪個HTML　(長風青雲, 2019)。

1. GET（取得所有或特定的訪客資料）

這就像是管理員要根據使用者的需求，從資料庫中找出相對應的訪客資料，並且回傳給使用者。

	# 如果是 GET 方法，則取得所有或特定的訪客資料
	if request.method == "GET":
		# 取得查詢參數 name，如果沒有則預設為空字串
		name = request.args.get("name", "")
		# 如果有 name，則根據 name 查詢特定的訪客資料
		if name:
			visitor = mongo.db.visitors.find_one({"name": name})
			# 如果找不到，則回傳 404 狀態碼和錯誤訊息
			if visitor is None:
				return jsonify({"status": 404, "message": "Visitor not found"}), 404
			# 如果找到，則回傳 200 狀態碼和訪客資料
			else:
				return jsonify({"status": 200, "visitor": visitor}), 200
		# 如果沒有 name，則取得所有的訪客資料
		else:
			visitors = mongo.db.visitors.find()
			# 將查詢結果轉換為列表
			visitors_list = list(visitors)
			# 回傳 200 狀態碼和訪客列表
			return jsonify({"status": 200, "visitors": visitors_list}), 200

• 如果是 GET 方法，則取得所有或特定的訪客資料
  這就像是管理員要根據使用者的需求，從資料庫中找出相對應的訪客資料，並且回傳給使用者。
  if request.method == "GET":：使用者使用GET時執行（從指定的資源請求數據）(Willis, 2022)
  • 取得查詢參數 name，如果沒有則預設為空字串
    這就像是管理員要先問使用者想查詢哪一位訪客的名字，如果使用者沒有說明，就預設為空字串。
    request.args.get('參數名稱')：
    Flask API要取得request的值的其中一種方式，取得URL後的參數 (無言小獅子, 2022)。
    request.args：
    使用request.args取得前端的username(Willis, 2022)
    args.get：
    使用args.get取得 GET 參數值(peiiiii, 2022)
  • 如果有 name，則根據 name 查詢特定的訪客資料
    這就像是管理員根據使用者提供的名字，在資料庫中找出符合的訪客資料。
    find_one({"name": name})：之前在第18天時有提到，使用find_one指令呼叫查詢，就像是在圖書館裡找一本特定的書，會取得返回符合條件的第一筆資料。
    • 如果找不到，則回傳 404 狀態碼和錯誤訊息
      就像是管理員告訴使用者，他沒有找到這位訪客的資料，並且用 404 這個代碼表示找不到的意思。
      {"Name": "kevin", "age": "18"}：
      JSON的資料格式中，用大括號{}表示的是物件(object)，物件(objcet)運作方式很像Python的Dict，JSON的物件是用key to value的方式去配對儲存資料 (silly_letter,2022)。
      "status": 404：
      常常聽到的404(not found)是一種HTTP Status Code，代表找不到請求的資源 (jim_chung, 2020)
    • 如果找到，則回傳 200 狀態碼和訪客資料
      就像是管理員告訴使用者，他已經找到這位訪客的資料，並且用 200 這個代碼表示成功的意思，然後把訪客的資料回傳給使用者。
      "status": 200：
      一般正常回應的情況下，會回傳200(OK)代表成功 (jim_chung, 2020)
  • 如果沒有 name，則取得所有的訪客資料
    這就像是管理員根據使用者沒有提供名字的情況，在資料庫中找出所有的訪客資料。
    find_one({"name": name})：使用find呼叫查詢時，如果沒有傳入任何資訊（沒有任何的篩選條件），就會把所有資料回傳(肯恩, 2020)
    • 將查詢結果轉換為列表：
      這就像是管理員把找到的所有訪客資料整理成一個列表，方便回傳。
    • 回傳 200 狀態碼和訪客列表：
      這就像是管理員告訴使用者，他已經找到所有的訪客資料，並且用 200 這個代碼表示成功的意思，然後把訪客列表回傳給使用者。

2. POST（新增一筆訪客資料）

	# 如果是 POST 方法，則新增一筆訪客資料
	elif request.method == "POST":
	    # 取得請求中的 JSON 資料
	    data = request.get_json()
	    # 檢查 JSON 資料是否包含所有必要的欄位
	    if data and all(key in data for key in ["name", "age", "gender", "phone", "address"]):
	        # 執行 insert_one 新增訪客資料到 MongoDB 中
	        result = mongo.db.visitors.insert_one(data)
	        # 回傳 201 狀態碼和新增的訪客 id
	        return jsonify({"status": 201, "id": str(result.inserted_id)}), 201
	    # 如果 JSON 資料不完整，則回傳 400 狀態碼和錯誤訊息
	    else:
	        return jsonify({"status": 400, "message": "Missing or invalid data"}), 400

• 如果是 POST 方法，則新增一筆訪客資料
  這就像是管理員要根據使用者提供的資料，往資料庫中新增一筆訪客資料，並且回傳結果給使用者。
  if request.method==’POST’:：
  要資料：使用者使用POST時執行（向指定的資源提交要被處理的數據）（Willis, 2022）
  • 取得請求中的 JSON 資料
    這就像是管理員要先從使用者那裡收到一個 JSON 格式的資料，裡面包含了要新增的訪客的相關資訊。
    request.get_json()：
    Flask API要取得request的值的其中一種方式，取得JSON的值 (無言小獅子, 2022)。
  • 檢查 JSON 資料是否包含所有必要的欄位
    這就像是管理員要先檢查使用者提供的資料是否完整，是否包含了姓名、年齡、性別、電話、地址等欄位。
    ["name", "age", "gender", "phone", "address"]：
    JSON的資料格式中，用中括號[]表示的是陣列(array)，是一系列的值(value)所組成的 (silly_letter,2022)。
    • 執行 insert_one 新增訪客資料到 MongoDB 中
      這就像是管理員在確認資料完整後，把它寫入到資料庫中，並且取得新增的訪客 id。
      insert_one：在MongoDB指令(1)中有提到，使用insert_one指令，就像是在圖書館中增加一本新書，要填寫欄位名稱和對應的值等。
    • 回傳 201 狀態碼和新增的訪客 id
      這就像是管理員告訴使用者，他已經成功地新增了一筆訪客資料，並且用 201 這個代碼表示新增的意思，然後把新增的訪客 id 回傳給使用者。
      201狀態碼：是一種HTTP Status Code，代表已建立 ( Hypertext Transfer Protocol: Response Status Codes)。
      　　表示請求已經完成，並且產生了一個或多個新的資源（可以想像成用外送平台點餐時，下單後會看到訂單從準備中到準備完成的畫面，代表餐廳已經準備好你點的餐點了）。
      　　請求所建立的主要資源，可以透過回應中的 Location 標頭欄位來識別（餐廳準備好你的餐點後，就會有外送員去取餐，你可以透過平台給你的位置資訊看到外送員的位置）
      　　或者如果沒有收到 Location 欄位，則透過有效的請求 URI 來識別（如果是自取的話，餐廳通常也會給一個訂單號碼，讓你可以取餐）。
  • 如果 JSON 資料不完整，則回傳 400 狀態碼和錯誤訊息
    這就像是管理員在發現資料不完整或無效時，告訴使用者他無法新增這筆資料，並且用 400 這個代碼表示錯誤的意思，然後把錯誤訊息回傳給使用者。
    400狀態碼：是一種HTTP Status Code，代表錯誤的請求 ( Hypertext Transfer Protocol: Response Status Codes)。
    　　表示伺服器無法或不願處理請求，因為伺服器認為這是客戶端的錯誤（可以想像成用外送平台點餐時，如果外送員發現你的訂單內容有問題，或是地址寫錯還要請外送員免費幫你送到更遠的地方，外送員可能會棄單）。

下集預告

• 七、定義路由和 HTTP 方法，用變數 id 傳遞參數，並用 auth.login_required decorator 要求驗證
  • 7-1 如果是 PUT 方法，則修改一筆訪客資料
  • 7-2 如果是 DELETE 方法，則刪除一筆訪客資料
• 八、啟動 Flask 應用程式，並指定主機和埠號

傳送門

撰寫Flask Web來存取Mongo DB (1)討論如何實作以下內容：

• 零、設定環境
• 一、引入 Flask 和 PyMongo 套件
• 二、建立 Flask 應用程式
• 三、設定 MongoDB 連線資訊

撰寫Flask Web來存取Mongo DB (2)討論如何實作以下內容：

• 四、建立 HTTPBasicAuth 物件
• 五、設定帳號密碼驗證機制
• 六、定義路由和 HTTP 方法，並使用 auth.login_required 要求驗證

撰寫Flask Web來存取Mongo DB (3)討論如何實作以下內容：

• 六、定義路由和 HTTP 方法，並用 auth.login_required decorator 要求驗證
  • 6-1 如果是 GET 方法，則取得所有或特定的訪客資料
  • 6-2 如果是 POST 方法，則新增一筆訪客資料
    撰寫Flask Web來存取Mongo DB (4)討論如何實作以下內容：
• 七、定義路由和 HTTP 方法，用變數 id 傳遞參數，並用 auth.login_required decorator 要求驗證
  • 7-1 如果是 PUT 方法，則修改一筆訪客資料
  • 7-2 如果是 DELETE 方法，則刪除一筆訪客資料
    撰寫Flask Web來存取Mongo DB (5)討論如何實作以下內容：
• 八、啟動 Flask 應用程式，並指定主機和埠號