curl

NB

以下內容均以 113 年末更新至最新的 Windows Server 2022 所自帶的簡易版 curl 命令為基準，在諸 Linux 發行版上 curl 的功能只會更強而非更弱，因此亦應適用。

基本項

• -L 接受 URL 轉址；
• -O 以連結中的名稱（遠端名稱）下載至當前路徑；
• -o "/designated/path/to/designated-filename.ext" 指定儲存至在地的目的路徑及目的檔案名稱；
• --output-dir 指定在地的目的路徑；
• --create-dirs 在使用 -o 或 --output-dir, 或者在連用 -O 與 --output-dir 時，若指定的在地路徑不存在，則需要加寫此項來將其創建；
• -C - 恢復中斷的傳輸（注意 C 後面還有一個橫線，並與前面的 C 中間有一個空格！）；
• -Z 啟用多執行緒並行執行（當連接中採用了 globbing 時會非常有用）；
• --parallel-max n 設定至多多少個執行緒並行執行，預設值為 50;
• -s 靜默執行（螢幕上不顯示任何字樣）；
• -S 顯示錯誤訊息，可與 -s 連用，即為：靜默執行，但在出錯時回報；
• -v 喧鬧執行（螢幕上詳細地顯示與遠端交互的每一步）；
• --connect-timeout n 設定逾時秒數；
• --max-time n 設定該次作業的以秒數計的總計時長上限；
• --rate n/u 設定每單位時間內進行多少次傳輸，其中 u 為時間單位，可為 s, m, 或 h, 如若設定 --rate 3/h, 則表示每小時傳輸 3 次；
• --retry n 設定該次傳輸作業中在遭遇失敗時進行重試的次數（預設值為 0, 也即「失敗不重試」）；
• --retry-max-time n 設定全部重試過程所最大可用的以秒數計的總時長上限；
• --retry-delay n 設定一個固定的失敗與重試間的間隔秒數（預設值為從 1 秒起步，每次翻倍，直至 600 秒為限）；
• --retry-connrefused 設定為即便遭遇「連結被拒絕」也依然重試；以及
• --retry-all-errors 設定為無論遭遇何種錯誤反饋均依然重試。

作業 FTP

• -u username:password 在為作業 FTP 時指定使用者名稱及密碼。在僅使用登入資訊與一處 FTP 網域名稱時，將得到該處 FTP 在使用該使用者登入後所得到的檔案清單，加綴 --list-only 可獲得只有名稱沒有其他細節的清單；
• -T "/local/path/to/the-file.ext" 指定要上載的在地檔案；
• -Q "CMD dir-or-file" 執行指令，一般可見的指令有：
  • -Q "DELE filename.ext" 刪除名為 filename.ext 的檔案；
  • -Q "MKD dirname" 創建名為 dirname 的資料夾；相應地，亦有 -Q "RMD dirname" 用來刪除名為 dirname 的空資料夾，但由於要刪除的資料夾必須為空方可刪除，且 -Q "DELE …" 的用法也有限，因此該指令其實用處不大；以及
  • -Q "RNFR old-filename.ext" -Q "RNTO new-filename.ext" 將原有的 old-filename.ext 檔案重新命名為 new-filename.ext（註：無法透過此方法來移動檔案）；
• 在作業 FTP 伺服器一端時，不可使用 --create-dirs, 因為 --create-dirs 只適用於下載時對在地一方不存在的路徑進行創建；若指定的上載路徑不存在，則需要先——或許可能涉及逐級—— -Q "MKD …" 將指定的路徑創建完畢，再行 -T "…" 傳輸；以及
• 在使用 -Q "CMD …" 執行指令的時候，切記檔案或資料夾名稱部分均不能有空格、不能使用萬用字元或 globbing, 因此所能做到的事情極為有限，只能對單一具名對象進行處理。

URL Globbing

• curl 的 URL Globbing 可能看上去像是 RegEx 或是萬用字元，但它兩者都不是，切勿以 RegEx 的預設思想來寫；
• curl 的 URL Globbing 總的來說有兩種—— [x-y] 和 {a,b,c}, 其中前者表示範圍，後者表示列舉，以下為其用法的詳細說明：
  • 與 RegEx 不同的是，[0-255] 表示從 0 到 255;
  • 如果在範圍末尾加入冒號，寫成形如 [0-255:5] 的樣子，則表示從 0 開始計，每次增量為 5, 也即取 0, 5, 10, … , 255 這 52 個數；
  • 如果寫成 [000-255] 的樣子，則會自動補位；
  • 寫成 [a-z:2] 也是可以的，這樣便會取 a, c, e, … , y 這 13 個字母；
  • {a,b,c} 的用法為單純的列舉，因此沒有甚麼好說的，不過 {a,b,c} 和 [x-y] 可以連用，甚至是多個連用，比如 {alauda,batiola,carruca}-[00-06:2] 就代表取 alauda-02, alauda-04, alauda-06, batiola-02, batiola-04, batiola-06, carruca-02, carruca-04, carruca-06 這九個值；以及
  • 如果連用更多，則被指涉到的檔案就會非常多了，比如 s[01-06]e[01-09].{mp4,srt}, 則理論上可以表示從 s01e01.mp4 到 s06e09.srt 共計 108 個檔案，如果其中有缺失的，則 curl 會自動跳過；
• 雖然叫做 ‘URL Globbing’, 但其實它是用在傳輸過程中的來源的地方的——這在下載過程中自然便是指的下載連結，因此這樣講沒有問題，但是在上載過程中它是可以用在 -T 後面的 "/local/{aleph,bet,gimel}/file[01-10].{ex1,ex2}" 部分的；
• 在下載時，對於儲存至在地的處所之路徑與儲存檔案的名稱，可以使用 #N 來援引在下載連結中透過 URL Globbing 表達的區塊，此處的用法與使用 RegEx 進行取代作業的用法完全一致（只是表示第幾個表達區塊的引導字元不同），比如——
  • 若對 "https://example.com/{aleph,bet,gimel}/img[01-99].{jpg,png,webp}" 進行下載，則 -o 後面可以寫成 "D:\Scatters\#1-#2.#3", 這樣，curl 便會走訪所有可能的組合，並將所有確實存在的連結所對應的檔案都下載到 D:\Scatters\ 中，且儲存下來的檔案名稱會形如 aleph-01.jpg, bet-23.png, 或 gimel-97.webp 的樣子；
• 使用 -g 可在本次傳輸任務中關閉 URL Globbing 功能——這在當 URL 或者上載檔案名稱中包含 [, ], {, 和 } 字元而同時又並不需要使用 URL Globbing 時非常方便；或者
• 如果下載連結或上載檔案名稱中確有包含上述字元而同時又需要使用 URL Globbing 的話，那麼需要將 [ 轉寫為 %5b, ] 轉寫為 %5d, { 轉寫為 %7b, } 轉寫為 %7d ——正常情況下，自瀏覽器拷貝出來的連結都應該是自動完成了這些轉寫的，因此主要適用場合為上載檔案時檔案名稱中含有這些字元，但同時又需要使用 URL Globbing 時。