ftp

连接到 FTP 服务器以访问其文件

全页展开

说明

通过调用 ftp 函数（用于创建 FTP 连接对象）可连接到 FTP 服务器。然后使用 FTP 连接对象上传和下载文件。您还可以创建、删除和导航到服务器上的不同文件夹。要关闭连接，请使用 close 函数。

由于 FTP 不是安全协议，因此它不会加密您的用户名、密码以及您从 FTP 服务器下载或上传到 FTP 服务器的任何数据。如果您需要安全 FTP 连接，请使用 sftp。

创建对象

语法

ftpobj = ftp(host)
ftpobj = ftp(host,username)
ftpobj = ftp(host,username,password)
ftpobj = ftp(host,username,password,Name,Value)

描述

ftpobj = ftp(host) 打开与 FTP 服务器 host 的连接，并返回 FTP 连接对象。此语法只用于支持匿名（未经身份验证）连接的主机。

示例

ftpobj = ftp(host,username) 使用指定的用户名访问 FTP 帐户。此语法只用于支持匿名（未经身份验证）连接的主机。

ftpobj = ftp(host,username,password) 使用指定的用户名和密码访问 FTP 帐户。

ftpobj = ftp(host,username,password,Name,Value) 使用一个或多个名称-值参量指定选项。例如，您可以将 "System" 指定为 "Windows" 以连接到在 Windows® 操作系统上运行的 FTP 服务器，或将 "LocalDataConnectionMethod" 指定为 "active" 以将连接模式从被动模式更改为主动模式。

输入参量

全部展开

FTP 服务器的主机名，指定为字符串标量或字符向量。

FTP 服务器的默认端口号为 21。要为连接指定备用端口号，请在 host 后面添加冒号 (:) 和端口号。

通常，服务器的主机名以 ftp 开头，如 "ftp.example.com" 中所示。然而，这种做法只是一种约定，而不是技术要求。例如，如果服务器 www.example.com 配置为提供 FTP 服务，则 ftpobj = ftp("www.example.com:20") 会打开与端口号 20 的匿名连接。

您可以在 MATLAB® 保管库或 .env 文件中存储和检索这些敏感信息，而不是对配置数据进行硬编码。有关详细信息，请参阅 Keep Sensitive Information Out of Code。

示例: ftpobj = ftp("ftp.example.com")

FTP 服务器上已授权帐户的名称，指定为字符串标量或字符向量。FTP 对象以纯文本形式发送 username。

已授权帐户的密码，指定为字符串标量或字符向量。FTP 对象以纯文本形式发送 password。

为了提高安全性，请避免对敏感信息（如密码）进行硬编码。有关详细信息，请参阅 Keep Sensitive Information Out of Code。

示例: ftpobj = ftp("ftp.example.com","myusername","mypassword")

名称-值参数

全部展开

以 Name1=Value1,...,NameN=ValueN 的形式指定可选参量对组，其中 Name 是参量名称，Value 是对应的值。名称-值参量必须出现在其他参量之后，但参量对组的顺序无关紧要。

示例: ftpobj = ftp(host,username,password,System="Windows")

在 R2021a 之前，使用逗号分隔每个名称和值，并用引号将 Name 引起来。

示例: ftpobj = ftp(host,username,password,"System","Windows")

FTP 服务器上运行的操作系统的类型，指定为名称-值参量，该对组由 "System" 和 "unix" 或 "Windows" 组成。

FTP 连接对象自动检测服务器的操作系统。

如果没有为 FTP 服务器上运行的操作系统配置 FTP 连接对象，则 FTP dir 函数返回的信息可能会少一些。在这种情况下，dir 可能会返回一个结构体数组，其中的某些字段为空。如果出现这种情况，请再次调用 ftp，并为 "System" 名称-值参量指定正确的值以指定正确的操作系统。

连接模式，指定为名称-值参量，包含 "LocalDataConnectionMethod" 和 "passive" 或 "active"。

可以通过两种模式来建立 FTP 连接。大多数现代 FTP 实现都使用 passive 模式，但要连接到一些旧式服务器，您可能需要指定 active 模式。

  • "passive" - 您的计算机会建立这两个通道。建立命令通道后，您的计算机会请求 FTP 服务器开始侦听某端口，以便您的计算机可以连接到该端口。

  • "active" - 您的计算机为命令建立一个通道，但 FTP 服务器为数据建立一个通道。例如，如果您的计算机受防火墙保护并且不允许来自外部源的未经授权的会话请求，则主动模式可能会出现问题。

从远程服务器读取日期的区域设置，指定为名称-值参量，其中包含 "ServerLocale" 和字符串标量或字符向量。

ServerLocale 值可以为：

  • xx_YY 形式的字符向量或字符串标量，其中 xx 是用于指定语言的小写 ISO 639-1 双字母代码，YY 是用于指定国家/地区的大写 ISO 3166-1 alpha-2 代码。

