Document Conventions
Monospaced |
Used for commands, HTTP request and responses and code blocks. |
<Monospaced> |
User entered values. |
[Monospaced] |
Optional values. When the value is not specified, the default value is used. |
Italics |
Important phrases and words. |
Introduction
HTTP REST API支持HDFSFileSystem/FileContext全部的API。HTTP操作和相应的FIleSystem/FileContext里的方法在下个部分展示。HTTP Query Parameter Dictionary部分详细的描述了默认值和有效值。
Operations
HTTP GET
- OPEN (see FileSystem.open)
- GETFILESTATUS (see FileSystem.getFileStatus)
- LISTSTATUS (see FileSystem.listStatus)
- GETCONTENTSUMMARY (see FileSystem.getContentSummary)
- GETFILECHECKSUM (see FileSystem.getFileChecksum)
- GETHOMEDIRECTORY (see FileSystem.getHomeDirectory)
- GETDELEGATIONTOKEN (see FileSystem.getDelegationToken)
- GETDELEGATIONTOKENS (see FileSystem.getDelegationTokens)
HTTP PUT
- CREATE (see FileSystem.create)
- MKDIRS (see FileSystem.mkdirs)
- CREATESYMLINK (see FileContext.createSymlink)
- RENAME (see FileSystem.rename)
- SETREPLICATION (see FileSystem.setReplication)
- SETOWNER (see FileSystem.setOwner)
- SETPERMISSION (see FileSystem.setPermission)
- SETTIMES (see FileSystem.setTimes)
- RENEWDELEGATIONTOKEN (see FileSystem.renewDelegationToken)
- CANCELDELEGATIONTOKEN (see FileSystem.cancelDelegationToken)
HTTP POST
- APPEND (see FileSystem.append)
- CONCAT (see FileSystem.concat)
HTTP DELETE
- DELETE (see FileSystem.delete)
FileSystem URIs vs HTTP URLs
WebHDFS文件系统的scheme是“webhdfs://”。一个WebHDFS文件系统的URL有下面的格式:
- webhdfs://<HOST>:<HTTP_PORT>/<PATH>
下面是对应的HDFS的URL:
- hdfs://<HOST>:<RPC_PORT>/<PATH>
在REST API中,前缀” /webhdfs/v1”插入到path之前,一个query被增加到最后。因此,相应的HTTPURL有下面的格式:
- http://<HOST>:<HTTP_PORT>/webhdfs/v1/<PATH>?op=...
HDFS Configuration Options
下面是HDFS配置中关于WebHDFS的配置属性:
Property Name |
Description |
dfs.webhdfs.enabled |
Enable/disable WebHDFS in Namenodes and Datanodes |
dfs.web.authentication.kerberos.principal |
The HTTP Kerberos principal used by Hadoop-Auth in the HTTP endpoint. The HTTP Kerberos principal MUST start with 'HTTP/' per Kerberos HTTP SPNEGO specification. |
dfs.web.authentication.kerberos.keytab |
The Kerberos keytab file with the credentials for the HTTP Kerberos principal used by Hadoop-Auth in the HTTP endpoint. |
Authentication
当security关闭的时候,认证的用户是在user.name查询参数中指定的用户。如果user.name参数没被设置,服务器设置认证用户为默认的web用户,如果是, if there is any, or return an error response。
当security开启时,认证通过Hadoop Delegation Token或者Kerberos SPNEGO执行。如果在delegation查询参数中设置了一个token,认证的用户就是编码进token的用户。如果delegation查询参数没有被设置,用户通过Kerberos SPNEGO认证。
下面是用curl命令工具的一下例子:
1. 当security关闭时的认证:
- curl -i"http://<HOST>:<PORT>/webhdfs/v1/<PATH>?[user.name=<USER>&]op=..."
2. 当security开启时用Kerberos SPNEGO认证
- curl -i--negotiate -u :"http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=..."
3. 当security开启时用Hadoop Delegation Token认证
- curl -i"http://<HOST>:<PORT>/webhdfs/v1/<PATH>?delegation=<TOKEN>&op=..."
也可以查看:HTTP Authentication。
Proxy Users
当代理用户特性开启时,一个代理用户P可以代表其他的用户U提交一个请求。U的用户名必须在doas查询参数中被指定,除非一个Delegation Token出现在认证中。在这种情况下,用户P和U的信息必须被编码进Delegation Token。
l 当security关闭时一个代理请求:
- curl -i"http://<HOST>:<PORT>/webhdfs/v1/<PATH>?[user.name=<USER>&]doas=<USER>&op=..."
l 当security开启时用KerberosSPNEGO验证代理请求:
- curl -i --negotiate -u :"http://<HOST>:<PORT>/webhdfs/v1/<PATH>?doas=<USER>&op=..."
l 当security开启时用HadoopDelegation Token验证大力请求:
- curl -i"http://<HOST>:<PORT>/webhdfs/v1/<PATH>?delegation=<TOKEN>&op=..."
File and Directory Operations
Create and Write to a File
u Step1:提交一个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>]"
请求被重定向到要被写入数据的文件所在的DataNode:
- HTTP/1.1 307 TEMPORARY_REDIRECT
- Location: http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=CREATE...
- Content-Length: 0
u Step2:用要被写入的文件数据,提交另一个HTTP PUT请求到上边返回的Header中的location的URL。
curl -i -X PUT -T <LOCAL_FILE> "http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=CREATE..."
客户端收到一个201 Created响应,content-length为0,location header是一个WebHDFS的URL。
- HTTP/1.1 201 Created
- Location: webhdfs://<HOST>:<PORT>/<PATH>
- Content-Length: 0
注意:分成create/append两步的原因是为了防止客户端在重定向之前发送数据。这个问题在HTTP/1.1中可以通过加入"Expect: 100-continue"头解决。不幸的是,还有一些软件库存在bug(例如Jetty 6HTTP Server and java 6 HTTP Client),它们没有正确的实现"Expect: 100-continue"。通过create/append两步是针对软件库bug一个临时的解决方案。
See also: overwrite, blocksize, replication, permission, buffersize, FileSystem.create
Append toa file
u Step1:提交一个HTTP POST请求,不会自动接着重定向,不发送文件数据:
- curl -i -X POST"http://<HOST>: