WebHDFS REST API

以你之姓@ 2022-08-17 15:16 139阅读 0赞

# Document Conventions #

<table style="color:rgb(51,51,51); font-family:Arial; font-size:14.44444465637207px; line-height:25.98958396911621px"> 
 <tbody> 
 <tr> 
 <td style="background-color:rgb(221,221,221)"> Monospaced </td> 
 <td style="background-color:rgb(221,221,221)"> Used for commands, HTTP request and responses and code blocks. </td> 
 </tr> 
 <tr> 
 <td style="background-color:rgb(223,227,219)"> &lt;Monospaced&gt; </td> 
 <td style="background-color:rgb(223,227,219)"> User entered values. </td> 
 </tr> 
 <tr> 
 <td style="background-color:rgb(221,221,221)"> [Monospaced] </td> 
 <td style="background-color:rgb(221,221,221)"> Optional values. When the value is not specified, the default value is used. </td> 
 </tr> 
 <tr> 
 <td style="background-color:rgb(238,238,238)"> Italics </td> 
 <td style="background-color:rgb(238,238,238)"> Important phrases and words. </td> 
 </tr> 
 </tbody> 
</table>

# 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][view plain]

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的配置属性：

<table style="color:rgb(51,51,51); font-family:Arial; font-size:14.44444465637207px; line-height:25.98958396911621px"> 
 <tbody> 
 <tr> 
 <td style="background-color:rgb(187,187,187)"> Property Name </td> 
 <td style="background-color:rgb(187,187,187)"> Description </td> 
 </tr> 
 <tr> 
 <td style="background-color:rgb(238,238,238)"> dfs.webhdfs.enabled </td> 
 <td style="background-color:rgb(238,238,238)"> Enable/disable WebHDFS in Namenodes and Datanodes </td> 
 </tr> 
 <tr> 
 <td style="background-color:rgb(223,227,219)"> dfs.web.authentication.kerberos.principal </td> 
 <td style="background-color:rgb(223,227,219)"> 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. </td> 
 </tr> 
 <tr> 
 <td style="background-color:rgb(238,238,238)"> dfs.web.authentication.kerberos.keytab </td> 
 <td style="background-color:rgb(238,238,238)"> The Kerberos keytab file with the credentials for the HTTP Kerberos principal used by Hadoop-Auth in the HTTP endpoint. </td> 
 </tr> 
 </tbody> 
</table>

# 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][view plain]

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

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

**\[html\]**  [view plain][] [copy][view plain]

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

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

**\[html\]**  [view plain][] [copy][view plain]

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][view plain]

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

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

**\[html\]**  [view plain][] [copy][view plain]

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

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

**\[html\]**  [view plain][] [copy][view plain]

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][view plain]

1. curl -i -X POST"http://**<****HOST****>**:**<****PORT****>**/webhdfs/v1/**<****PATH****>**?op=APPEND\[&buffersize=**<****INT****>**\]"

请求重定向到要被附加数据的文件所在的datanode：

**\[html\]**  [view plain][] [copy][view plain]

1. HTTP/1.1 307TEMPORARY\_REDIRECT  
2. Location:http://**<****DATANODE****>**:**<****PORT****>**/webhdfs/v1/**<****PATH****>**?op=APPEND...  
3. Content-Length: 0

u  Step2：使用上边的Location Header的URL提交另一个附加了要被增加到文件的数据的HTTP POST请求：

**\[html\]**  [view plain][] [copy][view plain]

1. curl -i -X POST -T**<****LOCAL\_FILE****>**"http://**<****DATANODE****>**:**<****PORT****>**/webhdfs/v1/**<****PATH****>**?op=APPEND..."

客户端收到一个content-length为0的响应：

**\[html\]**  [view plain][] [copy][view plain]

1.  HTTP/1.1 200 OK  
2.  Content-Length: 0

可以参考上一部分的描述，为什么这个操作需要两步。

See also: buffersize, FileSystem.append

## Concat File(s) ##

u  提交一个HTTP POST请求

**\[html\]**  [view plain][] [copy][view plain]

1. curl -i -X POST"http://**<****HOST****>**:**<****PORT****>**/webhdfs/v1/**<****PATH****>**?op=CONCAT&sources=**<****PATHS****>**"

客户端收到一个content-length=0的响应：

**\[html\]**  [view plain][] [copy][view plain]

1.  HTTP/1.1 200 OK  
2.  Content-Length: 0

See also: FileSystem.getAclStatus

# Delegation Token Operations #

## Get Delegation Token ##

u  提交一个HTTP GET 请求

[html] view plain copy 
 
 curl -i "http://<HOST>:<PORT>/webhdfs/v1/?op=GETDELEGATIONTOKEN&renewer=<USER>"

客户端收到一个Token JSON对象的请求

[html] view plain copy 
      
       HTTP/1.1 200 OK   Content-Type: application/json   Transfer-Encoding: chunked       {     "Token":     {       "urlString": "JQAIaG9y..."     }   }

See also: renewer, FileSystem.getDelegationToken

## Get Delegation Tokens ##

u  提交一个HTTP GET请求

[html] view plain copy 
 
 curl -i "http://<HOST>:<PORT>/webhdfs/v1/?op=GETDELEGATIONTOKENS&renewer=<USER>"

客户端收到一个Tokens JSON格式的响应：

[html] view plain copy 
      
       HTTP/1.1 200 OK   Content-Type: application/json   Transfer-Encoding: chunked       {     "Tokens":     {       "Token":       [         {           "urlString":"KAAKSm9i ..."         }       ]     }   }

See also: renewer, FileSystem.getDelegationTokens

## Renew Delegation Token ##

u  提交一个HTTP PUT 请求

[html] view plain copy 
 
 curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/?op=RENEWDELEGATIONTOKEN&token=<TOKEN>"

客户端收到一个long型JSON对象的响应：

[html] view plain copy 
      
       HTTP/1.1 200 OK   Content-Type: application/json   Transfer-Encoding: chunked       {"long": 1320962673997}           //the new expiration time

See also: token, FileSystem.renewDelegationToken

## Cancel Delegation Token ##

u  提交一个HTTP PUT请求

[html] view plain copy 
 
 curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/?op=CANCELDELEGATIONTOKEN&token=<TOKEN>"

客户端收到一个Content-Length=0的响应：

[html] view plain copy 
      
       HTTP/1.1 200 OK   Content-Length: 0

See also: token, FileSystem.cancelDelegationToken

# Error Responses #

当一个操作失败，服务器可能会抛出一个错误。一个error响应的JSON格式定义在 RemoteExceptionJSON Schema中。下面的表格显示了exception到HTTP响应码的映射。

## HTTP Response Codes ##

<table style="color:rgb(51,51,51); font-family:Arial; font-size:14.44444465637207px; line-height:25.98958396911621px"> 
 <tbody> 
 <tr> 
 <td style="background-color:rgb(187,187,187)"> Exceptions </td> 
 <td style="background-color:rgb(187,187,187)"> HTTP Response Codes </td> 
 </tr> 
 <tr> 
 <td style="background-color:rgb(238,238,238)"> IllegalArgumentException </td> 
 <td style="background-color:rgb(238,238,238)"> 400 Bad Request </td> 
 </tr> 
 <tr> 
 <td style="background-color:rgb(221,221,221)"> UnsupportedOperationException </td> 
 <td style="background-color:rgb(221,221,221)"> 400 Bad Request </td> 
 </tr> 
 <tr> 
 <td style="background-color:rgb(238,238,238)"> SecurityException </td> 
 <td style="background-color:rgb(238,238,238)"> 401 Unauthorized </td> 
 </tr> 
 <tr> 
 <td style="background-color:rgb(221,221,221)"> IOException </td> 
 <td style="background-color:rgb(221,221,221)"> 403 Forbidden </td> 
 </tr> 
 <tr> 
 <td style="background-color:rgb(223,227,219)"> FileNotFoundException </td> 
 <td style="background-color:rgb(223,227,219)"> 404 Not Found </td> 
 </tr> 
 <tr> 
 <td style="background-color:rgb(221,221,221)"> RumtimeException </td> 
 <td style="background-color:rgb(221,221,221)"> 500 Internal Server Error </td> 
 </tr> 
 </tbody> 
</table>

下面是一些错误的响应的例子。

## Illegal Argument Exception ##

[html] view plain copy 
      
       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\": ..."     }   }

## Security Exception ##

[html] view plain copy 
      
       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: ..."     }   }

## Access Control Exception ##

[html] view plain copy 
      
       HTTP/1.1 403 Forbidden   Content-Type: application/json   Transfer-Encoding: chunked       {     "RemoteException":     {       "exception"    : "AccessControlException",       "javaClassName": "org.apache.hadoop.security.AccessControlException",       "message"      : "Permission denied: ..."     }   }

## File Not Found Exception ##

[html] view plain copy 
      
       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"     }   }

# **\[html\]**  [view plain][] [copy][view plain]  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 Schemas #

所有的操作，除了OPEN，要么返回一个长度为0的响应要么返回一个JSON响应。对于OPEN，响应是一个自己流。下面是JSON的模式。

注意，additionalProperties是默认值是一个空的模式，这允许为附加的属性设置任何值。因此，所有的WebHDFS JSON响应允许任何额外的属性。但是，如果响应中加入了额外的属性，为了保持兼容，它们被认为是可选的属性。

## ACL Status JSON Schema ##

[html] view plain copy 
      
       {     "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           },         }       }     }   }

## Boolean JSON Schema ##

[html] view plain copy 
      
       {     "name"      : "boolean",     "properties":     {       "boolean":       {         "description": "A boolean value",         "type"       : "boolean",         "required"   : true       }     }   }

See also: MKDIRS, RENAME, DELETE, SETREPLICATION

## ContentSummary JSON Schema ##

[html] view plain copy 
      
       {     "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           }         }       }     }   }

## FileChecksum JSON Schema ##

[html] view plain copy 
      
       {     "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           }         }       }     }   }