WebHDFS REST API

               

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有下面的格式：

[html]  view plain copy

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

下面是对应的HDFS的URL：

   
   

    
    

     
     

      
      [html] 
      
      view plain
      
      copy
      
      

     
     
    
    
    
    

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

在REST API中，前缀” /webhdfs/v1”插入到path之前，一个query被增加到最后。因此，相应的HTTPURL有下面的格式：

   
   

    
    

     
     

      
      [html] 
      
      view plain
      
      copy
      
      

     
     
    
    
    
    

     
     
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关闭时的认证：

[html]  view plain copy

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

2.      当security开启时用Kerberos SPNEGO认证

[html]  view plain copy

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

3.      当security开启时用Hadoop Delegation Token认证

[html]  view plain copy

1. 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关闭时一个代理请求：

[html]  view plain copy

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

l  当security开启时用KerberosSPNEGO验证代理请求：

[html]  view plain copy

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

l  当security开启时用HadoopDelegation Token验证大力请求：

[html]  view plain copy

1. 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请求，没有自动接着重定向，也没有发送文件数据。

   
   

    
    

     
     

      
      [html] 
      
      view plain
      
      copy
      
      

     
     
    
    
    
    

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

请求被重定向到要被写入数据的文件所在的DataNode：

   
   

    
    

     
     

      
      [html] 
      
      view plain
      
      copy
      
      

     
     
    
    
    
    

     
     
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。

   
   

    
    

     
     

      
      [html] 
      
      view plain
      
      copy
      
      

     
     
    
    
    
    

     
     
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请求，不会自动接着重定向，不发送文件数据：

[html]  view plain copy

1. curl -i -X POST"http://<HOST>: