WebHDFS REST API

文档约定

等宽字体 用于命令、HTTP 请求和响应以及代码块。
<等宽字体> 用户输入的值。
[等宽字体] 可选值。当未指定值时，将使用默认值。
斜体 重要的短语和单词。

简介

HTTP REST API 支持 HDFS 的完整 FileSystem/FileContext 接口。操作和相应的 FileSystem/FileContext 方法将在下一部分中显示。部分 HTTP 查询参数词典 指定了参数详细信息，例如默认值和有效值。

操作

文件系统 URI 与 HTTP URL

WebHDFS 的文件系统方案为 “webhdfs://”。WebHDFS 文件系统 URI 具有以下格式。

  webhdfs://<HOST>:<HTTP_PORT>/<PATH>

上述 WebHDFS URI 对应于以下 HDFS URI。

  hdfs://<HOST>:<RPC_PORT>/<PATH>

在 REST API 中，前缀 “/webhdfs/v1” 会插入路径中，并追加查询。因此，相应的 HTTP URL 具有以下格式。

  http://<HOST>:<HTTP_PORT>/webhdfs/v1/<PATH>?op=...

注意，如果 WebHDFS 使用 SSL 保护，则方案应为 “swebhdfs://”。

  swebhdfs://<HOST>:<HTTP_PORT>/<PATH>

另请参阅：SWebHDFS 的 SSL 配置

HDFS 配置选项

以下是 WebHDFS 的 HDFS 配置选项。

属性名称 说明
dfs.web.authentication.kerberos.principal HTTP 端点中 Hadoop-Auth 使用的 HTTP Kerberos 主体。根据 Kerberos HTTP SPNEGO 规范，HTTP Kerberos 主体必须以“HTTP/”开头。值 “*” 将使用密钥表中找到的所有 HTTP 主体。
dfs.web.authentication.kerberos.keytab Hadoop-Auth 在 HTTP 端点中使用的 HTTP Kerberos 主体的 Kerberos 密钥表文件，其中包含凭据。
dfs.webhdfs.socket.connect-timeout 在失败之前等待建立连接的时间长度。指定为时间持续时间，即数字值后跟单位符号，例如 2m 表示两分钟。默认为 60s。
dfs.webhdfs.socket.read-timeout 在数据到达之前等待的时间长度，否则失败。默认为 60s。

身份验证

当安全性为 off 时，经过身份验证的用户是 user.name 查询参数中指定的用户名。如果未设置 user.name 参数，服务器可能会将经过身份验证的用户设置为默认 Web 用户（如果有），或者返回错误响应。

当安全性为 on 时，身份验证通过 Hadoop 委派令牌或 Kerberos SPNEGO 执行。如果在 delegation 查询参数中设置了令牌，则经过身份验证的用户是令牌中编码的用户。如果未设置 delegation 参数，则用户通过 Kerberos SPNEGO 进行身份验证。

以下是使用 curl 命令工具的示例。

  1. 安全性关闭时的身份验证

    curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?[user.name=<USER>&]op=..."

  2. 安全性开启时使用 Kerberos SPNEGO 进行身份验证

    curl -i --negotiate -u : "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=..."

  3. 安全性开启时使用 Hadoop 委派令牌进行身份验证

    curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?delegation=<TOKEN>&op=..."

另请参阅：Hadoop HTTP Web 控制台的身份验证

此外，WebHDFS 在客户端支持 OAuth2。NameNode 和 DataNode 目前不支持使用 OAuth2 的客户端，但实现 WebHDFS REST 接口的其他后端可能会支持。

默认情况下，WebHDFS 支持两种类型的 OAuth2 代码授权（用户提供的刷新和访问令牌或用户提供的凭据），并提供了一种可插入的机制来实现其他 OAuth2 身份验证，具体请参阅 OAuth2 RFC 或自定义身份验证。使用任一提供的代码授权机制时，WebHDFS 客户端会根据需要刷新访问令牌。

OAuth2 应仅对不使用 Kerberos SPENGO 运行的客户端启用。

OAuth2 代码授权机制 说明 实现代码授权的 dfs.webhdfs.oauth2.access.token.provider 的值
授权码授权 用户提供初始访问令牌和刷新令牌，然后分别使用它们来验证 WebHDFS 请求并获取替换访问令牌。 org.apache.hadoop.hdfs.web.oauth2.ConfRefreshTokenBasedAccessTokenProvider
客户端凭据授权 用户提供用于获取访问令牌的凭据，然后使用这些凭据来验证 WebHDFS 请求。 org.apache.hadoop.hdfs.web.oauth2.ConfCredentialBasedAccessTokenProvider

以下属性控制 OAuth2 身份验证。

OAuth2 相关属性 说明
dfs.webhdfs.oauth2.enabled 启用/禁用 OAuth2 身份验证的布尔值
dfs.webhdfs.oauth2.access.token.provider org.apache.hadoop.hdfs.web.oauth.AccessTokenProvider 实现的类名。如上所述，代码中提供了两个，或者用户可以指定用户提供的实现。此配置键的默认值是 ConfCredentialBasedAccessTokenProvider 实现。
dfs.webhdfs.oauth2.client.id 用于通过凭证或刷新令牌获取访问令牌的客户端 ID
dfs.webhdfs.oauth2.refresh.url 用于发布以通过凭证或刷新令牌获取持有者令牌的 URL
dfs.webhdfs.oauth2.access.token （如果使用 ConfRefreshTokenBasedAccessTokenProvider，则必需）用于身份验证的初始访问令牌
dfs.webhdfs.oauth2.refresh.token （如果使用 ConfRefreshTokenBasedAccessTokenProvider，则必需）用于获取新访问令牌的初始刷新令牌
dfs.webhdfs.oauth2.refresh.token.expires.ms.since.epoch （如果使用 ConfRefreshTokenBasedAccessTokenProvider，则必需）自 1970 年 1 月 1 日以来的毫秒数来衡量访问令牌到期时间。请注意，此值与 OAuth 提供商提供的值不同，并且已按照接口中所述进行整理，以便适合客户端应用程序
dfs.webhdfs.oauth2.credential （如果使用 ConfCredentialBasedAccessTokenProvider，则必需）。用于获取初始和后续访问令牌的凭证。

SWebHDFS 的 SSL 配置

要使用 SWebHDFS 文件系统（即使用 swebhdfs 协议），需要在客户端指定 SSL 配置文件。这必须指定 3 个参数

SSL 属性 说明
ssl.client.truststore.location 包含 NameNode 证书的信任库文件的本地文件系统位置。
ssl.client.truststore.type （可选）信任库文件的格式。
ssl.client.truststore.password （可选）信任库文件的密码。

以下是一个示例 SSL 配置文件 (ssl-client.xml)

<configuration>
  <property>
    <name>ssl.client.truststore.location</name>
    <value>/work/keystore.jks</value>
    <description>Truststore to be used by clients. Must be specified.</description>
  </property>

  <property>
    <name>ssl.client.truststore.password</name>
    <value>changeme</value>
    <description>Optional. Default value is "".</description>
  </property>

  <property>
    <name>ssl.client.truststore.type</name>
    <value>jks</value>
    <description>Optional. Default value is "jks".</description>
  </property>
</configuration>

SSL 配置文件必须在客户端程序的类路径中，并且文件名需要在 core-site.xml 中指定

<property>
  <name>hadoop.ssl.client.conf</name>
  <value>ssl-client.xml</value>
  <description>
    Resource file from which ssl client keystore information will be extracted.
    This file is looked up in the classpath, typically it should be in Hadoop
    conf/ directory. Default value is "ssl-client.xml".
  </description>
</property>

代理用户

启用代理用户功能后，代理用户 P 可以代表另一个用户 U 提交请求。U 的用户名必须在 doas 查询参数中指定，除非在身份验证中提供了委派令牌。在这种情况下，用户 P 和 U 的信息必须编码在委派令牌中。

  1. 在安全性关闭时进行代理请求

    curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?[user.name=<USER>&]doas=<USER>&op=..."

  2. 在安全性开启时使用 Kerberos SPNEGO 进行代理请求

    curl -i --negotiate -u : "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?doas=<USER>&op=..."

  3. 在安全性开启时使用 Hadoop 委派令牌进行代理请求

    curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?delegation=<TOKEN>&op=..."

跨站点请求伪造防护

WebHDFS 支持针对跨站请求伪造 (CSRF) 预防的可选可配置机制。启用后，对 NameNode 或 DataNode 的 WebHDFS HTTP 请求必须包含自定义 HTTP 头。配置属性允许调整受保护的特定 HTTP 方法和 HTTP 头的名称。头中发送的值无关紧要。只需要以该名称存在头。

启用 CSRF 预防还会设置 WebHdfsFileSystem 类以发送所需的标头。这确保了 CLI 命令（如 hdfs dfs 和 hadoop distcp）在与 webhdfs: URI 一起使用时继续正常工作。

启用 CSRF 预防还会设置 NameNode Web UI 以发送所需的标头。在启用 CSRF 预防并重新启动 NameNode 后，NameNode Web UI 的现有用户需要刷新浏览器以重新加载页面并找到新配置。

以下属性控制 CSRF 预防。

属性 说明 默认值
dfs.webhdfs.rest-csrf.enabled 如果为 true，则启用 WebHDFS 针对跨站请求伪造 (CSRF) 的保护。WebHDFS 客户端还使用此属性来确定是否需要在其 HTTP 请求中发送自定义 CSRF 预防标头。 false
dfs.webhdfs.rest-csrf.custom-header 当通过将 dfs.webhdfs.rest-csrf.enabled 设置为 true 为 WebHDFS 启用针对跨站请求伪造 (CSRF) 的保护时，HTTP 请求必须发送的自定义标头的名称。WebHDFS 客户端还使用此属性来确定是否需要在其 HTTP 请求中发送自定义 CSRF 预防标头。 X-XSRF-HEADER
dfs.webhdfs.rest-csrf.methods-to-ignore 当通过将 dfs.webhdfs.rest-csrf.enabled 设置为 true 为 WebHDFS 启用针对跨站请求伪造 (CSRF) 的保护时，不需要 HTTP 请求包含自定义标头的 HTTP 方法的逗号分隔列表。WebHDFS 客户端还使用此属性来确定是否需要在其 HTTP 请求中发送自定义 CSRF 预防标头。 GET,OPTIONS,HEAD,TRACE
dfs.webhdfs.rest-csrf.browser-useragents-regex 当通过将 dfs.webhdfs.reset-csrf.enabled 设置为 true 为 WebHDFS 启用针对跨站请求伪造 (CSRF) 的保护时，用于与 HTTP 请求的 User-Agent 标头匹配的逗号分隔的正则表达式列表。如果传入的 User-Agent 与任何这些正则表达式匹配，则该请求被认为是由浏览器发送的，因此强制执行 CSRF 预防。如果请求的 User-Agent 与任何这些正则表达式都不匹配，则该请求被认为是由浏览器以外的其他内容（例如脚本自动化）发送的。在这种情况下，CSRF 不是潜在的攻击媒介，因此不强制执行预防措施。这有助于实现与尚未更新为发送 CSRF 预防标头而存在的自动化程序的向后兼容性。 ^Mozilla.*,^Opera.*
dfs.datanode.httpserver.filter.handlers 要注入到 Datanode WebHDFS I/O 路径中的 Netty servlet 样式过滤器处理程序的逗号分隔列表 org.apache.hadoop.hdfs.server.datanode.web.RestCsrfPreventionFilterHandler

以下是一个使用 -H 选项在请求中包含自定义标头的示例 curl 调用。

    curl -i -L -X PUT -H 'X-XSRF-HEADER: ""' 'http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=CREATE'

WebHDFS 重试策略

WebHDFS 支持可选的可配置重试策略，用于可能超时的大文件的弹性复制，或在复制期间可能发生故障切换的高可用性群集之间的文件复制。

以下属性控制 WebHDFS 重试和故障切换策略。

属性 说明 默认值
dfs.http.client.retry.policy.enabled 如果为“true”，则启用 WebHDFS 客户端的重试策略。如果为“false”，则关闭重试策略。 false
dfs.http.client.retry.policy.spec 为 WebHDFS 客户端指定一个多线性随机重试策略，例如，给定重试次数和睡眠时间 (n0, t0)、(n1, t1)、… 的对，前 n0 次重试平均睡眠 t0 毫秒，接下来的 n1 次重试平均睡眠 t1 毫秒，依此类推。 10000,6,60000,10
dfs.http.client.failover.max.attempts 在发生网络异常的情况下，为 WebHDFS 客户端指定最大故障切换尝试次数。 15
dfs.http.client.retry.max.attempts 为 WebHDFS 客户端指定最大重试尝试次数，如果重试尝试次数与故障切换尝试次数的差值大于最大重试尝试次数，则将不再重试。 10
dfs.http.client.failover.sleep.base.millis 为 WebHDFS 客户端指定基本时间量（以毫秒为单位），在此基础上计算重试或故障切换之间的指数增加的睡眠时间。 500
dfs.http.client.failover.sleep.max.millis 为 WebHDFS 客户端指定重试或故障切换之间的睡眠时间上限（以毫秒为单位）。 15000

WebHDFS 请求筛选

人们可以控制 WebHDFS 协议中数据的方向性，仅允许从不安全的网络写入数据。要启用，必须确保 dfs.datanode.httpserver.filter.handlers 包括 org.apache.hadoop.hdfs.server.datanode.web.HostRestrictingAuthorizationFilterHandler。HostRestrictingAuthorizationFilter 的配置通过以下属性控制。

属性 说明 默认值
dfs.datanode.httpserver.filter.handlers 要注入到 Datanode WebHDFS I/O 路径中的 Netty servlet 样式过滤器处理程序的逗号分隔列表 org.apache.hadoop.hdfs.server.datanode.web.RestCsrfPreventionFilterHandler
dfs.web.authentication.host.allow.rules 允许用户以 user、network/bits、path glob 换行符或 | 分隔的格式读取文件的规则。对所有 user 或 network/bits 使用 * 作为通配符。 无 - 默认情况下，没有人可以通过 WebHDFS 读取

文件和目录操作

创建并写入文件

  • 步骤 1：提交一个 HTTP PUT 请求，不自动跟随重定向，也不发送文件数据。

    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=CREATE
                    [&overwrite=<true |false>][&blocksize=<LONG>][&replication=<SHORT>]
                    [&permission=<OCTAL>][&buffersize=<INT>][&noredirect=<true|false>]"

    通常，该请求会被重定向到一个数据节点，文件数据将被写入其中。

    HTTP/1.1 307 TEMPORARY_REDIRECT
Location: http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=CREATE...
Content-Length: 0

    但是，如果你不想自动重定向，你可以设置 noredirect 标志。

    HTTP/1.1 200 OK
Content-Type: application/json
{"Location":"http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=CREATE..."}

  • 步骤 2：使用 Location 标头中的 URL（或在你指定 noredirect 的情况下返回的响应）提交另一个 HTTP PUT 请求，其中包含要写入的文件数据。

    curl -i -X PUT -T <LOCAL_FILE> "http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=CREATE..."

    客户端会收到一个 201 Created 响应，内容长度为零，以及 Location 标头中文件的 WebHDFS URI。

    HTTP/1.1 201 Created
Location: webhdfs://<HOST>:<PORT>/<PATH>
Content-Length: 0

    如果没有指定权限，新创建的文件将被分配默认的 644 权限。服务器端不会应用 umask 模式（因此，在 NameNode 端设置的“fs.permissions.umask-mode”值配置将不起作用）。

注意，采用两步创建/追加的原因是为了防止客户端在重定向之前发送数据。HTTP/1.1 中的“Expect: 100-continue”标头解决了此问题；请参阅 RFC 2616，第 8.2.3 节。不幸的是，有些软件库存在缺陷（例如，Jetty 6 HTTP 服务器和 Java 6 HTTP 客户端），它们无法正确实现“Expect: 100-continue”。两步创建/追加是针对软件库缺陷的临时解决方法。

另请参阅：overwrite、blocksize、replication、permission、buffersize、FileSystem.create

追加到文件

  • 步骤 1：提交一个 HTTP POST 请求，不自动跟随重定向，也不发送文件数据。
    curl -i -X POST "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=APPEND[&buffersize=<INT>][&noredirect=<true|false>]"

    通常，该请求会被重定向到一个数据节点，文件数据将被追加到其中。

    HTTP/1.1 307 TEMPORARY_REDIRECT
Location: http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=APPEND...
Content-Length: 0

但是，如果你不想自动重定向，你可以设置 noredirect 标志。

    HTTP/1.1 200 OK
    Content-Type: application/json
    {"Location":"http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=APPEND..."}
  • 步骤 2：使用 Location 标头中的 URL（或在你指定 noredirect 的情况下返回的响应）提交另一个 HTTP POST 请求，其中包含要追加的文件数据。
    curl -i -X POST -T <LOCAL_FILE> "http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=APPEND..."

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

请参阅上一部分中的说明，了解此操作为何需要两步。

另请参阅：buffersize、FileSystem.append

连接文件

  • 提交一个 HTTP POST 请求。
    curl -i -X POST "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=CONCAT&sources=<PATHS>"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：sources、FileSystem.concat

打开并读取文件

  • 提交一个自动跟随重定向的 HTTP GET 请求。
    curl -i -L "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=OPEN
                    [&offset=<LONG>][&length=<LONG>][&buffersize=<INT>][&noredirect=<true|false>]"

    通常，该请求会被重定向到一个数据节点，文件数据可以在其中读取。

    HTTP/1.1 307 TEMPORARY_REDIRECT
Location: http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=OPEN...
Content-Length: 0

    但是，如果您不想自动重定向，可以设置 noredirect 标志。

    HTTP/1.1 200 OK
Content-Type: application/json
{"Location":"http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=OPEN..."}

    客户端遵循重定向到数据节点并接收文件数据

    HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: 22

Hello, webhdfs user!

另请参阅：offset、length、buffersize、FileSystem.open

创建目录

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=MKDIRS[&permission=<OCTAL>]"

    客户端收到带有 boolean JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{"boolean": true}

    如果未指定权限，新创建的目录将默认具有 755 权限。服务器端不会应用 umask 模式（因此，在 NameNode 端设置的 “fs.permissions.umask-mode” 值配置将不起作用）。

另请参阅：permission、FileSystem.mkdirs

创建符号链接

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=CREATESYMLINK
                              &destination=<PATH>[&createParent=<true |false>]"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：destination、createParent、FileSystem.createSymlink

重命名文件/目录

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "<HOST>:<PORT>/webhdfs/v1/<PATH>?op=RENAME&destination=<PATH>"

    客户端收到带有 boolean JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{"boolean": true}

另请参阅：destination、FileSystem.rename

删除文件/目录

  • 提交 HTTP DELETE 请求。
    curl -i -X DELETE "http://<host>:<port>/webhdfs/v1/<path>?op=DELETE
                              [&recursive=<true |false>]"

    客户端收到带有 boolean JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{"boolean": true}

另请参阅：recursive、FileSystem.delete

截断文件

  • 提交一个 HTTP POST 请求。
    curl -i -X POST "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=TRUNCATE&newlength=<LONG>"

    客户端收到带有 boolean JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{"boolean": true}

另请参阅：newlength、FileSystem.truncate

文件/目录状态

  • 提交 HTTP GET 请求。
    curl -i  "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETFILESTATUS"

    客户端收到带有 FileStatus JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{
  "FileStatus":
  {
    "accessTime"      : 0,
    "blockSize"       : 0,
    "group"           : "supergroup",
    "length"          : 0,             //in bytes, zero for directories
    "modificationTime": 1320173277227,
    "owner"           : "webuser",
    "pathSuffix"      : "",
    "permission"      : "777",
    "replication"     : 0,
    "snapshotEnabled" : true
    "type"            : "DIRECTORY"    //enum {FILE, DIRECTORY, SYMLINK}
  }
}

另请参阅：FileSystem.getFileStatus

列出目录

  • 提交 HTTP GET 请求。
    curl -i  "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=LISTSTATUS"

    客户端收到带有 FileStatuses JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 427

{
  "FileStatuses":
  {
    "FileStatus":
    [
      {
        "accessTime"      : 1320171722771,
        "blockSize"       : 33554432,
        "childrenNum"     : 0,
        "fileId"          : 16388,
        "group"           : "supergroup",
        "length"          : 24930,
        "modificationTime": 1320171722771,
        "owner"           : "webuser",
        "pathSuffix"      : "a.patch",
        "permission"      : "644",
        "replication"     : 1,
        "storagePolicy"   : 0,
        "type"            : "FILE"
      },
      {
        "accessTime"      : 0,
        "blockSize"       : 0,
        "childrenNum"     : 0,
        "fileId"          : 16389,
        "group"           : "supergroup",
        "length"          : 0,
        "modificationTime": 1320895981256,
        "owner"           : "username",
        "pathSuffix"      : "bar",
        "permission"      : "711",
        "replication"     : 0,
        "snapshotEnabled" : true
        "type"            : "DIRECTORY"
      },
      ...
    ]
  }
}

另请参阅：FileSystem.listStatus

列出文件

  • 提交 HTTP GET 请求。
    curl -i  "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=LISTSTATUS"

    客户端收到带有 FileStatuses JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 427

{
  "FileStatuses":
  {
    "FileStatus":
    [
      {
        "accessTime"      : 1320171722771,
        "blockSize"       : 33554432,
        "childrenNum"     : 0,
        "fileId"          : 16390,
        "group"           : "supergroup",
        "length"          : 1366,
        "modificationTime": 1501770633062,
        "owner"           : "webuser",
        "pathSuffix"      : "",
        "permission"      : "644",
        "replication"     : 1,
        "storagePolicy"   : 0,
        "type"            : "FILE"
      }
    ]
  }
}

另请参阅：FileSystem.listStatus

迭代列出目录

  • 提交 HTTP GET 请求。
    curl -i  "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=LISTSTATUS_BATCH&startAfter=<CHILD>"

    客户端收到带有 DirectoryListing JSON 对象 的响应，其中包含 FileStatuses JSON 对象 以及迭代信息

    HTTP/1.1 200 OK
Cache-Control: no-cache
Expires: Thu, 08 Sep 2016 03:40:38 GMT
Date: Thu, 08 Sep 2016 03:40:38 GMT
Pragma: no-cache
Expires: Thu, 08 Sep 2016 03:40:38 GMT
Date: Thu, 08 Sep 2016 03:40:38 GMT
Pragma: no-cache
Content-Type: application/json
X-FRAME-OPTIONS: SAMEORIGIN
Transfer-Encoding: chunked
Server: Jetty(6.1.26)

{
    "DirectoryListing": {
        "partialListing": {
            "FileStatuses": {
                "FileStatus": [
                    {
                        "accessTime": 0,
                        "blockSize": 0,
                        "childrenNum": 0,
                        "fileId": 16387,
                        "group": "supergroup",
                        "length": 0,
                        "modificationTime": 1473305882563,
                        "owner": "andrew",
                        "pathSuffix": "bardir",
                        "permission": "755",
                        "replication": 0,
                        "storagePolicy": 0,
                        "type": "DIRECTORY"
                    },
                    {
                        "accessTime": 1473305896945,
                        "blockSize": 1024,
                        "childrenNum": 0,
                        "fileId": 16388,
                        "group": "supergroup",
                        "length": 0,
                        "modificationTime": 1473305896965,
                        "owner": "andrew",
                        "pathSuffix": "bazfile",
                        "permission": "644",
                        "replication": 3,
                        "storagePolicy": 0,
                        "type": "FILE"
                    }
                ]
            }
        },
        "remainingEntries": 2
    }
}

如果 remainingEntries 非零，则目录中还有其他条目。要查询下一批，请将 startAfter 参数设置为当前批次中返回的最后一个项目的 pathSuffix。例如

    curl -i  "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=LISTSTATUS_BATCH&startAfter=bazfile"

这将返回下一批目录条目

    HTTP/1.1 200 OK
    Cache-Control: no-cache
    Expires: Thu, 08 Sep 2016 03:43:20 GMT
    Date: Thu, 08 Sep 2016 03:43:20 GMT
    Pragma: no-cache
    Expires: Thu, 08 Sep 2016 03:43:20 GMT
    Date: Thu, 08 Sep 2016 03:43:20 GMT
    Pragma: no-cache
    Content-Type: application/json
    X-FRAME-OPTIONS: SAMEORIGIN
    Transfer-Encoding: chunked
    Server: Jetty(6.1.26)

    {
        "DirectoryListing": {
            "partialListing": {
                "FileStatuses": {
                    "FileStatus": [
                        {
                            "accessTime": 0,
                            "blockSize": 0,
                            "childrenNum": 0,
                            "fileId": 16386,
                            "group": "supergroup",
                            "length": 0,
                            "modificationTime": 1473305878951,
                            "owner": "andrew",
                            "pathSuffix": "foodir",
                            "permission": "755",
                            "replication": 0,
                            "storagePolicy": 0,
                            "type": "DIRECTORY"
                        },
                        {
                            "accessTime": 1473305902864,
                            "blockSize": 1024,
                            "childrenNum": 0,
                            "fileId": 16389,
                            "group": "supergroup",
                            "length": 0,
                            "modificationTime": 1473305902878,
                            "owner": "andrew",
                            "pathSuffix": "quxfile",
                            "permission": "644",
                            "replication": 3,
                            "storagePolicy": 0,
                            "type": "FILE"
                        }
                    ]
                }
            },
            "remainingEntries": 0
        }
    }

批次大小由 NameNode 上的 dfs.ls.limit 选项控制。

另请参阅：FileSystem.listStatusIterator

其他文件系统操作

获取目录的内容摘要

  • 提交 HTTP GET 请求。
    curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETCONTENTSUMMARY"

    客户端收到响应，其中包含 ContentSummary JSON 对象

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{
  "ContentSummary":
  {
    "directoryCount": 2,
    "ecPolicy"      : "RS-6-3-1024k",
    "fileCount"     : 1,
    "length"        : 24930,
    "quota"         : -1,
    "spaceConsumed" : 24930,
    "spaceQuota"    : -1,
    "typeQuota":
    {
      "ARCHIVE":
      {
        "consumed": 500,
        "quota": 10000
      },
      "DISK":
      {
        "consumed": 500,
        "quota": 10000
      },
      "SSD":
      {
        "consumed": 500,
        "quota": 10000
      }
    }
  }
}

另请参阅：FileSystem.getContentSummary

获取目录的配额使用情况

  • 提交 HTTP GET 请求。
    curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETQUOTAUSAGE"

    客户端收到响应，其中包含 QuotaUsage JSON 对象

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{
  "QuotaUsage":
  {
    "fileAndDirectoryCount": 1,
    "quota"         : 100,
    "spaceConsumed" : 24930,
    "spaceQuota"    : 100000,
    "typeQuota":
    {
      "ARCHIVE":
      {
        "consumed": 500,
        "quota": 10000
      },
      "DISK":
      {
        "consumed": 500,
        "quota": 10000
      },
      "SSD":
      {
        "consumed": 500,
        "quota": 10000
      }
    }
  }
}

