跳到内容
Esc
↑↓导航↵打开⌘J预览
本页内容

CLI

@billionsend/cli 讓你在終端機裡把電子郵件服務帳號遷移到 BillionSend。

@billionsend/cli 用來把電子郵件服務帳號遷移到 BillionSend。它讀取來源帳號,與你的帳號比對,套用差異並寫出報告。目前唯一支援的來源是 Resend。逐步指南見從 Resend 遷移。套件是 npm 上的 @billionsend/cli,原始碼在 GitHub 的 billionsend/billionsend-cli。

安裝

需要 Node 18 或更新版本。不必安裝,直接執行:

npx @billionsend/cli migrate --from resend

也可以一次性安裝:

npm install -g @billionsend/cli
billionsend --version

指令

billionsend migrate --from resend                          # 連線、選擇資源、產生計畫、確認、套用
billionsend migrate plan --from resend [--out plan.json]   # 唯讀:結束碼 0 表示無須處理,2 表示有變更,1 表示出錯
billionsend migrate apply [plan.json] [--yes]              # 套用已儲存的計畫,或一次完成產生與套用
billionsend migrate status                                 # 上一次執行建立了什麼,還剩什麼
billionsend migrate rollback [--yes]                       # 只刪除這個工具建立的內容
  • migrate 是互動式路徑。它會詢問缺少的內容(金鑰),讓你選擇資源,顯示計畫,請你確認,然後套用並列印摘要。
  • migrate plan 顯示將會發生的變更,不寫入任何內容。在任何寫入之前,它會透過 GET /usage 檢查你方案的限額,並說明哪些放不下,例如「7 domains to create; the Free plan allows 3」。它還會估算所需時間。
  • migrate apply 套用已儲存的計畫,或一次完成產生與套用。聯絡人依電子郵件地址配對。其他一切依名稱、鍵、端點或別名配對,不同就更新,相同就保持不動。
  • migrate status 顯示上一次執行建立了什麼,以及檢查清單上還剩什麼。它不需要金鑰。
  • migrate rollback 只刪除這個工具建立的內容,絕不碰只是被它更新過的資料列。它會先列印清單並詢問(--yes 可略過詢問)。

參數

參數 含義
--from <provider> 來源服務商。目前只有 resend。
--from-key-stdin 從 stdin 讀取來源 API 金鑰(第一行)。
--from-key <key> 以參數形式傳入來源 API 金鑰。程序清單裡看得到,所以建議用環境變數。
--to-url <url> BillionSend API 位址。預設 https://api.billionsend.com。
--to-key-stdin 從 stdin 讀取 BillionSend API 金鑰(兩個 stdin 參數都設定時為第二行)。
--to-key <key> 以參數形式傳入 BillionSend API 金鑰。同樣要留意上面的問題。
--rps <n> 對來源服務的每秒請求數。預設 8,最大 100。Resend 的限額是 10,並與你的正式環境傳送共用。只有在 Resend 提高了你的限額之後,才可以超過 10。
--only <a,b> 只遷移這些資源。
--skip <a,b> 略過這些資源。
--on-conflict <mode> 對已存在的聯絡人:upsert(預設)、skip 或 error。
--include-sent 把已寄出的群發以草稿匯入。預設略過。
--fresh-webhook-secrets 建立新的 Webhook 簽章金鑰,而不是複製舊的。只會在報告裡顯示一次。
--fresh 捨棄續傳進度,重新讀取全部內容。先前執行建立的內容會保留,所以 rollback 仍然可用。
--out <file> migrate plan:把計畫寫成 JSON。
--report <file> 同時把 Markdown 報告寫到這個路徑。
-y、--yes 略過確認。
--non-interactive 從不提問。缺少輸入時以 1 結束。stdin 不是終端機時,以及使用 --json 時會自動啟用。
--json stdout 輸出 JSON,進度輸出到 stderr。
-v、--verbose 記錄每一次請求。
--color <mode>、--no-color auto(預設)、always 或 never。
-h、--help / -V、--version 說明與版本。

--only 與 --skip 可用的資源,依套用順序為:domains、properties、topics、segments、contacts、enrichment、broadcasts、templates、webhooks、suppressions、api-keys。enrichment 是第二輪,用來讀取每位聯絡人的訂閱主題與屬性。

環境變數

變數 含義
RESEND_API_KEY 來源 API 金鑰,完整存取。
BILLIONSEND_API_KEY 你的 BillionSend API 金鑰,完整存取。
BILLIONSEND_BASE_URL BillionSend API 位址,與 --to-url 相同。
NO_COLOR 關閉顏色。
FORCE_COLOR 即使經過管線也輸出顏色。

每把金鑰依這個順序尋找:環境變數、-stdin 參數、命令列參數,最後在終端機裡跳出隱藏輸入的提示。

檔案

工具會把這些檔案寫在你執行它的位置旁邊,只有你自己可讀,其中絕不包含金鑰:

檔案 內容
.billionsend/migrate-state.json 工具建立了什麼、停在哪裡,這樣中斷的執行可以繼續。
.billionsend/migrate-report.json 上一次執行的報告,資料格式。
.billionsend/migrate-report.md 同一份報告的 Markdown 版:數量、檢查清單、每個網域的 DNS 記錄、id 對照表(來源端的訂閱主題與分群 id 對應到 BillionSend 的 id)以及手動事項。

目前目錄裡有 .gitignore 時,.billionsend/ 會被加進去。

安全

  • 只讀取 Resend。 對 Resend 的每個請求都是 GET。寫入只送往你的 BillionSend API。
  • 金鑰只留在記憶體裡,並且會從每一行日誌中隱去。沒有遙測,也不檢查更新。
  • 遇到 401 或 403 就停止。 工具不會重試,也不會繞過。
  • 遵守速率限制。 遇到 429 時會等待 retry-after。遇到伺服器或網路錯誤時,會以逐漸加長的間隔最多重試 5 次。
  • 保留退訂狀態。 unsubscribed 與訂閱主題的退訂原樣複製,不會讓任何人重新訂閱。見退訂。

結束碼

結束碼 含義
0 成功;對 migrate plan 來說,表示無須處理。
1 錯誤:參數有誤、缺少輸入、金鑰被拒絕。
2 僅 migrate plan:計畫裡有變更。
3 部分完成:有些項目失敗。見報告。

腳本與 CI

stdin 不是終端機,或者使用了 --non-interactive 或 --json 時,工具從不提問。缺少輸入時以 1 結束,並指出需要設定的變數或參數。請透過環境變數或 stdin 傳入金鑰,不要當作參數傳入:

export RESEND_API_KEY=re_...
export BILLIONSEND_API_KEY=bs_...

billionsend migrate plan --from resend --out plan.json
# 結束碼 2 表示有內容需要套用
billionsend migrate apply plan.json --yes

使用 --json 時,stdout 只輸出 JSON(migrate plan 輸出計畫,migrate apply 輸出報告),可以直接接上管線:

billionsend migrate plan --from resend --json | jq '.counts'

Resend 是 Plus Five Five, Inc. 的註冊商標。BillionSend 與 Resend 無關聯,也未獲其背書。

这个页面有帮助吗?