Zulip REST API 完全使用指南從 API 密鑰、HTTP 認(rèn)證到端點(diǎn)全景【免費(fèi)下載鏈接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/zu/zulipZulip 的 REST API 是驅(qū)動(dòng)其官方 Web 端與移動(dòng)端應(yīng)用的核心接口任何在 Zulip 界面中能完成的操作都可以通過這套 API 以編程方式實(shí)現(xiàn)。本文以倉庫中的 api_docs/rest.md 為骨架系統(tǒng)講解如何獲取 API 密鑰、配置官方語言綁定、發(fā)送帶認(rèn)證的 HTTP 請(qǐng)求、理解統(tǒng)一錯(cuò)誤處理與限流響應(yīng)頭并給出完整端點(diǎn)清單與源碼級(jí)實(shí)現(xiàn)依據(jù)幫助讀者快速構(gòu)建自己的 Zulip 集成與機(jī)器人。一、總覽REST API 是 Zulip 一切功能的外殼根據(jù) rest.mdZulip REST API 直接支撐著 Zulip 官方 Web 應(yīng)用與移動(dòng)應(yīng)用因此凡是你能在 Zulip 里做的事都能通過 REST API 完成。要開始使用這套 API官方給出了四步準(zhǔn)備工作獲取 API 密鑰通常建議創(chuàng)建一個(gè)機(jī)器人bot來持有密鑰除非你是用 API 處理自己的賬號(hào)數(shù)據(jù)例如導(dǎo)出個(gè)人消息歷史。選擇語言可以下載官方的 Python 或 JavaScript 綁定使用社區(qū)維護(hù)的其他語言庫或直接用任意語言發(fā)起 HTTP 請(qǐng)求。構(gòu)造認(rèn)證請(qǐng)求如果自行發(fā)起 HTTP 請(qǐng)求需要按 HTTP 認(rèn)證頭規(guī)范 發(fā)送 HTTP Basic 認(rèn)證信息。理解錯(cuò)誤體系Zulip API 采用統(tǒng)一的 JSON 錯(cuò)誤報(bào)告機(jī)制。各端點(diǎn)的細(xì)節(jié)則由逐端點(diǎn)文檔覆蓋本文第四節(jié)會(huì)給出從 rest-endpoints.md 繼承的完整端點(diǎn)索引。由于 Zulip 是開源的rest.md 還提示任何未收錄于此的用法都可以直接查閱 Zulip 服務(wù)器源碼來確認(rèn)行為——這是官方文檔刻意保留的最終參考。二、身份認(rèn)證與 API 密鑰2.1 什么是 API 密鑰與zuliprc文件根據(jù) api-keys.mdAPI key是用戶或機(jī)器人向 Zulip 標(biāo)識(shí)自己賬號(hào)的方式zuliprc文件則是采用 INI 格式的配置文件以鍵值對(duì)形式存放使用 API 所必需的憑據(jù)例如[api] keybot API key emailbot email address siteZulip servers URL ...對(duì)于官方客戶端尤其是 Python 綁定官方推薦直接下載zuliprc文件使用。2.2 獲取 API 密鑰的兩種場(chǎng)景為機(jī)器人獲取密鑰進(jìn)入組織的機(jī)器人管理界面Settings → Your bots在 Actions 列點(diǎn)擊manage bot圖標(biāo)向下滾動(dòng)到API key區(qū)域點(diǎn)擊復(fù)制圖標(biāo)即可拷貝。官方警告任何持有機(jī)器人 API 密鑰的人都可冒充該機(jī)器人務(wù)必妥善保管。為自己的賬號(hào)獲取密鑰在 Settings → Account privacy 下的API key區(qū)域點(diǎn)擊 Manage your API key輸入密碼后點(diǎn)擊Get API key忘記密碼可先重置。同理個(gè)人密鑰泄露等同于賬號(hào)被他人控制。2.3 使密鑰失效與重新生成要廢棄舊的 API 密鑰唯一方式就是生成新密鑰生成新密鑰的副作用是立即在所有移動(dòng)設(shè)備上注銷該賬號(hào)的登錄態(tài)。機(jī)器人場(chǎng)景在 manage bot 面板點(diǎn)擊generate new API key圖標(biāo)個(gè)人場(chǎng)景則在 Manage your API key 頁面點(diǎn)擊Generate new API key。補(bǔ)充API 層面同樣提供了POST /api/v1/.../regenerate-api-key一類的端點(diǎn)見 rest-endpoints.md 中的 Regenerate your API key 與 Regenerate a bots API key方便通過編程方式輪換密鑰。2.4 下載zuliprc并配置默認(rèn)憑據(jù)機(jī)器人的zuliprc在 manage bot 面板的Zuliprc configuration區(qū)域點(diǎn)擊下載圖標(biāo)下載或復(fù)制其內(nèi)容。個(gè)人的zuliprc在 Manage your API key 頁面點(diǎn)擊Download zuliprc若希望這臺(tái)機(jī)器上所有 Zulip API 調(diào)用默認(rèn)使用該憑據(jù)可把文件移動(dòng)到主目錄~/.zuliprc。2.5zuliprc配置鍵與環(huán)境變量對(duì)照表api-keys.md 給出了完整對(duì)照本文原樣繼承并補(bǔ)充取值說明zuliprc鍵環(huán)境變量必填說明keyZULIP_API_KEY是用戶的 API 密鑰emailZULIP_EMAIL是持有上述密鑰的賬號(hào)郵箱siteZULIP_SITE否Zulip 服務(wù)器 URLclient_cert_keyZULIP_CERT_KEY否綁定用于連接服務(wù)器的 SSL/TLS 私鑰路徑client_certZULIP_CERT否*client_cert_key/ZULIP_CERT_KEY的公共證書部分*設(shè)置了 cert key 時(shí)必填client_bundleZULIP_CERT_BUNDLE否服務(wù)器 PEM 編碼證書的路徑也接受 CA 證書當(dāng)這些 CA 簽發(fā)了服務(wù)器證書時(shí)默認(rèn)使用 Python 內(nèi)置的 CA 包insecureZULIP_ALLOW_INSECURE否允許連接 SSL/TLS 證書無效的 Zulip 服務(wù)器注意開啟會(huì)使 HTTPS 連接不安全默認(rèn)false2.6 Python 綁定的四種配置方式configuring-python-bindings.md 補(bǔ)充說明了 Python 綁定PyPI 上的zulip包的憑據(jù)配置途徑可按場(chǎng)景任選其一通過--config-file命令行參數(shù)或zulip.Client構(gòu)造函數(shù)的config_file選項(xiàng)指定zuliprc文件機(jī)器人場(chǎng)景推薦把zuliprc放到主目錄~/.zuliprc個(gè)人 API key 場(chǎng)景推薦使用上表列出的環(huán)境變量ZULIP_API_KEY、ZULIP_EMAIL、ZULIP_SITE等使用--api-key、--email、--site命令行參數(shù)使用zulip.Client構(gòu)造函數(shù)的api_key、email、site參數(shù)。三、HTTP 層的認(rèn)證與請(qǐng)求規(guī)范3.1Authorization頭HTTP Basic 認(rèn)證HTTP headers 文檔 明確Zulip API 客戶端通過HTTP Basic 認(rèn)證向服務(wù)器標(biāo)識(shí)身份。若使用官方 Python/JavaScript 綁定這一步在配置綁定后即自動(dòng)完成自行構(gòu)造請(qǐng)求時(shí)需注意使用 HTTPBasic認(rèn)證即發(fā)送名為Authorization的請(qǐng)求頭Zulip 的 Basic 認(rèn)證中用戶名是郵箱地址密碼是API 密鑰——即各端點(diǎn) curl 示例中的-u EMAIL_ADDRESS:API_KEY機(jī)器人的憑據(jù)可通過 Web/桌面端的機(jī)器人管理界面獲取或下載其zuliprc若想用密碼換取用戶的 API 密鑰生產(chǎn)環(huán)境流程參見 Fetch an API key 端點(diǎn)說明見 rest-endpoints.md 的 Specialty endpoints 分組。3.2User-Agent頭標(biāo)識(shí)你的集成User-Agent并非強(qiáng)制要求但編寫集成時(shí)強(qiáng)烈建議攜帶——它能讓 Zulip 服務(wù)器識(shí)別具體客戶端與集成用于日志記錄、使用統(tǒng)計(jì)以及極少數(shù)情況下的向后兼容邏輯。官方客戶端與集成的User-Agent以類似ZulipMobile/20.0.103的形式開頭編碼應(yīng)用名與版本號(hào)官方 Python 綁定默認(rèn)User-Agent以ZulipPython/{version}開頭可以通過初始化 Python 綁定時(shí)傳入client參數(shù)給機(jī)器人/集成起名官方 Nagios 集成的寫法即為此例client zulip.Client( config_fileopts.config, clientfZulipNagios/{VERSION} )源碼印證服務(wù)器端對(duì)User-Agent的解析位于 zerver/middleware.py它調(diào)用 zerver/lib/user_agent.py 中的parse_user_agent解析出客戶端name與version該解析器用正則^(?Pname [^/ ]* [^0-9/(]* )從User-Agent提取應(yīng)用名并據(jù)此確定后續(xù)請(qǐng)求歸屬的客戶端類型。3.3 限流響應(yīng)頭X-RateLimit-*為幫助客戶端避免觸達(dá)限流Zulip 在所有 API 響應(yīng)中都會(huì)設(shè)置以下 HTTP 頭X-RateLimit-Remaining該請(qǐng)求類型在觸限前還可發(fā)送的請(qǐng)求數(shù)X-RateLimit-Limit一個(gè)近期未發(fā)起該類型請(qǐng)求的客戶端可用的上限用于設(shè)計(jì)突發(fā)burst行為、避免觸限X-RateLimit-Reset客戶端不再受任何限流限制的時(shí)間點(diǎn)此刻起可再做一批X-RateLimit-Limit次請(qǐng)求。Zulip 的限流規(guī)則本身可配置會(huì)隨服務(wù)器與時(shí)間變化默認(rèn)配置為每個(gè)用戶每分鐘總計(jì) 200 次 API 請(qǐng)求針對(duì)認(rèn)證/登錄嘗試的獨(dú)立且低得多的限制。當(dāng)多個(gè)限流同時(shí)作用于一次請(qǐng)求時(shí)響應(yīng)中返回的是最嚴(yán)格的那條限制對(duì)應(yīng)的值。源碼印證限流頭的實(shí)際寫入位于 zerver/middleware.py 的RateLimitMiddlewareX-RateLimit-Limit取所有生效限流中max_api_calls()的最小值X-RateLimit-Remaining取remaining的最小值X-RateLimit-Reset則取time.time() max(secs_to_freedom)即最晚的恢復(fù)自由時(shí)刻且僅當(dāng)settings.RATE_LIMITING開啟且本次請(qǐng)求確有生效限流時(shí)才附加這些頭。四、統(tǒng)一錯(cuò)誤處理體系4.1 JSON 響應(yīng)與統(tǒng)一字段根據(jù) rest-error-handling.mdZulip API永遠(yuǎn)返回 JSON 格式響應(yīng)HTTP 狀態(tài)碼語義為200 成功4xx 用戶錯(cuò)誤5xx 服務(wù)器錯(cuò)誤。每個(gè)響應(yīng)無論成敗至少包含兩個(gè)鍵msg已國(guó)際化的、人類可讀的錯(cuò)誤消息字符串result取值error或success——與 HTTP 狀態(tài)碼冗余但便于打印調(diào)試。所有錯(cuò)誤響應(yīng)還會(huì)額外包含code機(jī)器可讀的錯(cuò)誤字符串一般性錯(cuò)誤的默認(rèn)值為BAD_REQUEST。4.2 客戶端應(yīng)檢查code而非msg文檔給出關(guān)鍵告誡客戶端判斷具體錯(cuò)誤條件時(shí)應(yīng)始終檢查code而不是msg——因?yàn)閙sg是國(guó)際化的例如用戶是法語 locale 時(shí)服務(wù)器會(huì)返回法文錯(cuò)誤信息依賴msg字符串做判斷會(huì)寫出有 bug 的代碼。若某個(gè)錯(cuò)誤場(chǎng)景需要的信息只存在于msg字符串中集成開發(fā)者應(yīng)推動(dòng)為對(duì)應(yīng)錯(cuò)誤分配專門的code與附加鍵值對(duì)。4.3 錯(cuò)誤code的版本邊界變更記錄在 Zulip 5.0feature level 76之前所有錯(cuò)誤響應(yīng)都不含code鍵code的缺席即表示該錯(cuò)誤尚未分配特定錯(cuò)誤碼。也就是說帶code的錯(cuò)誤響應(yīng)是較新版本服務(wù)器才具備的行為兼容老服務(wù)器時(shí)需注意這一點(diǎn)。4.4 常見錯(cuò)誤響應(yīng)與附加字段除上述通用鍵外部分錯(cuò)誤響應(yīng)還會(huì)攜帶與code相關(guān)的額外鍵值對(duì)具體鍵由錯(cuò)誤碼決定并在對(duì)應(yīng)端點(diǎn)的文檔中說明。此外JSON 成功響應(yīng)中所有 REST 端點(diǎn)都可能返回一個(gè)ignored_parameters_unsupported數(shù)組列出本次請(qǐng)求中該端點(diǎn)不支持的參數(shù)——這在以下情形中屬預(yù)期行為同時(shí)向一個(gè)未知版本的服務(wù)器發(fā)送某參數(shù)的舊名與新名反之這往往意味著客戶端實(shí)現(xiàn)有 bug或客戶端嘗試在不支持該新特性的舊版 Zulip 服務(wù)器上配置新功能。源碼印證ignored_parameters_unsupported的生成邏輯位于 zerver/lib/typed_endpoint.py它取請(qǐng)求POST/GET參數(shù)與端點(diǎn)聲明參數(shù)的差集從而列出被忽略的、不支持的參數(shù)而 zerver/lib/test_classes.py 的測(cè)試輔助方法會(huì)斷言響應(yīng)中該鍵是否存在及內(nèi)容是否與預(yù)期參數(shù)列表一致。五、端點(diǎn)全景從消息到實(shí)時(shí)事件的完整清單rest-endpoints.md 按功能域組織了全部 REST 端點(diǎn)是逐端點(diǎn)文檔的索引。以下完整繼承其結(jié)構(gòu)便于快速定位5.1 消息Messages發(fā)送消息、上傳文件、編輯/刪除消息、獲取消息、構(gòu)造 narrow消息過濾、添加/移除表情反應(yīng)、渲染消息、獲取單條消息、檢查消息是否匹配 narrow、獲取消息編輯歷史、更新個(gè)人消息標(biāo)記、將全部/頻道內(nèi)/主題內(nèi)消息標(biāo)記為已讀、獲取消息已讀回執(zhí)、獲取上傳文件的臨時(shí) URL、檢查縮略圖狀態(tài)、上報(bào)消息。5.2 定時(shí)消息Scheduled messages與提醒Message reminders獲取/創(chuàng)建/編輯/刪除定時(shí)消息創(chuàng)建消息提醒、獲取/刪除提醒。5.3 草稿與導(dǎo)航視圖Drafts / Navigation views獲取/創(chuàng)建/編輯/刪除草稿獲取/創(chuàng)建/編輯/刪除已存片段獲取全部導(dǎo)航視圖、添加/更新/移除導(dǎo)航視圖。5.4 頻道Channels獲取已訂閱頻道、訂閱/退訂頻道、獲取訂閱狀態(tài)、獲取頻道訂閱者、獲取用戶的已訂閱頻道、更新訂閱設(shè)置單個(gè)與批量、獲取全部頻道、按 ID/按名稱獲取頻道、創(chuàng)建/更新/歸檔頻道、獲取頻道郵箱地址、獲取頻道內(nèi)主題、主題靜音、更新某主題的個(gè)人偏好、刪除主題、添加/移除默認(rèn)頻道、創(chuàng)建/獲取/重排/更新頻道文件夾。5.5 用戶Users按 ID/郵箱/自身獲取用戶、獲取用戶列表、創(chuàng)建/更新/停用/重新激活用戶、獲取與更新狀態(tài)、更新個(gè)人資料數(shù)據(jù)、上傳/刪除頭像、設(shè)置正在輸入狀態(tài)、獲取用戶在線狀態(tài)presence并更新、獲取/刪除附件、更新設(shè)置、用戶組獲取/創(chuàng)建/更新/停用/成員管理/子組管理/成員狀態(tài)查詢、靜音/取消靜音用戶、管理提醒詞、重新生成自己的或機(jī)器人的 API 密鑰、獲取機(jī)器人 API 密鑰。5.6 邀請(qǐng)Invitations獲取全部邀請(qǐng)、發(fā)送邀請(qǐng)、創(chuàng)建可復(fù)用邀請(qǐng)鏈接、重發(fā)郵件邀請(qǐng)、撤銷郵件邀請(qǐng)、撤銷可復(fù)用邀請(qǐng)鏈接。5.7 服務(wù)器與組織Server organizations獲取服務(wù)器設(shè)置、鏈接化器linkifiers增刪改查與重排、代碼游樂場(chǎng)playground增刪、自定義表情獲取/上傳/停用、自定義資料字段獲取/重排/創(chuàng)建/更新/刪除、更新 realm 級(jí)用戶設(shè)置默認(rèn)值、域名白名單管理、數(shù)據(jù)導(dǎo)出獲取/創(chuàng)建/獲取同意狀態(tài)/刪除、測(cè)試歡迎機(jī)器人自定義消息、停用組織。5.8 實(shí)時(shí)事件Real-time events實(shí)時(shí)事件 API、注冊(cè)事件隊(duì)列、從事件隊(duì)列取事件、刪除事件隊(duì)列——這是構(gòu)建實(shí)時(shí)客戶端的核心入口。5.9 交互式機(jī)器人Interactive bots獲取/更新/移除機(jī)器人的存儲(chǔ)數(shù)據(jù)。5.10 視頻通話集成Video call integrations創(chuàng)建 BigBlueButton、Constructor Groups、Nextcloud Talk、Webex 視頻通話。5.11 移動(dòng)推送通知Mobile push notifications注冊(cè)登錄設(shè)備、發(fā)送 E2EE 測(cè)試通知、注冊(cè) E2EE 推送設(shè)備含經(jīng) bouncer 的遠(yuǎn)程注冊(cè)、移動(dòng)通知說明、發(fā)送測(cè)試通知、添加/移除 APNs 設(shè)備令牌、添加/移除 FCM 注冊(cè)令牌。5.12 特殊端點(diǎn)Specialty endpoints獲取 API 密鑰生產(chǎn)環(huán)境 / 僅開發(fā)環(huán)境 / JWT 三種流程、列出用戶僅開發(fā)環(huán)境、出站 Webhook 負(fù)載說明。六、語言綁定與安裝6.1 官方庫Pythonpip install zulip同時(shí)提供命令行工具zulip-send官方 Python 庫功能最完整、文檔最完善并內(nèi)置便于編寫交互式機(jī)器人的工具官方優(yōu)先推薦。JavaScriptnpm install zulip-js。需要 curl 時(shí)無需安裝任何庫直接按各端點(diǎn)文檔中的 curl 示例發(fā)送請(qǐng)求即可。6.2 社區(qū)維護(hù)庫與其他語言官方核心團(tuán)隊(duì)維護(hù)的資源有限因此整理了社區(qū)維護(hù)的語言庫清單涵蓋 Clojure、C#、Go、Java、Kotlin、PHP、Ruby、Swift 等語言另有一批未積極維護(hù)的舊庫Lua、Erlang、PHP、Go、Haskell、Chicken Scheme、Scala、EventMachine、Ruby、Perl、.Net——由于 Zulip 核心 API 已穩(wěn)定多年即使是較老的庫也可能可用。完整清單見 client-libraries.md。6.3 調(diào)用未收錄端點(diǎn)call_endpoint若某個(gè)端點(diǎn)未在文檔中收錄Python 綁定提供了通用調(diào)用方法可以使用 Python 綁定的client.call_endpoint方法調(diào)用未收錄的端點(diǎn)示例見 Upload a custom emoji 端點(diǎn)文檔。七、實(shí)戰(zhàn)要點(diǎn)小結(jié)憑據(jù)分層機(jī)器人用專屬zuliprc--config-file/config_file個(gè)人賬號(hào)用~/.zuliprc自動(dòng)化部署可改用ZULIP_API_KEY/ZULIP_EMAIL/ZULIP_SITE環(huán)境變量client_bundle/client_cert/insecure用于自建服務(wù)器與自簽證書場(chǎng)景。認(rèn)證即 Basic-u EMAIL_ADDRESS:API_KEY是裸 HTTP 調(diào)用的唯一認(rèn)證方式務(wù)必用機(jī)器人密鑰而非個(gè)人密碼。錯(cuò)誤處理看code判斷錯(cuò)誤條件只依賴code不依賴會(huì)被國(guó)際化的msg注意老版本服務(wù)器Zulip 5.0 之前無code鍵。限流自適配通過X-RateLimit-Remaining/X-RateLimit-Limit/X-RateLimit-Reset設(shè)計(jì)退避與突發(fā)策略默認(rèn)每用戶每分鐘 200 次 API 請(qǐng)求認(rèn)證端點(diǎn)另有更嚴(yán)限制多個(gè)限流疊加時(shí)取最嚴(yán)格者。參數(shù)兼容檢測(cè)利用成功響應(yīng)中的ignored_parameters_unsupported數(shù)組盡早發(fā)現(xiàn)傳參錯(cuò)誤或新特性連到了老服務(wù)器的問題。開放源碼兜底任何文檔未覆蓋的行為均可直接閱讀 zerver 目錄下的服務(wù)器源碼確認(rèn)——這正是開源項(xiàng)目作為API 最終規(guī)范的價(jià)值所在。相關(guān)閱讀API 密鑰與zuliprc配置 Python 綁定安裝說明Python / JavaScript 綁定HTTP 頭規(guī)范錯(cuò)誤處理規(guī)范端點(diǎn)索引完整清單實(shí)時(shí)事件 API 說明【免費(fèi)下載鏈接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/zu/zulip創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考