另请参阅：FileSystem.getQuotaUsage

设置配额

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETQUOTA
                              &namespacequota=<QUOTA>[&storagespacequota=<QUOTA>]"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：FileSystem.setQuota

按存储类型设置配额

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETQUOTABYSTORAGETYPE
                              &storagetype=<STORAGETYPE>&storagespacequota=<QUOTA>"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：FileSystem.setQuotaByStorageType

获取文件校验和

  • 提交 HTTP GET 请求。
    curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETFILECHECKSUM"

    通常，请求会重定向到数据节点

    HTTP/1.1 307 TEMPORARY_REDIRECT
Location: http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=GETFILECHECKSUM...
Content-Length: 0

    但是，如果你不想自动重定向，你可以设置 noredirect 标志。

    HTTP/1.1 200 OK
Content-Type: application/json
{"Location":"http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=GETFILECHECKSUM..."}

    客户端遵循重定向到数据节点并收到 FileChecksum JSON 对象

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{
  "FileChecksum":
  {
    "algorithm": "MD5-of-1MD5-of-512CRC32",
    "bytes"    : "eadb10de24aa315748930df6e185c0d ...",
    "length"   : 28
  }
}

另请参阅：FileSystem.getFileChecksum

获取主目录

  • 提交 HTTP GET 请求。
    curl -i "http://<HOST>:<PORT>/webhdfs/v1/?op=GETHOMEDIRECTORY"

    客户端收到响应，其中包含 Path JSON 对象

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{"Path": "/user/username"}

另请参阅：FileSystem.getHomeDirectory

获取回收站根目录

  • 提交 HTTP GET 请求。
    curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETTRASHROOT"

    客户端收到响应，其中包含 Path JSON 对象

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{"Path": "/user/username/.Trash"}

    如果路径是加密区域路径，并且用户具有该路径的权限，则客户端会收到如下响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{"Path": "/PATH/.Trash/username"}

另请参阅：FileSystem.getTrashRoot

有关加密区域中回收站根目录的更多详细信息，请参阅 透明加密指南。

设置权限

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETPERMISSION
                              [&permission=<OCTAL>]"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：permission，FileSystem.setPermission

设置所有者

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETOWNER
                              [&owner=<USER>][&group=<GROUP>]"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：owner，group，FileSystem.setOwner

设置复制因子

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETREPLICATION
                              [&replication=<SHORT>]"

    客户端收到带有 boolean JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{"boolean": true}

另请参阅：replication，FileSystem.setReplication

设置访问或修改时间

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETTIMES
                              [&modificationtime=<TIME>][&accesstime=<TIME>]"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：modificationtime，accesstime，FileSystem.setTimes

修改 ACL 条目

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=MODIFYACLENTRIES
                              &aclspec=<ACLSPEC>"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：FileSystem.modifyAclEntries

删除 ACL 条目

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=REMOVEACLENTRIES
                              &aclspec=<ACLSPEC>"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：FileSystem.removeAclEntries

删除默认 ACL

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=REMOVEDEFAULTACL"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：FileSystem.removeDefaultAcl

删除 ACL

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=REMOVEACL"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：FileSystem.removeAcl

设置 ACL

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETACL
                              &aclspec=<ACLSPEC>"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：FileSystem.setAcl

获取 ACL 状态

  • 提交 HTTP GET 请求。
    curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETACLSTATUS"

    客户端收到一个带有 AclStatus JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{
    "AclStatus": {
        "entries": [
            "user:carla:rw-", 
            "group::r-x"
        ], 
        "group": "supergroup", 
        "owner": "hadoop", 
        "permission":"775",
        "stickyBit": false
    }
}

另请参阅：FileSystem.getAclStatus

检查访问权限

  • 提交 HTTP GET 请求。
    curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=CHECKACCESS
                              &fsaction=<FSACTION>

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：FileSystem.access

存储策略操作

获取所有存储策略

  • 提交 HTTP GET 请求。
    curl -i "http://<HOST>:<PORT>/webhdfs/v1?op=GETALLSTORAGEPOLICY"

    客户端收到一个带有 BlockStoragePolicies JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{
    "BlockStoragePolicies": {
        "BlockStoragePolicy": [
           {
               "copyOnCreateFile": false,
               "creationFallbacks": [],
               "id": 2,
               "name": "COLD",
               "replicationFallbacks": [],
               "storageTypes": ["ARCHIVE"]
           },
           {
               "copyOnCreateFile": false,
               "creationFallbacks": ["DISK","ARCHIVE"],
               "id": 5,
               "name": "WARM",
               "replicationFallbacks": ["DISK","ARCHIVE"],
               "storageTypes": ["DISK","ARCHIVE"]
           },
           {
               "copyOnCreateFile": false,
               "creationFallbacks": [],
               "id": 7,
               "name": "HOT",
               "replicationFallbacks": ["ARCHIVE"],
               "storageTypes": ["DISK"]
           },
           {
               "copyOnCreateFile": false,
               "creationFallbacks": ["SSD","DISK"],
               "id": 10,"name": "ONE_SSD",
               "replicationFallbacks": ["SSD","DISK"],
               "storageTypes": ["SSD","DISK"]
           },
           {
               "copyOnCreateFile": false,
               "creationFallbacks": ["DISK"],
               "id": 12,
               "name": "ALL_SSD",
               "replicationFallbacks": ["DISK"],
               "storageTypes": ["SSD"]
           },
           {
               "copyOnCreateFile": true,
               "creationFallbacks": ["DISK"],
               "id": 15,
               "name": "LAZY_PERSIST",
               "replicationFallbacks": ["DISK"],
               "storageTypes": ["RAM_DISK","DISK"]
           }
       ]
   }
}

另请参阅：FileSystem.getAllStoragePolicies

设置存储策略

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETSTORAGEPOLICY
                              &storagepolicy=<policy>"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：FileSystem.setStoragePolicy

取消设置存储策略

  • 提交 HTTP POT 请求。
    curl -i -X POST "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=UNSETSTORAGEPOLICY"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：FileSystem.unsetStoragePolicy

获取存储策略

  • 提交 HTTP GET 请求。
    curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETSTORAGEPOLICY"

    客户端收到一个带有 BlockStoragePolicy JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{
    "BlockStoragePolicy": {
        "copyOnCreateFile": false,
       "creationFallbacks": [],
        "id":7,
        "name":"HOT",
        "replicationFallbacks":["ARCHIVE"],
        "storageTypes":["DISK"]
    }
}

另请参阅：FileSystem.getStoragePolicy

满足存储策略

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SATISFYSTORAGEPOLICY"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：ArchivalStorage.satisfyStoragePolicy

获取文件块位置

  • 提交 HTTP GET 请求。
    curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETFILEBLOCKLOCATIONS

    客户端收到一个带有 BlockLocations JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{
  "BlockLocations" :
  {
    "BlockLocation":
    [
      {
        "cachedHosts" : [],
        "corrupt" : false,
        "hosts" : ["host"],
        "length" : 134217728,                             // length of this block
        "names" : ["host:ip"],
        "offset" : 0,                                     // offset of the block in the file
        "storageTypes" : ["DISK"],                        // enum {RAM_DISK, SSD, DISK, ARCHIVE}
        "topologyPaths" : ["/default-rack/hostname:ip"]
      }, {
        "cachedHosts" : [],
        "corrupt" : false,
        "hosts" : ["host"],
        "length" : 62599364,
        "names" : ["host:ip"],
        "offset" : 134217728,
        "storageTypes" : ["DISK"],
        "topologyPaths" : ["/default-rack/hostname:ip"]
      },
      ...
    ]
  }
}

另请参阅：offset、length、FileSystem.getFileBlockLocations

扩展属性 (XAttrs) 操作

设置 XAttr

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETXATTR
                              &xattr.name=<XATTRNAME>&xattr.value=<XATTRVALUE>
                              &flag=<FLAG>"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：FileSystem.setXAttr

删除 XAttr

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=REMOVEXATTR
                              &xattr.name=<XATTRNAME>"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：FileSystem.removeXAttr

获取 XAttr

  • 提交 HTTP GET 请求。
    curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETXATTRS
                              &xattr.name=<XATTRNAME>&encoding=<ENCODING>"

    客户端收到一个带有 XAttrs JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{
    "XAttrs": [
        {
            "name":"XATTRNAME",
            "value":"XATTRVALUE"
        }
    ]
}

另请参阅：FileSystem.getXAttr

获取多个 XAttr

  • 提交 HTTP GET 请求。
    curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETXATTRS
                              &xattr.name=<XATTRNAME1>&xattr.name=<XATTRNAME2>
                              &encoding=<ENCODING>"

    客户端收到一个带有 XAttrs JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{
    "XAttrs": [
        {
            "name":"XATTRNAME1",
            "value":"XATTRVALUE1"
        },
        {
            "name":"XATTRNAME2",
            "value":"XATTRVALUE2"
        }
    ]
}

