內容

名稱

HTTP::Tiny - 一個小巧、簡單、正確的 HTTP/1.1 客户端

版本

版本 0.086

範例

use HTTP::Tiny;

my $response = HTTP::Tiny->new->get('http://example.com/');

die "Failed!\n" unless $response->{success};

print "$response->{status} $response->{reason}\n";

while (my ($k, $v) = each %{$response->{headers}}) {
    for (ref $v eq 'ARRAY' ? @$v : $v) {
        print "$k: $_\n";
    }
}

print $response->{content} if length $response->{content};

說明

這是一個非常簡單的 HTTP/1.1 客户端，用於執行簡單的請求，而不會像 LWP::UserAgent 這樣的大型框架那樣有負擔。

它比 HTTP::Lite 更正確、更完整。它支援代理和重新導向。它也可以在 EINTR 之後正確地繼續執行。

如果安裝了 IO::Socket::IP 0.25 或更高版本，HTTP::Tiny 將使用它來代替 IO::Socket::INET，以透明地支援 IPv4 和 IPv6。

Cookie 支援需要 HTTP::CookieJar 或支援 add 和 cookie_header 方法的等效類別。

方法

new

$http = HTTP::Tiny->new( %attributes );

此建構函式會傳回一個新的 HTTP::Tiny 物件。有效的屬性包括

每個屬性都有存取器/變異器方法。

傳遞明確的 undef 給 proxy、http_proxy 或 https_proxy 會防止從環境取得對應的代理伺服器。

請求執行期間的錯誤將導致偽 HTTP 狀態碼 599 和原因「內部例外」。回應中的內容欄位將包含錯誤文字。

keep_alive 參數啟用持續連線，但僅限於單一目標方案、主機和埠。如果透過存取器修改任何與連線相關的屬性，或如果處理序 ID 或執行緒 ID 變更，持續連線將會中斷。如果你想要跨多個目標建立持續連線，請使用多個 HTTP::Tiny 物件。

有關 verify_SSL 和 SSL_options 屬性的詳細資訊，請參閱 "SSL 支援"。

get|head|put|post|patch|delete

$response = $http->get($url);
$response = $http->get($url, \%options);
$response = $http->head($url);

這些方法是呼叫 request() 的簡寫，用於給定的方法。URL 必須對不安全的字元進行跳脫，並對國際網域名稱進行編碼。有關有效選項和回應說明，請參閱 request()。

如果狀態碼為 2XX，則回應的 success 欄位將為 true。

post_form

$response = $http->post_form($url, $form_data);
$response = $http->post_form($url, $form_data, \%options);

此方法執行 POST 要求，並將表單資料雜湊或陣列參考中的金鑰/值對傳送至給定的 URL，其 content-type 為 application/x-www-form-urlencoded。如果資料以陣列參考提供，則會保留順序；如果以雜湊參考提供，則會根據金鑰和值對詞彙進行排序以確保一致性。有關編碼的詳細資訊，請參閱 www_form_urlencode 方法的文件。

URL 必須對不安全的字元進行跳脫，並對國際網域名稱進行編碼。有關有效選項和回應說明，請參閱 request()。選項雜湊中的任何 content-type 標頭或內容都將被忽略。

如果狀態碼為 2XX，則回應的 success 欄位將為 true。

mirror

$response = $http->mirror($url, $file, \%options)
if ( $response->{success} ) {
    print "$file is up to date\n";
}

針對 URL 執行 GET 要求，並將回應主體儲存至提供的檔案名稱。URL 必須對不安全的字元進行跳脫，並對國際網域名稱進行編碼。如果檔案已存在，則要求將包含 If-Modified-Since 標頭，其中包含檔案的修改時間戳記。你可以在 $options->{headers} 雜湊中自行指定不同的 If-Modified-Since 標頭。

如果狀態碼為 2XX 或 304（未修改），則回應的 success 欄位將為 true。

如果檔案已修改，且伺服器回應包含格式正確的 Last-Modified 標頭，則檔案修改時間將會相應更新。

request

