Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

發送 HTTP 請求

為什麼要用 HTTP？

HTTP 請求 常用於與 Web 伺服器及其他非 Godot 程式溝通。

相較於 Godot 其他網路功能（如 高階多人連線），HTTP 請求有較多額外負擔、啟動較慢，因此不適合即時溝通，也不適合像多人遊戲那樣頻繁傳送小量資料。

不過，HTTP 適合與外部 Web 資源互動，也很適合大量資料傳輸，例如交換遊戲素材檔。這些檔案可以再透過 執行時檔案讀寫 載入。

因此，HTTP 特別適合用於遊戲的登入系統、大廳清單、獲取網路資料或下載遊戲素材。

Godot 裡的 HTTP 請求

Godot 最簡單的 HTTP 請求方式是使用 HTTPRequest 節點。底層則有 HTTPClient 類可用，相關教學可參考 這裡。

以下範例將向 GitHub 發送 HTTP 請求，取得最新 Godot 版本名稱。

警告

匯出至 Android 時，請在專案匯出設定裡啟用 Internet 權限，否則任何網路傳輸都會被 Android 系統阻擋。

場景準備

建立新空場景，新增一個 Node 當根節點並掛上腳本，再加一個 HTTPRequest 節點作為子節點。

../../_images/rest_api_scene.webp

撰寫請求腳本

啟動專案時（即 _ready() 階段），將透過 HTTPRequest 節點向 Github 發送 HTTP 請求。完成後會解析回傳的 JSON 資料，尋找 name 欄位並印出至主控台。

extends Node

func _ready():
    $HTTPRequest.request_completed.connect(_on_request_completed)
    $HTTPRequest.request("https://api.github.com/repos/godotengine/godot/releases/latest")

func _on_request_completed(result, response_code, headers, body):
    var json = JSON.parse_string(body.get_string_from_utf8())
    print(json["name"])

儲存腳本與場景，執行專案後，Github 上最新的 Godot 發行名稱會輸出至訊息紀錄。如需解析 JSON 請參考 JSON 的說明文件。

請注意，建議檢查 result 是否等於 RESULT_SUCCESS 以及 JSON 是否有解析錯誤。更多細節請參閱 JSON class reference 和 HTTPRequest 文件。

你必須等一個請求處理完才能發送下一個。若要同時送多個請求，每個請求都需一個 HTTPRequest 節點。一般做法是根據需求在執行時動態建立與刪除 HTTPRequest 節點。

傳送資料到伺服器

前面只介紹了從伺服器取得資料。若要傳資料到伺服器，可以這樣做：

var json = JSON.stringify(data_to_send)
var headers = ["Content-Type: application/json"]
$HTTPRequest.request(url, headers, HTTPClient.METHOD_POST, json)

自訂 HTTP 標頭

你也可以設定自訂 HTTP 標頭，只要傳入字串陣列，每個字串格式為 "header: value"。例如，要自訂 User-Agent（HTTP 的 User-Agent 標頭），可以這樣：

$HTTPRequest.request("https://api.github.com/repos/godotengine/godot/releases/latest", ["User-Agent: YourCustomUserAgent"])

危險

請注意，任何人都可能分析、反編譯你的遊戲，取得嵌入的授權資訊（如 token、帳號、密碼等）。所以千萬不要將資料庫等敏感憑證放進遊戲中，也盡量避免提供任何對攻擊者有用的資訊。