下表列出了区域设置的某些常用值。

区域设置 语言国家/地区
"de_DE"德语德国
"en_GB"英语英国
"en_US"英语美国
"es_ES"西班牙语西班牙
"fr_FR"法语法国
"it_IT"意大利语意大利
"ja_JP"日语日本
"ko_KR"韩语韩国
"nl_NL"荷兰荷兰
"zh_CN"简体中文中国

如何解析 FTP 服务器的 LIST 命令输出，指定为由 "DirParserFcn" 和函数句柄组成的名称-值参量。默认值为 @matlab.io.ftp.parseDirListingForUnix 或 @matlab.io.ftp.parseDirListingForWindows，具体取决于服务器的操作系统。

一个自定义函数句柄必须有两个输入：

  1. 目录条目列表，指定为字符串向量。

  2. 服务器区域设置，指定为字符串标量。

自定义函数句柄的输出必须是大小为 m×1 的结构体数组，其中 m 是文件夹中的项数。该结构体的字段必须与 dir 函数返回的结构体的字段匹配：name、isdir、bytes、date 和 datenum。有关这些字段的详细信息，请参阅 dir 函数页。

如果默认值导致引用无法解析 dir 输出的错误，请指定此名称-值参量。必须正确指定此参量才能使用引用 dir 的对象函数。

函数签名

自定义写入函数必须接受两个输入参量，即目录条目列表 entries 和服务器区域设置 serverLocale：

function listing = myFormatFcn(entries,serverLocale)

示例函数

将条目联接为一个元胞数组，该元胞数组将作为 textscan 的输入：

function listing = myFormatFcn(entries,serverLocale)
    entries = join(entries,newline);
    out = textscan(entries,"%s%d%3c%d%s","MultipleDelimsAsOne",true);
    structSize = numel(out{1});
预分配结构体：
listing = struct("name",cell(structSize,1),"isdir",zeros(1,1), ...
        "bytes",zeros(1,1),"date",'',"datenum",zeros(1,1));
从 textscan 输出中获取各个部分：
monthName = string(out{3});
    day = string(out{4});
    time = string(out{5});
    names = out{1};
    bytes = out{2};
构造填充适当字段的结构体：
    for ii = 1 : structSize
        listing(ii).name = names{ii};
        listing(ii).isdir = false;
        listing(ii).bytes = bytes(ii);
        makeDate = day(ii) + "-" + monthName(ii) + " " + ...
            time(ii);
        thisDate = datetime(makeDate, "InputFormat", "dd-MMM HH:mm", ...
            "Locale", serverLocale);
        listing(ii).date = datestr(thisDate);
        listing(ii).datenum = datenum(thisDate);    
    end
end

FTP 服务器的传输模式，指定为由 "Mode" 和 "binary" 或 "ascii" 组成的名称-值参量。使用 ASCII 模式处理文本文件，例如 HTML 页面和富文本格式 (RTF) 文件。对非文本文件使用二进制模式，如可执行文件或 zip 存档。

创建 FTP 对象后，使用 ascii 和二元函数更改传输模式。您可能需要更改模式来传输不同类型的文件。传输模式设置会保留到您的 MATLAB 会话结束，或直到您更改它们。

自 R2024b 起

连接允许的最长时间，指定为 duration 标量。默认情况下，连接会在 300 秒后结束。

自 R2024b 起

传输允许的最长时间，指定为 duration 标量。如果不指定值，FTP 传输不会超时。

自 R2024b 起

使用 TLS/SSL 连接到服务器，指定为以下值之一：

  • "none" - 不要使用 TLS/SSL 连接到服务器。在客户端和服务器之间使用纯文本数据传输。

  • "strict" - 确保在客户端和服务器之间建立了 TLS/SSL 连接。如果无法建立 TLS/SSL 连接，则连接会失败并返回错误。

  • "opportunistic" - 尽可能使用 TLS/SSL 连接。如果无法建立 TLS/SSL 连接，则 FTP 连接使用客户端和服务器之间的纯文本数据传输。

TLS（传输层安全性），有时也称为 SSL（安全套接字层），是一种对客户端和服务器之间通信进行加密的安全协议。

注意

安全注意事项：为了提高工作流的安全性，如果您的 FTP 服务器支持 TLS/SSL 连接，请将 TLSMode 指定为 "strict"。

对象函数

ascii将 FTP 传输模式设置为 ASCII
binary将 FTP 传输模式设置为二进制
cd更改或查看 SFTP 或 FTP 服务器上的当前文件夹
close关闭与 SFTP 或 FTP 服务器的连接
delete删除 SFTP 或 FTP 服务器上的文件
dir列出 SFTP 或 FTP 服务器上的文件夹内容
mget从 SFTP 或 FTP 服务器下载文件
mkdir在 SFTP 或 FTP 服务器上创建新文件夹
mput将文件或文件夹上传到 SFTP 或 FTP 服务器
rename重命名 SFTP 或 FTP 服务器上的文件
rmdir删除 SFTP 或 FTP 服务器上的文件夹

示例

全部折叠

打开实时脚本

要打开到 FTP 服务器的连接，请创建 FTP 对象。使用 FTP 对象下载文件并列出服务器上子文件夹的内容。在 FTP 会话结束后，关闭连接。

首先，连接到美国国家环境信息中心 (NCEI) 的 FTP 服务器。 

ftpobj = ftp("ftp.ngdc.noaa.gov")
  FTP with properties:

                         Host: "ftp.ngdc.noaa.gov"
                     Username: "anonymous"
                         Port: 21
                 ServerLocale: "en_US"
                 DirParserFcn: @matlab.io.ftp.parseDirListingForUnix
                         Mode: "binary"
    LocalDataConnectionMethod: "passive"
       RemoteWorkingDirectory: "/"
          CertificateFilename: "default"
            ConnectionTimeout: 5 min
              TransferTimeout: Inf sec

列出 FTP 服务器上顶层文件夹的内容。

dir(ftpobj)
 
DMSP                         INDEX.txt                    README.txt                   STP                          Snow_Ice                     Solid_Earth                  coastwatch                   dmsp4alan                    ftp.html                     geomag                       google12c4c939d7b90761.html  index.html                   international                ionosonde                    mgg                          pub                          wdc

从 FTP 服务器下载 README.txt 文件。mget 函数会下载一个副本到您当前的 MATLAB® 文件夹中。

mget(ftpobj,"README.txt");

使用 readlines 函数读取 README.txt 副本的内容。

readme = readlines("README.txt");
readme(1:4)
ans = 4×1 string
    "                 Welcome to the "
    "    NOAA/National Centers for Environmental Information (NCEI), "
    "    formerly the National Geophysical Data Center (NGDC)"
    "                    FTP area"

使用 dir 函数列出子文件夹的内容。

dir(ftpobj,"STP")
 
ANOMALIES                   DMSP                        ECLIPSE                     GEOMAGNETIC_DATA            GOIN                        GPS_GNSS                    IONOSPHERE                  NOAA                        SEIS                        SGD                         SOLAR_DATA                  SPIDR                       STEP                        SWA                         Solid_Earth                 aavso_22nov16               aeronomy                    cdroms                      goesr                       ionosonde                   log.txt                     publications                satellite_data              space-weather               space_environment_modeling  swpc_products               temp                        tivoli

使用 cd 函数切换到子文件夹。cd 的输出是 FTP 服务器上当前文件夹的路径，而不是当前 MATLAB 文件夹的路径。

cd(ftpobj,"STP/space-weather")
ans = 
'/STP/space-weather'

列出 FTP 服务器上当前文件夹的内容。

dir(ftpobj)
 
aurora-airglow           denig-files              documentation            geomagnetic-data         interplanetary-data      ionospheric-data         online-publications      satellite-data           solar-data               spacecraft-environments

关闭与 FTP 服务器的连接。您也可以通过删除 FTP 对象或让连接超时来关闭连接。

close(ftpobj)

FTP 服务由美国国家环境信息中心 (NCEI) 提供。有关 NCEI 服务条款，请参阅 NCEI 隐私政策、免责声明和版权。

打开实时脚本

连接到美国国家环境信息中心 (NCEI) 的 FTP 服务器。将服务器区域设置指定为英国。使用名称-值参量 "DirParserFcn" 指定要相对于 Windows 解析的 FTP 服务器的 LIST 命令输出。

ftpobj = ftp("ftp.ngdc.noaa.gov","ServerLocale","en_GB","DirParserFcn",@matlab.io.ftp.parseDirListingForWindows)
  FTP with properties:

                         Host: "ftp.ngdc.noaa.gov"
                     Username: "anonymous"
                         Port: 21
                 ServerLocale: "en_GB"
                 DirParserFcn: @matlab.io.ftp.parseDirListingForWindows
                         Mode: "binary"
    LocalDataConnectionMethod: "passive"
       RemoteWorkingDirectory: "/"
          CertificateFilename: "default"
            ConnectionTimeout: 5 min
              TransferTimeout: Inf sec

FTP 服务由美国国家环境信息中心 (NCEI) 提供。有关 NCEI 服务条款，请参阅 NCEI 隐私政策、免责声明和版权。

提示

  • FTP 对象不支持代理服务器设置。

  • 将 ~ 符号传递给 cd 函数以导航到登录文件夹。

版本历史记录

在 R2006a 之前推出

全部展开

另请参阅

| | | |

主题