另请参阅：FileSystem.getXAttrs

获取所有 XAttr

  • 提交 HTTP GET 请求。
    curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETXATTRS
                              &encoding=<ENCODING>"

    客户端收到一个带有 XAttrs JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{
    "XAttrs": [
        {
            "name":"XATTRNAME1",
            "value":"XATTRVALUE1"
        },
        {
            "name":"XATTRNAME2",
            "value":"XATTRVALUE2"
        },
        {
            "name":"XATTRNAME3",
            "value":"XATTRVALUE3"
        }
    ]
}

另请参阅：FileSystem.getXAttrs

列出所有 XAttr

  • 提交 HTTP GET 请求。
    curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=LISTXATTRS"

    客户端会收到一个包含 XAttrNames JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{
    "XAttrNames":"[\"XATTRNAME1\",\"XATTRNAME2\",\"XATTRNAME3\"]"
}

另请参阅：FileSystem.listXAttrs

纠删码操作

启用 EC 策略

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/?op=ENABLEECPOLICY
                              &ecpolicy=<policy>"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：HDFSErasureCoding.enablePolicy

禁用 EC 策略

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/?op=DISABLEECPOLICY
                              &ecpolicy=<policy>"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：HDFSErasureCoding.disablePolicy

设置 EC 策略

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETECPOLICY
                              &ecpolicy=<policy>"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：HDFSErasureCoding.setErasureCodingPolicy

获取 EC 策略

  • 提交 HTTP GET 请求。
    curl -i -X GET "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETECPOLICY
                             "

客户端会收到一个包含 ECPolicy JSON 对象 的响应

    {
        "name": "RS-10-4-1024k",
        "schema":
        {
        "codecName": "rs",
        "numDataUnits": 10,
        "numParityUnits": 4,
        "extraOptions": {}
        }
        "cellSize": 1048576,
        "id":5,
        "codecname":"rs",
        "numDataUnits": 10,
        "numParityUnits": 4,
        "replicationpolicy":false,
        "systemPolicy":true

    }

另请参阅：HDFSErasureCoding.getErasureCodingPolicy

取消设置 EC 策略

  • 提交一个 HTTP POST 请求。
    curl -i -X POST "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=UNSETECPOLICY
                             "

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：HDFSErasureCoding.unsetErasureCodingPolicy

快照操作

允许快照

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=ALLOWSNAPSHOT"

    如果成功，客户端会收到一个内容长度为零的响应

    HTTP/1.1 200 OK
Content-Length: 0

禁止快照

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=DISALLOWSNAPSHOT"

    如果成功，客户端会收到一个内容长度为零的响应

    HTTP/1.1 200 OK
Content-Length: 0

创建快照

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=CREATESNAPSHOT[&snapshotname=<SNAPSHOTNAME>]"

    客户端收到响应，其中包含 Path JSON 对象

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{"Path": "/user/username/.snapshot/s1"}

另请参阅：FileSystem.createSnapshot

删除快照

  • 提交 HTTP DELETE 请求。
    curl -i -X DELETE "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=DELETESNAPSHOT&snapshotname=<SNAPSHOTNAME>"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：FileSystem.deleteSnapshot

重命名快照

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=RENAMESNAPSHOT
                   &oldsnapshotname=<SNAPSHOTNAME>&snapshotname=<SNAPSHOTNAME>"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：FileSystem.renameSnapshot

获取快照差异

  • 提交 HTTP GET 请求。
    curl -i GET "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETSNAPSHOTDIFF
                   &oldsnapshotname=<SNAPSHOTNAME>&snapshotname=<SNAPSHOTNAME>"

    客户端会收到一个包含 SnapshotDiffReport JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{"SnapshotDiffReport":{"diffList":[],"fromSnapshot":"s3","snapshotRoot":"/foo","toSnapshot":"s4"}}

获取可创建快照的目录列表

  • 提交 HTTP GET 请求。
    curl -i GET "http://<HOST>:<PORT>/webhdfs/v1/?user.name=<USER>&op=GETSNAPSHOTTABLEDIRECTORYLIST"

    如果 USER 不是 hdfs 超级用户，调用将仅列出用户拥有的可创建快照的目录。如果 USER 是 hdfs 超级用户，调用将列出所有可创建快照的目录。客户端会收到一个包含 SnapshottableDirectoryList JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{
    "SnapshottableDirectoryList":
    [
        {
          "dirStatus":
            {
                "accessTime":0,
                "blockSize":0,
                "childrenNum":0,
                "fileId":16386,
                "group":"hadoop",
                "length":0,
                "modificationTime":1520761889225,
                "owner":"random",
                "pathSuffix":"bar",
                "permission":"755",
                "replication":0,
                "storagePolicy":0,
                "type":"DIRECTORY"
            },
          "parentFullPath":"/",
          "snapshotNumber":0,
          "snapshotQuota":65536
        }
    ]
}

委派令牌操作

获取委派令牌

  • 提交 HTTP GET 请求。
    curl -i "http://<HOST>:<PORT>/webhdfs/v1/?op=GETDELEGATIONTOKEN
            [&renewer=<USER>][&service=<SERVICE>][&kind=<KIND>]"

    客户端会收到一个包含 Token JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{
  "Token":
  {
    "urlString": "JQAIaG9y..."
  }
}

另请参阅：renewer、FileSystem.getDelegationToken、kind、service

续订委派令牌

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/?op=RENEWDELEGATIONTOKEN&token=<TOKEN>"

    客户端会收到一个包含 long JSON 对象 的响应

    HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{"long": 1320962673997}           //the new expiration time

另请参阅：token、DelegationTokenAuthenticator.renewDelegationToken

取消委派令牌

  • 提交 HTTP PUT 请求。
    curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/?op=CANCELDELEGATIONTOKEN&token=<TOKEN>"

    客户端会收到一个内容长度为零的响应。

    HTTP/1.1 200 OK
Content-Length: 0

另请参阅：token、DelegationTokenAuthenticator.cancelDelegationToken

错误响应

当操作失败时，服务器可能会抛出异常。错误响应的 JSON 架构在 RemoteException JSON 架构 中定义。下表显示了从异常到 HTTP 响应代码的映射。

HTTP 响应代码

异常 HTTP 响应代码
IllegalArgumentException 400 错误请求
UnsupportedOperationException 400 错误请求
SecurityException 401 未经授权
IOException 403 禁止
FileNotFoundException 404 未找到
RuntimeException 500 内部服务器错误

以下是异常响应的示例。

非法参数异常

HTTP/1.1 400 Bad Request
Content-Type: application/json
Transfer-Encoding: chunked

{
  "RemoteException":
  {
    "exception"    : "IllegalArgumentException",
    "javaClassName": "java.lang.IllegalArgumentException",
    "message"      : "Invalid value for webhdfs parameter \"permission\": ..."
  }
}

安全异常

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Transfer-Encoding: chunked

{
  "RemoteException":
  {
    "exception"    : "SecurityException",
    "javaClassName": "java.lang.SecurityException",
    "message"      : "Failed to obtain user group information: ..."
  }
}

访问控制异常

HTTP/1.1 403 Forbidden
Content-Type: application/json
Transfer-Encoding: chunked

{
  "RemoteException":
  {
    "exception"    : "AccessControlException",
    "javaClassName": "org.apache.hadoop.security.AccessControlException",
    "message"      : "Permission denied: ..."
  }
}

文件未找到异常

HTTP/1.1 404 Not Found
Content-Type: application/json
Transfer-Encoding: chunked

{
  "RemoteException":
  {
    "exception"    : "FileNotFoundException",
    "javaClassName": "java.io.FileNotFoundException",
    "message"      : "File does not exist: /foo/a.patch"
  }
}

JSON 架构

除了 OPEN 之外，所有操作都会返回零长度响应或 JSON 响应。对于 OPEN，响应是一个八位字节流。JSON 架构如下所示。请参阅 draft-zyp-json-schema-03 以了解 JSON 架构的语法定义。

请注意，additionalProperties 的默认值是一个空架构，允许对其他属性使用任何值。因此，所有 WebHDFS JSON 响应都允许任何其他属性。但是，如果响应中包含其他属性，则将它们视为可选属性，以保持兼容性。

ACL 状态 JSON 架构

{
  "name"      : "AclStatus",
  "properties":
  {
    "AclStatus":
    {
      "type"      : "object",
      "properties":
      {
        "entries":
        {
          "type": "array",
          "items":
          {
            "description": "ACL entry.",
            "type": "string"
          }
        },
        "group":
        {
          "description": "The group owner.",
          "type"       : "string",
          "required"   : true
        },
        "owner":
        {
          "description": "The user who is the owner.",
          "type"       : "string",
          "required"   : true
        },
        "stickyBit":
        {
          "description": "True if the sticky bit is on.",
          "type"       : "boolean",
          "required"   : true
        }
      }
    }
  }
}

XAttrs JSON 架构

