Salesforce把Heroku API藏了8年

全球170個國家、超過400萬個應用跑在Heroku上，但90%的開發者至今還在手動點按鈕部署。一個運維10個以上應用的團隊，每周要在重復操作上燒掉8到12小時——這相當于每年扔掉一個半月的人效。

Heroku API（應用程序編程接口）其實2011年就上線了，Salesforce收購后反而被埋得更深。直到2024年平臺功能大更新，這套RESTful接口才真正成熟：OAuth 2.0認證、1小時1萬次的調用額度、從應用生命周期到基礎設施擴縮的全鏈路覆蓋。問題在于，官方文檔寫得像說明書，沒人告訴你該在什么時候、用什么姿勢調用。

本文用一套可直接復制的Node.js客戶端代碼，把認證陷阱、核心端點、CI/CD實戰串成閉環。讀完能直接上手，不需要再翻第二篇教程。

認證：別在代碼里寫死密鑰，這是新手墳場

Heroku CLI是生成API令牌的最短路徑。macOS用Homebrew、Windows用npm、Linux用curl腳本，三條命令覆蓋全平臺。裝完之后先執行heroku login，瀏覽器跳轉完成OAuth授權——這一步很多人卡在命令行等待，其實是要你去點彈出的窗口。

令牌分兩種壽命。臨時令牌適合本地調試，heroku authorizations:create --short-lived生成后幾小時失效，泄露了也不怕。CI/CD流水線必須用長期令牌，帶描述和過期時間：--description "CI/CD Pipeline" --expires-in "1 year"。一年到期強制輪換，比永久令牌安全一個數量級。

密鑰管理的鐵律是絕不硬編碼。把HEROKU_API_KEY寫進.env文件，.gitignore里加上這行，比任何代碼審查都管用。我見過太多人把密鑰提交到GitHub，被掃描機器人秒扒，賬單一夜之間飆到五位數。

請求頭必須成對出現。Authorization: Bearer {token}負責身份，Accept: application/vnd.heroku+json; version=3鎖定API版本。漏掉第二個，Heroku會返回2012年的舊格式，字段名全不一樣，調試能調通宵。

測試連通性的curl命令長這樣：

curl -n https://api.heroku.com/account \-H "Accept: application/vnd.heroku+json; version=3" \-H "Authorization: Bearer $HEROKU_API_KEY"

返回的JSON里確認email字段匹配你的賬號，就可以進入業務邏輯了。

封裝：寫一次客戶端，所有接口復用

原生的fetch調用散落在各處，錯誤處理會寫成災難。建議封裝一個herokuRequest函數，把base URL、認證頭、狀態碼判斷全包進去。Node.js 18+內置fetch，不需要額外依賴。

核心結構是：從環境變量讀密鑰，拼接完整URL，強制注入三個標準頭，非2xx狀態碼自動拋錯并帶上Heroku返回的message。調用方只需要關心業務端點和payload。

const herokuRequest = async (endpoint, options = {}) => {const response = await fetch(`${HEROKU_BASE_URL}${endpoint}`, {...options,headers: {'Authorization': `Bearer ${HEROKU_API_KEY}`,'Accept': 'application/vnd.heroku+json; version=3','Content-Type': 'application/json',...options.headersif (!response.ok) {const error = await response.json();throw new Error(`Heroku API Error: ${error.message}`);return response.json();};

這個模板能撐到生產環境。需要加功能的話，在headers里塞Range做分頁，或者在options里開retry邏輯，改動都收斂在一處。

應用與 dyno（容器單元）：自動化部署的兩大抓手

Heroku的應用（app）是邏輯容器，dyno是實際跑代碼的容器單元。API對兩者的操作粒度完全不同：應用層管配置、域名、環境變量；dyno層管進程類型、數量、規格。

創建應用用POST/apps，payload里指定name和region。名字全局唯一，搶注邏輯和域名類似。拿到app ID后，才能往里面推代碼或者綁定流水線。

dyno的彈性是API最值錢的場景。手動擴容要進Dashboard點三四下，API調用只要一個PATCH/apps/{id}/formation，把web進程的quantity從2改到10，響應時間控制在200ms以內。配合監控告警，流量峰值自動橫向擴容， valley期自動縮回來，賬單能砍40%以上。

構建（build）端點解耦了代碼推送和部署。你可以先POST/apps/{id}/builds傳源碼blob URL，Heroku異步打包成slug（可運行鏡像），再通過release端點綁定到dyno。這套流程是藍綠部署的基礎：新版本構建完不立即切換，等健康檢查通過再改formation指向，回滾只要切回上一個slug。

流水線與 add-on（擴展服務）：把環境同步做成腳本

Heroku的流水線（pipeline）把review app、staging、production串成階段。API能做的事包括：創建流水線、把應用關聯到階段、在階段間promote（晉升）代碼。promote操作本質是復制slug，比重新構建快一個數量級，也避免了"staging能跑、production掛掉"的環境漂移。

add-on管理是另一個省時間的場景。數據庫、緩存、消息隊列這些擴展服務，手動配置要填七八個參數，API調用只需要POST/apps/{id}/addons，plan參數指定heroku-postgresql:mini或者redis:mini，30秒后返回連接字符串。批量給10個應用配同樣的add-on，腳本跑一圈比人工點半天靠譜得多。

環境變量同步是常見痛點。staging和production的配置經常對不齊，debug時發現少了個API_KEY能氣死人。用API的/apps/{id}/config-vars端點，可以把源環境的key-value全量讀出，過濾掉敏感項，再批量寫入目標環境。腳本化之后，每周的"配置對齊會"可以直接取消。

CI/CD 集成：把API嵌進GitHub Actions

GitHub Actions的workflow里，Heroku API比官方CLI更靈活。官方action只支持git推送部署，API能讓你做構建-等待-驗證-切換的完整藍綠流程。

典型pipeline分三步：第一步用API創建review app，關聯到PR分支；第二步跑自動化測試；第三步promote到staging，人工確認后再promote到production。全程狀態回寫到GitHub check，失敗自動阻斷合并。

密鑰管理用GitHub Secrets存HEROKU_API_KEY，workflow里注入環境變量。比把密鑰塞Heroku CLI的.netrc文件干凈，也不會泄露在容器層。

調用頻率注意1小時1萬次的硬限制。構建查詢和日志拉取最容易踩雷，建議加指數退避重試，429狀態碼時自動sleep再試。

調試：Heroku的錯誤信息藏著版本號

API返回的錯誤JSON有標準結構：id是錯誤類型標識，message是人類可讀描述，url指向官方文檔。最隱蔽的坑是版本不匹配——如果你忘了加Accept頭，拿到的錯誤格式可能是v2的，字段名完全不同。

日志端點/apps/{id}/log-sessions返回的是臨時URL，5分鐘內有效，指向日志 drains 的聚合流。生產環境建議配外置的日志服務（如Splunk或Datadog），用add-on形式接入，不要依賴Heroku的原生日志API做長期存儲。

狀態碼401不一定是密鑰錯了，可能是token過期或者scope不足。用/oauth/authorizations端點自查token的權限范圍，比盲目重新生成高效。

Heroku在2024年Q4的更新日志里埋了一句話：API調用量同比增長了217%，但主動啟用API的開發者賬戶占比仍不到15%。剩下的85%還在每周花8小時手動點按鈕——如果你的團隊正好在這85%里，第一個問題或許是：你們打算什么時候把那12小時要回來？