$response = $http->request($method, $url);
$response = $http->request($method, $url, \%options);

在給定的 URL 上執行給定方法類型（'GET'、'HEAD'、'POST'、'PUT' 等）的 HTTP 要求。URL 必須對不安全的字元進行跳脫，並對國際網域名稱進行編碼。

注意：根據 HTTP/1.1 規範，方法名稱區分大小寫。當您實際上需要 GET 時，請勿使用 get。請參閱 限制，了解這如何套用於重新導向。

如果 URL 包含「使用者：密碼」區塊，它們將用於基本型授權標頭。（授權標頭不會包含在重新導向的請求中。）例如

$http->request('GET', 'http://Aladdin:open sesame@example.com/');

如果「使用者：密碼」區塊包含保留字元，則必須以百分比編碼

$http->request('GET', 'http://john%40example.com:password@example.com/');

可以附加選項雜湊值來修改請求。

有效的選項為

Host 標頭根據 RFC 2616 從 URL 產生。在 headers 選項中指定 Host 是致命錯誤。如有必要，其他標頭可能會被忽略或覆寫以符合傳輸規範。

如果 content 選項是程式碼參考，它將被反覆呼叫以提供請求的內容主體。當反覆器用盡時，它應傳回空字串或未定義。

如果 content 選項是空字串，則不會產生 content-type 或 content-length 標頭。

如果提供了 data_callback 選項，它將被反覆呼叫，直到收到整個回應主體。第一個引數將是包含回應主體區塊的字串，第二個引數將是進行中的回應雜湊值參考，如下所述。（這允許根據在內容主體之前收到的 status 或 headers 自訂回呼動作。）

請求/回應中的內容資料以「原始位元組」處理。任何編碼/解碼（包含相關標頭）都由呼叫者負責。

request 方法會傳回包含回應的雜湊參考。雜湊參考會有以下金鑰

如果在執行請求期間發生錯誤，status 欄位會包含 599，而 content 欄位會包含錯誤文字。

www_form_urlencode

$params = $http->www_form_urlencode( $data );
$response = $http->get("http://example.com/query?$params");

此方法會將資料雜湊或陣列參考中的金鑰/值對轉換成 x-www-form-urlencoded 字串。資料參考中的金鑰和值會依據 RFC 3986 編碼成 UTF-8 並轉譯。如果值是陣列參考，金鑰會重複使用陣列參考的每個值。如果資料以雜湊參考提供，結果字串中的金鑰/值對會依據金鑰和值排序，以維持一致的順序。

can_ssl

$ok         = HTTP::Tiny->can_ssl;
($ok, $why) = HTTP::Tiny->can_ssl;
($ok, $why) = $http->can_ssl;

表示 SSL 支援是否可用。當以類別物件呼叫時，會檢查 Net::SSLeay 和 IO::Socket::SSL 的正確版本。當以物件方法呼叫時，如果 SSL_verify 為 true，或如果在 SSL_options 中設定 SSL_verify_mode，會檢查 CA 檔案是否可用。

在標量環境中，傳回一個布林值，表示 SSL 是否可用。在清單環境中，傳回布林值和一個（可能是多行）錯誤字串，表示 SSL 為何不可用。

connected

$host = $http->connected;
($host, $port) = $http->connected;

表示是否根據 keep_alive 選項，與對等端維持連線。

在標量環境中，傳回對等端主機和埠，中間以冒號分隔，或 undef（如果沒有對等端連線）。在清單環境中，傳回對等端主機和埠，或一個空清單（如果沒有對等端連線）。

注意：此方法無法可靠地用於判斷遠端主機是否已關閉其端點的 socket。

TLS/SSL 支援

只有在安裝了 1.56 或更高版本的 IO::Socket::SSL 和 1.49 或更高版本的 Net::SSLeay 時，才支援直接的 https 連線。如果沒有安裝這些模組的較新版本，或 TLS 加密失敗，就會發生錯誤。您也可以使用 HTTP::Tiny::can_ssl() 函式，它會傳回布林值，以查看是否已安裝必要的模組。