{
  "name"      : "XAttrs",
  "properties":
  {
    "XAttrs":
    {
      "type"      : "array",
      "items":
      {
        "type"    : "object",
        "properties":
        {
          "name":
          {
            "description": "XAttr name.",
            "type"       : "string",
            "required"   : true
          },
          "value":
          {
            "description": "XAttr value.",
            "type"       : "string"
          }
        }
      }
    }
  }
}

XAttrNames JSON 架构

{
  "name"      : "XAttrNames",
  "properties":
  {
    "XAttrNames":
    {
      "description": "XAttr names.",
      "type"       : "string",
      "required"   : true
    }
  }
}

布尔 JSON 架构

{
  "name"      : "boolean",
  "properties":
  {
    "boolean":
    {
      "description": "A boolean value",
      "type"       : "boolean",
      "required"   : true
    }
  }
}

另请参阅：MKDIRS、RENAME、DELETE、SETREPLICATION

ContentSummary JSON 架构

{
  "name"      : "ContentSummary",
  "properties":
  {
    "ContentSummary":
    {
      "type"      : "object",
      "properties":
      {
        "directoryCount":
        {
          "description": "The number of directories.",
          "type"       : "integer",
          "required"   : true
        },
        "fileCount":
        {
          "description": "The number of files.",
          "type"       : "integer",
          "required"   : true
        },
        "length":
        {
          "description": "The number of bytes used by the content.",
          "type"       : "integer",
          "required"   : true
        },
        "quota":
        {
          "description": "The namespace quota of this directory.",
          "type"       : "integer",
          "required"   : true
        },
        "spaceConsumed":
        {
          "description": "The disk space consumed by the content.",
          "type"       : "integer",
          "required"   : true
        },
        "spaceQuota":
        {
          "description": "The disk space quota.",
          "type"       : "integer",
          "required"   : true
        },
        "typeQuota":
        {
          "type"      : "object",
          "properties":
          {
            "ARCHIVE":
            {
              "type"      : "object",
              "properties":
              {
                "consumed":
                {
                  "description": "The storage type space consumed.",
                  "type"       : "integer",
                  "required"   : true
                },
                "quota":
                {
                  "description": "The storage type quota.",
                  "type"       : "integer",
                  "required"   : true
                }
              }
            },
            "DISK":
            {
              "type"      : "object",
              "properties":
              {
                "consumed":
                {
                  "description": "The storage type space consumed.",
                  "type"       : "integer",
                  "required"   : true
                },
                "quota":
                {
                  "description": "The storage type quota.",
                  "type"       : "integer",
                  "required"   : true
                }
              }
            },
            "SSD":
            {
              "type"      : "object",
              "properties":
              {
                "consumed":
                {
                  "description": "The storage type space consumed.",
                  "type"       : "integer",
                  "required"   : true
                },
                "quota":
                {
                  "description": "The storage type quota.",
                  "type"       : "integer",
                  "required"   : true
                }
              }
            }
          }
        }
      }
    }
  }
}

另请参阅：GETCONTENTSUMMARY

配额使用情况 JSON 架构

{
  "name"      : "QuotaUsage",
  "properties":
  {
    "QuotaUsage":
    {
      "type"      : "object",
      "properties":
      {
        "fileAndDirectoryCount":
        {
          "description": "The number of files and directories.",
          "type"       : "integer",
          "required"   : true
        },
        "quota":
        {
          "description": "The namespace quota of this directory.",
          "type"       : "integer",
          "required"   : true
        },
        "spaceConsumed":
        {
          "description": "The disk space consumed by the content.",
          "type"       : "integer",
          "required"   : true
        },
        "spaceQuota":
        {
          "description": "The disk space quota.",
          "type"       : "integer",
          "required"   : true
        },
        "typeQuota":
        {
          "type"      : "object",
          "properties":
          {
            "ARCHIVE":
            {
              "type"      : "object",
              "properties":
              {
                "consumed":
                {
                  "description": "The storage type space consumed.",
                  "type"       : "integer",
                  "required"   : true
                },
                "quota":
                {
                  "description": "The storage type quota.",
                  "type"       : "integer",
                  "required"   : true
                }
              }
            },
            "DISK":
            {
              "type"      : "object",
              "properties":
              {
                "consumed":
                {
                  "description": "The storage type space consumed.",
                  "type"       : "integer",
                  "required"   : true
                },
                "quota":
                {
                  "description": "The storage type quota.",
                  "type"       : "integer",
                  "required"   : true
                }
              }
            },
            "SSD":
            {
              "type"      : "object",
              "properties":
              {
                "consumed":
                {
                  "description": "The storage type space consumed.",
                  "type"       : "integer",
                  "required"   : true
                },
                "quota":
                {
                  "description": "The storage type quota.",
                  "type"       : "integer",
                  "required"   : true
                }
              }
            }
          }
        }
      }
    }
  }
}

另请参阅：GETQUOTAUSAGE

文件校验和 JSON 架构

{
  "name"      : "FileChecksum",
  "properties":
  {
    "FileChecksum":
    {
      "type"      : "object",
      "properties":
      {
        "algorithm":
        {
          "description": "The name of the checksum algorithm.",
          "type"       : "string",
          "required"   : true
        },
        "bytes":
        {
          "description": "The byte sequence of the checksum in hexadecimal.",
          "type"       : "string",
          "required"   : true
        },
        "length":
        {
          "description": "The length of the bytes (not the length of the string).",
          "type"       : "integer",
          "required"   : true
        }
      }
    }
  }
}

文件状态 JSON 架构

{
  "name"      : "FileStatus",
  "properties":
  {
    "FileStatus": fileStatusProperties      //See FileStatus Properties
  }
}

另请参阅：FileStatus 属性、GETFILESTATUS、FileStatus

文件状态属性

使用 JavaScript 语法定义 fileStatusProperties，以便在 FileStatus 和 FileStatuses JSON 架构中引用它。

var fileStatusProperties =
{
  "type"      : "object",
  "properties":
  {
    "accessTime":
    {
      "description": "The access time.",
      "type"       : "integer",
      "required"   : true
    },
    "blockSize":
    {
      "description": "The block size of a file.",
      "type"       : "integer",
      "required"   : true
    },
    "group":
    {
      "description": "The group owner.",
      "type"       : "string",
      "required"   : true
    },
    "length":
    {
      "description": "The number of bytes in a file.",
      "type"       : "integer",
      "required"   : true
    },
    "modificationTime":
    {
      "description": "The modification time.",
      "type"       : "integer",
      "required"   : true
    },
    "owner":
    {
      "description": "The user who is the owner.",
      "type"       : "string",
      "required"   : true
    },
    "pathSuffix":
    {
      "description": "The path suffix.",
      "type"       : "string",
      "required"   : true
    },
    "permission":
    {
      "description": "The permission represented as a octal string.",
      "type"       : "string",
      "required"   : true
    },
    "replication":
    {
      "description": "The number of replication of a file.",
      "type"       : "integer",
      "required"   : true
    },
   "symlink":                                         //an optional property
    {
      "description": "The link target of a symlink.",
      "type"       : "string"
    },
   "type":
    {
      "description": "The type of the path object.",
      "enum"       : ["FILE", "DIRECTORY", "SYMLINK"],
      "required"   : true
    }
  }
};

文件状态 JSON 架构

FileStatuses JSON 对象表示 FileStatus JSON 对象的数组。

{
  "name"      : "FileStatuses",
  "properties":
  {
    "FileStatuses":
    {
      "type"      : "object",
      "properties":
      {
        "FileStatus":
        {
          "description": "An array of FileStatus",
          "type"       : "array",
          "items"      : fileStatusProperties      //See FileStatus Properties
        }
      }
    }
  }
}

另请参阅：FileStatus 属性、LISTSTATUS、FileStatus

目录列表 JSON 架构

DirectoryListing JSON 对象表示在迭代列出目录时的目录条目批次。它包含一个 FileStatuses JSON 对象以及迭代信息。

{
  "name"      : "DirectoryListing",
  "properties":
  {
    "DirectoryListing":
    {
      "type"      : "object",
      "properties":
      {
        "partialListing":
        {
          "description": "A partial directory listing",
          "type"       : "object", // A FileStatuses object
          "required"   : true
        },
        "remainingEntries":
        {
          "description": "Number of remaining entries",
          "type"       : "integer",
          "required"   : true
        }
      }
    }
  }

}

另请参阅：FileStatuses JSON 架构、LISTSTATUS_BATCH、FileStatus

长整型 JSON 架构

{
  "name"      : "long",
  "properties":
  {
    "long":
    {
      "description": "A long integer value",
      "type"       : "integer",
      "required"   : true
    }
  }
}

另请参阅：RENEWDELEGATIONTOKEN，

路径 JSON 架构

{
  "name"      : "Path",
  "properties":
  {
    "Path":
    {
      "description": "The string representation a Path.",
      "type"       : "string",
      "required"   : true
    }
  }
}

另请参阅：GETHOMEDIRECTORY、Path

远程异常 JSON 架构

