代理API

Important

自 v3.3.1 起，每個 Dev Proxy API 請求都需要標 Authorization: Bearer <token> 頭;沒有有效 token 回傳 401 Unauthorized的請求。

開發 Proxy 隨附 Web API，可讓您以程式設計方式與 Proxy 互動。 API 可在代理設定中指定的 IP 位址和埠口使用。

Dev Proxy 會為每個執行中的實例產生一個獨特的權杖，並存到一個只有啟動實例的使用者能存取的檔案中。使用 devproxy status 或 devproxy api token取得令牌。當 CI 環境變數被設定時，請使用 devproxy api token ，因為 Dev Proxy 會省略狀態和啟動輸出中的標記。

例如，當另一個工具啟動 Dev Proxy 並呼叫其 API 時，要使用已知的 token 而非產生的 token，請先設定 DEV_PROXY_API_TOKEN 環境變數，或透過該 --env 選項傳遞。該值必須至少有 32 個字元長，不包括後方=填充，且只能包含 ASCII 字母、數字，以及字元 -、 .、 _+~/，後面可選擇性地加上=填充。 Dev Proxy 會修剪周圍的空白區域。如果值不正確，Dev Proxy 不會啟動並會出錯退出。開發代理仍然儲存代幣，所以 devproxy status、 devproxy api token，繼續 devproxy stop 運作。

在標頭中包含該標記 Authorization ：

Authorization: Bearer <token>

無有效令牌的請求回傳 401 Unauthorized。瀏覽器請求也必須來自設定 apiAllowedOrigins 中列出的來源。其他起源回歸 403 Forbidden。

Operations

下列清單顯示可用的 API 作業。

`GET /proxy`

傳回的實例 ProxyInfo ，其中包含目前執行中 Dev Proxy 實例的相關信息。

範例：取得目前執行中開發 Proxy 實例的相關信息

要求：

GET http://localhost:8897/proxy
Authorization: Bearer <token>

回應：

200 OK