可以透過支援 CONNECT 命令（例如 RFC 2817）的 http 代理伺服器建立 https 連線。您可能無法透過本身需要 https 來通訊的代理伺服器，代理 https。

TLS/SSL 提供兩個不同的功能

預設情況下，HTTP::Tiny 會驗證伺服器身分.

由於安全問題，此預設行為已在版本 0.083 中變更。可以透過將 $ENV{PERL_HTTP_TINY_SSL_INSECURE_BY_DEFAULT} 設定為 1，來啟用先前的預設行為。

驗證是透過檢查 TLS/SSL 連線是否具有與連線主機名稱相對應的有效憑證，以及該憑證是否已由 CA 驗證來進行。假設您信任 CA，這將可以防範 中間人攻擊。

憑證驗證需要一個包含受信任 CA 憑證的檔案。

如果環境變數 SSL_CERT_FILE 存在，HTTP::Tiny 會嘗試在該位置尋找 CA 憑證檔案。

如果已安裝 Mozilla::CA 模組，HTTP::Tiny 會使用其附帶的 CA 檔案作為受信任 CA 的來源。

如果該模組不可用，HTTP::Tiny 會搜尋幾個系統特定的預設位置，以尋找 CA 憑證檔案

如果 verify_SSL 為 true 且沒有 CA 憑證檔案可用，將會發生錯誤。

如果您希望完全控制 TLS/SSL 連線，SSL_options 屬性讓您可以提供雜湊參照，該參照將傳遞給 IO::Socket::SSL::start_SSL()，覆寫 HTTP::Tiny 設定的任何選項。例如，提供您自己的受信任 CA 檔案

SSL_options => {
    SSL_ca_file => $file_path,
}

SSL_options 屬性也可以用於提供客戶端憑證以驗證伺服器或控制用於 TLS/SSL 連線的密碼選擇等事項。有關詳細資訊，請參閱 IO::Socket::SSL 文件。

PROXY 支援

HTTP::Tiny 可以代理 http 和 https 要求。僅支援基本代理授權，且必須作為代理 URL 的一部分提供：http://user:pass@proxy.example.com/。

HTTP::Tiny 支援下列代理環境變數

如果設定 REQUEST_METHOD 環境變數，則這可能是 CGI 程序，而 HTTP_PROXY 會從 Proxy: 標頭設定，這是一個安全風險。如果設定 REQUEST_METHOD，則會忽略 HTTP_PROXY（僅限大寫變體），但會考慮 CGI_HTTP_PROXY。

支援使用 CONNECT 方法透過 http 代理通道 https。如果您的代理本身使用 https，您無法透過它通道 https。

請注意，透過代理伺服器代理 https 連線會讓您面臨中間人攻擊的風險。

no_proxy 環境變數以逗號分隔的網域延伸清單格式支援，不應使用代理。

傳遞給 new 的代理引數將覆寫其對應的環境變數。

限制

HTTP::Tiny 有條件地符合 HTTP/1.1 規格

它嘗試符合規格中所有「必須」的要求，但並未實作所有「應該」的要求。(注意：它是根據較早的 RFC 2616 規格開發，可能尚未符合已修正的 RFC 7230-7235 規格。)此外，HTTP::Tiny 支援 RFC 5789 的 PATCH 方法。

一些特別需要注意的限制包括

儘管有上述限制，HTTP::Tiny 仍被視為功能齊全。新的功能要求應導向 HTTP::Tiny::UA。

另請參閱

支援

錯誤 / 功能要求

請透過 https://github.com/chansen/p5-http-tiny/issues 上的問題追蹤器回報任何錯誤或功能要求。您會自動收到關於問題進度的任何通知。

原始碼

這是開放原始碼軟體。程式碼儲存庫可供公開檢閱和根據授權條款提供協助。

https://github.com/chansen/p5-http-tiny

git clone https://github.com/chansen/p5-http-tiny.git

作者

協助者

著作權與授權

此軟體的著作權為 (c) 2023 Christian Hansen 所有。

此為免費軟體；您可以在與 Perl 5 程式語言系統相同的條款下重新散布或修改它。