{
  "name"      : "RemoteException",
  "properties":
  {
    "RemoteException":
    {
      "type"      : "object",
      "properties":
      {
        "exception":
        {
          "description": "Name of the exception",
          "type"       : "string",
          "required"   : true
        },
        "message":
        {
          "description": "Exception message",
          "type"       : "string",
          "required"   : true
        },
        "javaClassName":                                     //an optional property
        {
          "description": "Java class name of the exception",
          "type"       : "string"
        }
      }
    }
  }
}

另请参阅：错误响应

令牌 JSON 架构

{
  "name"      : "Token",
  "properties":
  {
    "Token": tokenProperties      //See Token Properties
  }
}

另请参阅：Token 属性、GETDELEGATIONTOKEN、委派中的注释。

令牌属性

使用 JavaScript 语法定义 tokenProperties，以便在 Token JSON 架构中引用它。

var tokenProperties =
{
  "type"      : "object",
  "properties":
  {
    "urlString":
    {
      "description": "A delegation token encoded as a URL safe string.",
      "type"       : "string",
      "required"   : true
    }
  }
}

另请参阅：Token 属性、委派中的注释。

块存储策略 JSON 架构

{
  "name"      : "BlockStoragePolicy",
  "properties":
  {
    "BlockStoragePolicy": blockStoragePolicyProperties      //See BlockStoragePolicy Properties
  }
}

另请参阅：BlockStoragePolicy 属性、GETSTORAGEPOLICY

块存储策略属性

使用 JavaScript 语法定义 blockStoragePolicyProperties，以便在 BlockStoragePolicy 和 BlockStoragePolicies JSON 架构中引用它。

var blockStoragePolicyProperties =
{
  "type"      : "object",
  "properties":
  {
    "id":
    {
      "description": "Policy ID.",
      "type"       : "integer",
      "required"   : true
    },
    "name":
    {
      "description": "Policy name.",
      "type"       : "string",
      "required"   : true
    },
    "storageTypes":
    {
      "description": "An array of storage types for block placement.",
      "type"       : "array",
      "required"   : true
      "items"      :
      {
        "type": "string"
      }
    },
    "replicationFallbacks":
    {
      "description": "An array of fallback storage types for replication.",
      "type"       : "array",
      "required"   : true
      "items"      :
      {
        "type": "string"
      }
    },
    "creationFallbacks":
    {
      "description": "An array of fallback storage types for file creation.",
      "type"       : "array",
      "required"   : true
      "items"      :
      {
       "type": "string"
      }
    },
    "copyOnCreateFile":
    {
      "description": "If set then the policy cannot be changed after file creation.",
      "type"       : "boolean",
      "required"   : true
    }
  }
};

EC 策略 JSON 架构

{
  "name": "RS-10-4-1024k",
  schema {
           "codecName": "rs",
           "numDataUnits": 10,
           "numParityUnits": 4,
           "extraOptions": {}
          }
  "cellSize": 1048576,
  "id":5,
  "codecname":"rs",
  "numDataUnits": 10,
  "numParityUnits": 4,
  "replicationpolicy":false,
  "systemPolicy":true
}

块存储策略 JSON 架构

BlockStoragePolicies JSON 对象表示 BlockStoragePolicy JSON 对象的数组。

{
  "name"      : "BlockStoragePolicies",
  "properties":
  {
    "BlockStoragePolicies":
    {
      "type"      : "object",
      "properties":
      {
        "BlockStoragePolicy":
        {
          "description": "An array of BlockStoragePolicy",
          "type"       : "array",
          "items"      : blockStoragePolicyProperties      //See BlockStoragePolicy Properties
        }
      }
    }
  }
}

SnapshotDiffReport JSON 模式

{
  "name": "SnapshotDiffReport",
  "type": "object",
  "properties":
  {
    "SnapshotDiffReport":
    {
      "type"        : "object",
      "properties"  :
      {
        "diffList":
        {
          "description": "An array of DiffReportEntry",
          "type"        : "array",
          "items"       : diffReportEntries,
          "required"    : true
        },
        "fromSnapshot":
        {
          "description": "Source snapshot",
          "type"        : "string",
          "required"    : true
        },
        "snapshotRoot":
        {
          "description" : "String representation of snapshot root path",
          "type"        : "string",
          "required"    : true
        },
        "toSnapshot":
        {
          "description" : "Destination snapshot",
          "type"        : "string",
          "required"    : true
        }
      }
    }
  }
}

DiffReport 条目

使用 JavaScript 语法定义 diffReportEntries，以便在 SnapshotDiffReport JSON 模式中引用它。

var diffReportEntries =
{
  "type": "object",
  "properties":
  {
    "sourcePath":
    {
      "description" : "Source path name relative to snapshot root",
      "type"        : "string",
      "required"    : true
    },
    "targetPath":
    {
      "description" : "Target path relative to snapshot root used for renames",
      "type"        : "string",
      "required"    : true
    },
    "type":
    {
      "description" : "Type of diff report entry",
      "enum"        : ["CREATE", "MODIFY", "DELETE", "RENAME"],
      "required"    : true
    }
  }
}

SnapshottableDirectoryList JSON 模式

{
  "name": "SnapshottableDirectoryList",
  "type": "object",
  "properties":
  {
    "SnapshottableDirectoryList":
    {
      "description": "An array of SnapshottableDirectoryStatus",
      "type"        : "array",
      "items"       : snapshottableDirectoryStatus,
      "required"    : true
    }
  }
}

SnapshottableDirectoryStatus

使用 JavaScript 语法定义 snapshottableDirectoryStatus，以便在 SnapshottableDirectoryList JSON 模式中引用它。

var snapshottableDirectoryStatus =
{
  "type": "object",
  "properties":
  {
    "dirStatus": fileStatusProperties,
    "parentFullPath":
    {
      "description" : "Full path of the parent of snapshottable directory",
      "type"        : "string",
      "required"    : true
    },
    "snapshotNumber":
    {
      "description" : "Number of snapshots created on the snapshottable directory",
      "type"        : "integer",
      "required"    : true
    },
    "snapshotQuota":
    {
      "description" : "Total number of snapshots allowed on the snapshottable directory",
      "type"        : "integer",
      "required"    : true
    }
  }
}

BlockLocations JSON 模式

BlockLocations JSON 对象表示 BlockLocation JSON 对象的数组。

{
  "name"      : "BlockLocations",
  "properties":
  {
    "BlockLocations":
    {
      "type"      : "object",
      "properties":
      {
        "BlockLocation":
        {
          "description": "An array of BlockLocation",
          "type"       : "array",
          "items"      : blockLocationProperties      //See BlockLocation Properties
        }
      }
    }
  }
}

另请参阅 BlockLocation 属性、GETFILEBLOCKLOCATIONS、BlockLocation

BlockLocation JSON 模式

{
  "name"      : "BlockLocation",
  "properties":
  {
    "BlockLocation": blockLocationProperties      //See BlockLocation Properties
  }
}

另请参阅 BlockLocation 属性、GETFILEBLOCKLOCATIONS、BlockLocation

BlockLocation 属性

使用 JavaScript 语法定义 blockLocationProperties，以便在 BlockLocation 和 BlockLocations JSON 模式中引用它。

var blockLocationProperties =
{
  "type"      : "object",
  "properties":
  {
    "cachedHosts":
    {
      "description": "Datanode hostnames with a cached replica",
      "type"       : "array",
      "required"   : "true",
      "items"      :
      {
        "description": "A datanode hostname",
        "type"       : "string"
      }
    },
    "corrupt":
    {
      "description": "True if the block is corrupted",
      "type"       : "boolean",
      "required"   : "true"
    },
    "hosts":
    {
      "description": "Datanode hostnames store the block",
      "type"       : "array",
      "required"   : "true",
      "items"      :
      {
        "description": "A datanode hostname",
        "type"       : "string"
      }
    },
    "length":
    {
      "description": "Length of the block",
      "type"       : "integer",
      "required"   : "true"
    },
    "names":
    {
      "description": "Datanode IP:xferPort for accessing the block",
      "type"       : "array",
      "required"   : "true",
      "items"      :
      {
        "description": "DatanodeIP:xferPort",
        "type"       : "string"
      }
    },
    "offset":
    {
      "description": "Offset of the block in the file",
      "type"       : "integer",
      "required"   : "true"
    },
    "storageTypes":
    {
      "description": "Storage type of each replica",
      "type"       : "array",
      "required"   : "true",
      "items"      :
      {
        "description": "Storage type",
        "enum"       : ["RAM_DISK", "SSD", "DISK", "ARCHIVE"]
      }
    },
    "topologyPaths":
    {
      "description": "Datanode addresses in network topology",
      "type"       : "array",
      "required"   : "true",
      "items"      :
      {
        "description": "/rack/host:ip",
        "type"       : "string"
      }
    }
  }
};

HTTP 查询参数字典

ACL 规范

名称 aclspec
说明 ACL 修改操作中包含的 ACL 规范。
类型 字符串
默认值 <empty>
有效值 请参阅 权限和 HDFS。
语法 请参阅 权限和 HDFS。

XAttr 名称