{
  "recording": false,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

`POST /proxy`

控制目前執行中的 Dev Proxy 實例。若要從腳本或 CI 管線開始或停止錄影，請參見「從腳本與 CI 錄製」。

範例：開始錄製

要求：

POST http://localhost:8897/proxy
Authorization: Bearer <token>
content-type: application/json

{
  "recording": true
}

回應：

200 OK

{
  "recording": true,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

範例：停止錄製

要求：

POST http://localhost:8897/proxy
Authorization: Bearer <token>
content-type: application/json

{
  "recording": false
}

回應：

200 OK

{
  "recording": false,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

停止錄影並產生報告

停止錄影不只是停止擷取請求。當你在 Dev Proxy 錄影時發送 {"recording": false} ，Dev Proxy 會依照設定檔中列出的順序，將錄製的請求傳給所有啟用的插件。這跟在執行 Dev Proxy 的控制台按 s 鍵是一樣的。在此步驟中：

報告外掛會分析記錄的請求並產生報告。
記者會將報告轉換成檔案。每個報告者為每個報告撰寫一個檔案，命名為 <plugin>_<reporter>.<extension>，例如。 ExecutionSummaryPlugin_MarkdownReporter.md <plugin> 是產生報告的外掛實例名稱，是 <reporter> 報告實例的名稱。如果已有該名稱的檔案存在，報告器會加上時間戳，例如。 ExecutionSummaryPlugin_MarkdownReporter_20261105114500.md
產生器插件，像是 OpenApiSpecGeneratorPlugin，會寫入它們產生的檔案。

Dev Proxy 會將這些檔案寫入其目前的工作目錄，也就是你啟動 Dev Proxy 的目錄。

API 會在所有插件處理完成錄製的請求後才回應。根據你使用的外掛，例如呼叫語言模型的外掛，這步驟可能會花上一段時間，所以請確保你的 HTTP 用戶端不會太早逾時。當回應到達時，報告檔案會寫入磁碟。

Dev Proxy 也會記錄處理已錄製請求的進度：

日誌訊息	Meaning
`DONE`	所有插件都完成了錄製的請求處理。
`No requests to process`	外掛找不到任何可分析的錄音請求。
`An error occurred in a plugin`	一個插件失敗了。 Dev Proxy 會繼續執行下一個插件，並在所有插件完成後進行 `DONE` 日誌。

如果你傳送 {"recording": false}時 Dev Proxy 沒有錄音，它就不會處理任何請求，也不會寫入任何檔案，也不會記錄 DONE。

Tip

如果你在錄製時停止使用 POST /proxy/stopproxy Dev Proxy，Dev Proxy 也會在結束前處理已錄製的請求。不過，該 API 會立即回應，因此你需要等 Dev Proxy 程序退出後，才能知道報告是否準備好。要確定報告何時準備好，先停止錄影，等待回應，然後停止開發代理。

關於啟動開發代理、透過 API 控制錄影並等待開發代理完成的完整腳本，請參考「在 CI/CD 情境中使用開發代理」。

`POST /proxy/jwtToken`

產生 JSON Web 令牌（JWT）。

要求：

POST http://localhost:8897/proxy/jwtToken
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Dev Proxy",
  "audiences": [
    "https://myserver.com"
  ],
  "issuer": "dev-proxy",
  "roles": [
    "admin"
  ],
  "scopes": [
    "Post.Read",
    "Post.Write"
  ],
  "claims": {
    "claim1": "value",
    "claim2": "value"
  },
  "validFor": 60
}

注意

已註冊的宣告（例如，、isssub、、aud、exp、nbfiat、jti）會自動新增至令牌。如果您在要求中指定上述任何宣告，API 會忽略您提供的值。

回應：

200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IkRldiBQcm94eSIsInN1YiI6IkRldiBQcm94eSIsImp0aSI6IjkyZjM5YzciLCJzY3AiOlsiUG9zdC5SZWFkIiwiUG9zdC5Xcml0ZSJdLCJyb2xlcyI6ImFkbWluIiwiY2xhaW0xIjoidmFsdWUiLCJjbGFpbTIiOiJ2YWx1ZSIsImF1ZCI6Imh0dHBzOi8vbXlzZXJ2ZXIuY29tIiwibmJmIjoxNzI3MTk4MjgyLCJleHAiOjE3MjcyMDE4ODIsImlhdCI6MTcyNzE5ODI4MiwiaXNzIjoiZGV2LXByb3h5In0.E_Gj9E58OrAh9uHgc-TW8DYfq8YHFrhaUTpKA4yXEIg"
}

`GET /proxy/logs`

回傳開發代理的日誌輸出。相當於命令 logs 。此端點僅在 Dev Proxy 以分離模式運行時可用。否則，API 回傳 404 Not Found。

查詢參數	描述	預設值
`lines`	從對數末端返回的線數	`50`
`follow`	當 `true`時，會以伺服器傳送事件的方式串流新的日誌行	`false`
`since`	只回傳自指定日期和時間以來記錄的行數。請使用時間（例如 `30s`，， `5m1d1h`，）或 ISO 8601 日期與時間（例如 `2026-01-24T14:00:00` ，或）。`2026-01-24T14:00:00Z` 如果時間戳沒有包含時區偏移，Dev Proxy 會使用當地時區。	n/a

參數會 since 依照完整日期和時間篩選日誌行，無論是回傳日誌行還是串流播放時。 Dev Proxy 會依請求開始的時間來篩選每個請求，所以在指定時間前開始的請求不會被回傳，即使它後來結束了。

預設情況下，API 會將日誌行以純文字回傳。要取得 JSON 日誌條目的陣列，請將標頭設 Accept 為 application/json。若要將日誌行串流為伺服器發送事件，請將標頭設 Accept 為 text/event-stream 或設 follow 為 true。

要求：

GET http://localhost:8897/proxy/logs?lines=10
Authorization: Bearer <token>

回應：

200 OK
content-type: text/plain

[last 10 lines of the Dev Proxy log]

`POST /proxy/mockrequest`

引發模擬要求。相當於在執行Dev Proxy的控制台中按 w 。 API 會在模擬請求完成後回應。

要求：

POST http://localhost:8897/proxy/mockrequest
Authorization: Bearer <token>

回應：

204 No Content

`GET /proxy/rootCertificate?format=crt`

下載開發 Proxy 用來解密 HTTPS 要求之 PEM（隱私權增強郵件）格式之跟證書的公鑰。當您想要在 Docker 容器中執行 Dev Proxy 時信任主機上的跟證書時，此 API 會很有説明。

目前，唯一支援的格式是 crt。如果您指定任何其他格式或完全未指定格式，API 會傳回 400 錯誤的要求錯誤。

要求：

GET http://localhost:8897/proxy/rootCertificate?format=crt
Authorization: Bearer <token>

回應：

content-type: application/x-x509-ca-cert

-----BEGIN CERTIFICATE-----
[base64 encoded certificate]
-----END CERTIFICATE-----

`POST /proxy/stopproxy`

正常關閉開發 Proxy。如果 Dev Proxy 正在錄影，它會在結束前停止錄影並產生報告。 API 在 Dev Proxy 關閉前立即回應。

要求：

POST http://localhost:8897/proxy/stopproxy
Authorization: Bearer <token>

回應：

202 Accepted

Dev Proxy 一開始關機就會立刻回歸 202 Accepted 。這個回應並不代表 Dev Proxy 已經退出。關閉期間，開發代理：

停止接受新的代理請求。如果開發代理被註冊為系統代理，它會恢復之前的系統代理設定。 Dev Proxy 會等待最多五秒鐘，讓未開啟的連線關閉，然後關閉剩餘的連線。
如果錄影開啟，它會停止錄影，並對錄製的請求執行報告插件，就像你停止自己錄音一樣。當外掛完成後，Dev Proxy 會撰寫報告和日誌 DONE。
移除實例資訊，也devproxy statusdevproxy stop就是不再列出。
有出口代碼 0的出口。

Dev Proxy 在關機時不會從受信任憑證庫移除根憑證。要移除憑證，請使用 cert remove。

關機通常需要幾秒鐘。當外掛程式處理大型錄音時，可能會花更長時間。關閉開始後，API 就無法連線，所以不要輪詢 API 來確認 Dev Proxy 是否已經退出。相反地，請使用以下選項之一：

等待列印出來的程序 ID（PID） devproxy --detach 退出。
執行 devproxy status --pid <pid> 直到返回退出代碼 1，表示該實例已停止執行。欲了解更多資訊，請參閱狀態。
如果你在錄影，請查看開發代理日誌中的 DONE 訊息，開發代理會在報告插件結束後記錄訊息。舉例來說，請參考「在 CI/CD 情境中使用開發代理」。

例如，要等待分離的開發代理實例在 Linux 或 macOS 上退出：

# DEVPROXY_PID is the PID that devproxy --detach printed
# TOKEN is the API token from devproxy api token
curl -X POST http://localhost:8897/proxy/stopproxy -H "Authorization: Bearer $TOKEN"

while ./devproxy/devproxy status --pid $DEVPROXY_PID > /dev/null 2>&1; do
  sleep 1
done

避免強制終止開發代理程序，例如使用 kill -9。當你用這種方式結束流程時，Dev Proxy 不會清除錄影或還原系統代理設定。要從命令列停止 Dev Proxy，請使用 stop，這會呼叫這個 API，並等待開發代理退出最多 10 秒。

模型

`ProxyInfo`

目前執行之 Dev Proxy 實例的相關信息。

屬性	類型	描述
`recording`	`boolean`	Proxy 目前是否正在錄製要求
`configFile`	`string`	開發 Proxy 所使用的組態檔路徑（唯讀）

`JwtOptions`

產生 JWT 令牌的選項。

屬性	類型	描述
`name`	`string`	要為其建立令牌的用戶名稱
`audiences`	`string[]`	要為其建立令牌的物件
`issuer`	`string`	令牌的簽發者
`roles`	`string[]`	要新增至令牌的角色宣告
`scopes`	`string[]`	要新增至令牌的範圍宣告
`claims`	`KeyValuePair`	要新增至令牌的宣告
`validFor`	`number`	權杖有效持續時間（以分鐘為單位）
`signingKey`	`string`	用來簽署令牌的金鑰。長度必須至少為32個字元。如果未指定，請使用隨機產生的索引鍵。

`JwtInfo`

JWT 令牌的相關信息。

屬性	類型	描述
`token`	`string`	JWT 令牌

也請參閱

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-11-05

代理API

Operations

GET /proxy

範例：取得目前執行中開發 Proxy 實例的相關信息

POST /proxy

範例：開始錄製

範例：停止錄製

停止錄影並產生報告

POST /proxy/jwtToken

GET /proxy/logs

POST /proxy/mockrequest

GET /proxy/rootCertificate?format=crt

POST /proxy/stopproxy

模型

ProxyInfo

JwtOptions

JwtInfo