萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP cURL 呼叫 API 介面完整範例與選項說明

cURL 基本流程

PHP 透過 curl_init() → curl_setopt() 設定選項 → curl_exec() 執行 → curl_close() 關閉,是呼叫 HTTP API 最常用方式。

標準 POST JSON 請求範例

<?php
$url = 'https://api.example.com/v1/order';
$data = ['order_id' => '202401001', 'amount' => 199.00];
$header = [
    'Content-Type: application/json',
    'Authorization: Bearer YOUR_TOKEN',
    'Accept: application/json'
];

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => $url,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($data),
    CURLOPT_HTTPHEADER     => $header,
    CURLOPT_RETURNTRANSFER => true,     // 回傳字串而非直接輸出
    CURLOPT_TIMEOUT        => 10,       // 連線逾時秒數
    CURLOPT_CONNECTTIMEOUT => 5,        // 建立連線逾時
    CURLOPT_SSL_VERIFYPEER => true,     // 驗證 SSL 憑證 (生產必開)
    CURLOPT_SSL_VERIFYHOST => 2,
    // CURLOPT_CAINFO       => '/path/to/cacert.pem', // 若驗證失敗指定 CA 憑證
]);

$response = curl_exec($ch);
$errno = curl_errno($ch);
$error = curl_error($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($errno) {
    error_log("cURL Error [$errno]: $error");
    // 處理失敗...
}

$result = json_decode($response, true);
if ($httpCode >= 200 && $httpCode < 300) {
    // 成功處理 $result
} else {
    // 依 $httpCode 處理錯誤
}
?>

常用選項分類速查

類別選項說明
行為控制CURLOPT_RETURNTRANSFERtrue 回傳字串,false 直接輸出
CURLOPT_FOLLOWLOCATIONtrue 跟隨 3xx 重導向
CURLOPT_MAXREDIRS最大重導向次數 (預設 20)
CURLOPT_AUTOREFERER重導向時自動帶 Referer
CURLOPT_FAILONERRORtrue 時 HTTP ≥400 視為失敗
CURLOPT_TIMEOUT總執行逾時秒數
CURLOPT_CONNECTTIMEOUT建立連線逾時秒數
CURLOPT_NOSIGNAL多線程環境必開 (避免信號衝突)
請求設定CURLOPT_POSTtrue 發送 POST
CURLOPT_POSTFIELDSPOST 資料 (陣列→multipart, 字串→application/x-www-form-urlencoded)
CURLOPT_HTTPHEADER自定標頭陣列
CURLOPT_USERAGENTUser-Agent 字串
CURLOPT_COOKIE攜帶 Cookie 字串
CURLOPT_COOKIEJAR/FILE儲存/讀取 Cookie 檔案
SSL/安全CURLOPT_SSL_VERIFYPEER驗證對端憑證 (生產必 true)
CURLOPT_SSL_VERIFYHOST2=驗證 CN/SubjectAltName 匹配主機名
CURLOPT_CAINFOCA 憑證束路徑
CURLOPT_SSLCERT/KEY客戶端憑證 (雙向 TLS)
CURLOPT_PROXY代理伺服器 ip:port

進階:GET 請求、檔案上傳、多執行緒併發

<?php
// GET with query string
$ch = curl_init("$url?" . http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// 檔案上傳 (PHP 5.5+ 使用 CURLFile)
$post = ['file' => new CURLFile('/path/to/file.png', 'image/png', 'filename.png')];
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);

// 並發請求 (curl_multi)
$mh = curl_multi_init();
$handles = [];
foreach ($urls as $u) {
    $ch = curl_init($u);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_multi_add_handle($mh, $ch);
    $handles[] = $ch;
}
$running = null;
do { curl_multi_exec($mh, $running); } while ($running);
foreach ($handles as $ch) {
    $result = curl_multi_getcontent($ch);
    curl_multi_remove_handle($mh, $ch);
}
curl_multi_close($mh);
?>

錯誤處理最佳實踐

  • 永遠檢查 curl_errno() 與 curl_getinfo($ch, CURLINFO_HTTP_CODE)。
  • 設定合理 CURLOPT_TIMEOUT 避免阻塞。
  • 記錄請求/回應 (隱藏敏感欄位) 供除錯。
  • 重試策略:指數退避 + 亂數抖動,僅重試冪等操作 (GET、PUT、DELETE)。
copyright © 萬盛學電腦網 all rights reserved