名称 xattr.name
说明 文件/目录的 XAttr 名称。
类型 字符串
默认值 <empty>
有效值 以 user./trusted./system./security.. 为前缀的任何字符串。
语法 以 user./trusted./system./security.. 为前缀的任何字符串。

XAttr 值

名称 xattr.value
说明 文件/目录的 XAttr 值。
类型 字符串
默认值 <empty>
有效值 编码值。
语法 用双引号括起来或以 0x 或 0s 为前缀。

另请参阅：扩展属性

XAttr 设置标志

名称 flag
说明 XAttr 设置标志。
类型 字符串
默认值 <empty>
有效值 CREATE、REPLACE。
语法 CREATE、REPLACE。

另请参阅：扩展属性

XAttr 值编码

名称 encoding
说明 XAttr 值编码。
类型 字符串
默认值 <empty>
有效值 text hex base64
语法 text hex base64

另请参阅：扩展属性

访问时间

名称 accesstime
说明 文件/目录的访问时间。
类型 long
默认值 -1（表示保持不变）
有效值 -1 或时间戳
语法 任何整数。

另请参阅：SETTIMES

块大小

名称 blocksize
说明 文件的块大小。
类型 long
默认值 在配置中指定。
有效值 > 0
语法 任何整数。

另请参阅：CREATE

缓冲区大小

名称 buffersize
说明 用于传输数据时所用缓冲区的大小。
类型 int
默认值 在配置中指定。
有效值 > 0
语法 任何整数。

另请参阅：CREATE、APPEND、OPEN

创建标志

名称 createflag
说明 创建文件时要处理的可能标志的枚举
类型 枚举字符串
默认值 <empty>
有效值 create、overwrite、append 和 sync_block 的合法组合
语法 请参阅下面的注释

以下组合无效：* append,create * create,append,overwrite

另请参阅：CREATE

创建父级

名称 createparent
说明 如果父目录不存在，是否应该创建它们？
类型 布尔值
默认值 true
有效值 true、false
语法 true

另请参阅：CREATESYMLINK

委派

名称 delegation
说明 用于身份验证的委派令牌。
类型 字符串
默认值 <empty>
有效值 编码令牌。
语法 请参阅下面的注释。

请注意，委派令牌被编码为 URL 安全字符串；请参阅 org.apache.hadoop.security.token.Token 中的 encodeToUrlString() 和 decodeFromUrlString(String)，了解编码的详细信息。

另请参阅：身份验证

目标

名称 destination
说明 目标路径。
类型 路径
默认值 <empty>（无效路径）
有效值 不带方案和权限的绝对文件系统路径。
语法 任何路径。

另请参阅：CREATESYMLINK、RENAME

以身份执行

名称 doas
说明 允许代理用户以其他用户的身份执行操作。
类型 字符串
默认值 null
有效值 任何有效的用户名。
语法 任何字符串。

另请参阅：代理用户

文件系统操作

名称 fsaction
说明 文件系统操作读/写/执行
类型 字符串
默认值 null（无效值）
有效值 与正则表达式模式“ [r-][w-][x-] ”匹配的字符串
语法  “[r-][w-][x-] ”

另请参阅：CHECKACCESS，

组

名称 group
说明 组的名称。
类型 字符串
默认值 <empty>（表示保持不变）
有效值 任何有效的组名。
语法 任何字符串。

另请参阅：SETOWNER

长度

名称 length
说明 要处理的字节数。
类型 long
默认值 null（表示整个文件）
有效值 >= 0 或 null
语法 任何整数。

另请参阅：OPEN

修改时间

名称 modificationtime
说明 文件/目录的修改时间。
类型 long
默认值 -1（表示保持不变）
有效值 -1 或时间戳
语法 任何整数。

另请参阅：SETTIMES

新长度

名称 newlength
说明 要将文件截断到的长度。
类型 long
有效值 >= 0
语法 任何 long。

偏移量

名称 offset
说明 起始字节位置。
类型 long
默认值 0
有效值 >= 0
语法 任何整数。

另请参阅：OPEN

旧快照名称

名称 oldsnapshotname
说明 要重命名的快照的旧名称。
类型 字符串
默认值 null
有效值 现有的快照名称。
语法 任何字符串。

另请参阅：RENAMESNAPSHOT

操作

名称 op
说明 要执行的操作的名称。
类型 枚举
默认值 null（无效值）
有效值 任何有效的操作名称。
语法 任何字符串。

另请参阅：操作

覆盖

名称 overwrite
说明 如果文件已存在，是否应覆盖它？
类型 布尔值
默认值 false
有效值 true
语法 true

另请参阅：CREATE

所有者

名称 owner
说明 文件/目录的所有者的用户名。
类型 字符串
默认值 <empty>（表示保持不变）
有效值 任何有效的用户名。
语法 任何字符串。

另请参阅：SETOWNER

权限

名称 permission
说明 文件/目录的权限。
类型 八进制
默认值 文件为 644，目录为 755
有效值 0 - 1777
语法 任何基数 8 的整数（可以省略前导零）。

另请参阅：CREATE、MKDIRS、SETPERMISSION

递归

名称 recursive
说明 操作是否应作用于子目录中的内容？
类型 布尔值
默认值 false
有效值 true
语法 true

另请参阅：RENAME

更新者

名称 renewer
说明 委派令牌更新者的用户名。
类型 字符串
默认值 <empty>（表示当前用户）
有效值 任何有效的用户名。
语法 任何字符串。

另请参阅：GETDELEGATIONTOKEN

复制

名称 replication
说明 文件的复制数。
类型 短整型
默认值 在配置中指定。
有效值 > 0
语法 任何整数。

另请参阅：CREATE、SETREPLICATION

快照名称

名称 snapshotname
说明 要创建/删除的快照的名称。或快照重命名的新名称。
类型 字符串
默认值 null
有效值 任何有效的快照名称。
语法 任何字符串。

另请参阅：CREATESNAPSHOT、DELETESNAPSHOT、RENAMESNAPSHOT

源

名称 sources
说明 源路径列表。
类型 字符串
默认值 <empty>
有效值 不带方案和权限的以逗号分隔的绝对文件系统路径列表。
语法 任何字符串。

另请参阅：CONCAT

令牌

名称 token
说明 用于操作的委派令牌。
类型 字符串
默认值 <empty>
有效值 编码令牌。
语法 请参阅委派中的注释。

另请参阅：RENEWDELEGATIONTOKEN、CANCELDELEGATIONTOKEN

令牌类型

名称 kind
说明 请求的委派令牌的类型
类型 字符串
默认值 <empty>（服务器为服务设置默认类型）
有效值 表示令牌类型的字符串，例如“HDFS_DELEGATION_TOKEN”或“WEBHDFS delegation”
语法 任何字符串。

另请参阅：GETDELEGATIONTOKEN

令牌服务

名称 service
说明 服务名称，令牌应该在该服务中使用，例如 namenode 的 ip:port
类型 字符串
默认值 <empty>
有效值 字符串格式的 ip:port 或服务的逻辑名称
语法 任何字符串。

另请参阅：GETDELEGATIONTOKEN

用户名

名称 user.name
说明 经过身份验证的用户；请参阅 身份验证。
类型 字符串
默认值 null
有效值 任何有效的用户名。
语法 任何字符串。

另请参阅：身份验证

不重定向

名称 noredirect
说明 响应应返回 HTTP 307 重定向还是 HTTP 200 OK。请参阅 创建和写入文件。
类型 布尔值
默认值 false
有效值 true
语法 true

另请参阅：创建和写入文件

命名空间配额

名称 namespacequota
说明 命名空间使用限制，即目录下的文件/目录数量。
类型 字符串
默认值 Long.MAX_VALUE
有效值 > 0.
语法 任何整数。

另请参阅：SETQUOTA

存储空间配额

名称 storagespacequota
说明 目录下存储空间使用限制（以字节为单位，包括复制）。
类型 字符串
默认值 Long.MAX_VALUE
有效值 > 0.
语法 任何整数。

另请参阅：SETQUOTA、SETQUOTABYSTORAGETYPE

存储类型

名称 storagetype
说明 要修改的特定存储类型配额的存储类型。
类型 字符串
默认值 <empty>
有效值 任何有效的存储类型。
语法 任何字符串。

另请参阅：SETQUOTABYSTORAGETYPE

存储策略

名称 storagepolicy
说明 存储策略的名称。
类型 字符串
默认值 <empty>
有效值 任何有效的存储策略名称；请参阅 GETALLSTORAGEPOLICY。
语法 任何字符串。

另请参阅：SETSTORAGEPOLICY

纠删码策略

名称 ecpolicy
说明 纠删码策略的名称。
类型 字符串
默认值 <empty>
有效值 任何有效的纠删码策略名称；
语法 任何字符串。

另请参阅：ENABLEECPOLICY 或 DISABLEECPOLICY

从...开始

名称 startAfter
说明 liststatus 批处理中返回的最后一个项目。
类型 字符串
默认值 <empty>
有效值 任何有效的文件/目录名称。
语法 任何字符串。

另请参阅：LISTSTATUS_BATCH