Apache HBase External APIs

    代表性状态传输（Representational State Transfer ）在2000年由Roy Fielding在其博士论文中提出（Roy Fielding是HTTP的主要作者之一。）

    REST本身并不在本文讨论的范围，REST允许客户-服务通过URL绑定在一起的API进行交互。本节讨论如何在HBase上配置并运行REST服务，将HBase表，行，cells以及元数据作为URL中特定的资源。

    REST服务可以作为集成的Jetty服务容器中的一部分，其服务部署于Jetty中。可以使用下面的命令在前后台来启动REST服务。端口是可选的，默认为8080。

    在前台运行时，使用ctrl-c来停止REST服务，在后台运行时，使用下面命令

    For information about configuring the REST server and client for SSL, as well as doAs impersonation for the REST server, see Configure the Thrift Gateway to Authenticate on Behalf of the Client and other portions of the Securing Apache HBase chapter.

    Table 12. Namespace Endpoints
    Endpoint HTTP Verb Description Example

    /namespaces

    GET

    列出所有命名空间

    		 
    1. curl -vi -X GET \
    2.   -H “Accept: text/xml” \
    3.   “http://example.com:8000/namespaces/“

    /namespaces/namespace

    GET

    描述某个特定的命名空间

    		 
    1. curl -vi -X GET \
    2.   -H “Accept: text/xml” \
    3.   ““

    /namespaces/namespace

    POST

    创建新的命名空间

    		 
    1. curl -vi -X POST \
    2.   -H “Accept: text/xml” \
    3.   “example.com:8000/namespaces/special_ns”

    /namespaces/namespace/tables

    GET

    		 
    1. curl -vi -X GET \
    2.   -H “Accept: text/xml” \
    3.   “http://example.com:8000/namespaces/special_ns/tables“

    /namespaces/namespace

    PUT

    修改某个已存在的表格。当前不被使用

    /namespaces/namespace

    DELETE

    删除一个命名空间，其必须为空

    		 
    1. curl -vi -X DELETE \
    2.   -H “Accept: text/xml” \
    3.   “example.com:8000/namespaces/special_ns”
    Table 14. Endpoints for Get Operations
    Endpoint HTTP Verb Description Example

    /table/row/column:qualifier/timestamp

    GET

    得到某行的值，该值是经过Base-64编码的

    		 
    1. curl -vi -X GET \
    2.   -H “Accept: text/xml” \
    3.   ““
    4.  
    5. curl -vi -X GET \
    6.   -H “Accept: text/xml” \
    7.   “http://example.com:8000/users/row1/cf:a/1458586888395“

    /table/row/column:qualifier

    获取某列的值，该值是经过Base-64编码的。

    		 
    1. curl -vi -X GET \
    2.   -H “Accept: text/xml” \
    3.   ““
    4.  
    5. curl -vi -X GET \
    6.   -H “Accept: text/xml” \
    7.    “http://example.com:8000/users/row1/cf:a/“

    /table/row/column:qualifier/?v=number_of_versions

    GET

    获取某个cell指定版本数量的值，该值经过Base-64编码的。
    Table 16. Endpoints for Put Operations
    Endpoint HTTP Verb Description Example

    /table/row_key

    PUT

    在表中增加一行。 行，列族，以及其值必须是Base-64编码的.要编码一段字符串，使用 命令行工具base64 . 要解码字符串base64 -d. 负载在参数 —data , and the /users/fakerow值为placeholder. 通过将它们加入<CellSet>来实现插入多行。也可以将数据保存到文件中并pass it to the -d parameter with syntax like -d @filename.txt.

    		 
    1. curl -vi -X PUT \
    2.   -H “Accept: text/xml” \
    3.   -H “Content-Type: text/xml” \
    4.   -d ‘<?xml version=”1.0” encoding=”UTF-8” standalone=”yes”?><CellSet><Row key=”cm93NQo=”><Cell column=”Y2Y6ZQo=”>dmFsdWU1Cg==</Cell></Row></CellSet>’ \
    5.   ““
    6.  
    7. curl -vi -X PUT \
    8.   -H “Accept: text/json” \
    9.   -H “Content-Type: text/json” \
    10.   -d ‘{“Row”:[{“key”:”cm93NQo=”, “Cell”: [{“column”:”Y2Y6ZQo=”, “$”:”dmFsdWU1Cg==”}]}]}’’ \
    11.   “example.com:8000/users/fakerow”
    		 
    1. <schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:tns="RESTSchema">
    3.       <element name="Version" type="tns:Version"></element>
    5.       <complexType name="Version">
    6.         <attribute name="REST" type="string"></attribute>
    7.         <attribute name="JVM" type="string"></attribute>
    8.         <attribute name="OS" type="string"></attribute>
    9.         <attribute name="Server" type="string"></attribute>
    10.         <attribute name="Jersey" type="string"></attribute>
    11.       </complexType>
    13.       <element name="TableList" type="tns:TableList"></element>
    15.         <sequence>
    16.               <element name="table" type="tns:Table" maxOccurs="unbounded" minOccurs="1"></element>
    17.         </sequence>
    18.       </complexType>
    20.     <complexType name="Table">
    21.         <sequence>
    22.               <element name="name" type="string"></element>
    23.         </sequence>
    24.       </complexType>
    26.       <element name="TableInfo" type="tns:TableInfo"></element>
    28.       <complexType name="TableInfo">
    29.         <sequence>
    30.               <element name="region" type="tns:TableRegion" maxOccurs="unbounded" minOccurs="1"></element>
    31.         </sequence>
    32.         <attribute name="name" type="string"></attribute>
    33.       </complexType>
    35.       <complexType name="TableRegion">
    36.         <attribute name="name" type="string"></attribute>
    37.         <attribute name="id" type="int"></attribute>
    38.         <attribute name="startKey" type="base64Binary"></attribute>
    39.         <attribute name="endKey" type="base64Binary"></attribute>
    40.         <attribute name="location" type="string"></attribute>
    41.       </complexType>
    43.       <element name="TableSchema" type="tns:TableSchema"></element>
    45.       <complexType name="TableSchema">
    46.         <sequence>
    47.               <element name="column" type="tns:ColumnSchema" maxOccurs="unbounded" minOccurs="1"></element>
    48.         </sequence>
    49.         <attribute name="name" type="string"></attribute>
    50.         <anyAttribute></anyAttribute>
    51.       </complexType>
    53.       <complexType name="ColumnSchema">
    54.         <attribute name="name" type="string"></attribute>
    55.         <anyAttribute></anyAttribute>
    56.       </complexType>
    58.       <element name="CellSet" type="tns:CellSet"></element>
    60.       <complexType name="CellSet">
    61.         <sequence>
    62.               <element name="row" type="tns:Row" maxOccurs="unbounded" minOccurs="1"></element>
    63.         </sequence>
    64.      </complexType>
    66.       <element name="Row" type="tns:Row"></element>
    68.       <complexType name="Row">
    69.         <sequence>
    70.               <element name="key" type="base64Binary"></element>
    71.               <element name="cell" type="tns:Cell" maxOccurs="unbounded" minOccurs="1"></element>
    72.         </sequence>
    73.       </complexType>
    75.       <element name="Cell" type="tns:Cell"></element>
    77.       <complexType name="Cell">
    78.         <sequence>
    79.               <element name="value" maxOccurs="1" minOccurs="1">
    80.                 <simpleType><restriction base="base64Binary">
    81.                 </simpleType>
    82.               </element>
    83.         </sequence>
    84.         <attribute name="column" type="base64Binary" />
    85.         <attribute name="timestamp" type="int" />
    86.       </complexType>
    88.       <element name="Scanner" type="tns:Scanner"></element>
    90.       <complexType name="Scanner">
    91.         <sequence>
    92.               <element name="column" type="base64Binary" minOccurs="0" maxOccurs="unbounded"></element>
    93.         </sequence>
    94.         <sequence>
    95.               <element name="filter" type="string" minOccurs="0" maxOccurs="1"></element>
    96.         </sequence>
    97.         <attribute name="startRow" type="base64Binary"></attribute>
    98.         <attribute name="endRow" type="base64Binary"></attribute>
    99.         <attribute name="batch" type="int"></attribute>
    100.         <attribute name="startTime" type="int"></attribute>
    101.         <attribute name="endTime" type="int"></attribute>
    102.       </complexType>
    104.       <element name="StorageClusterVersion" type="tns:StorageClusterVersion" />
    106.       <complexType name="StorageClusterVersion">
    107.         <attribute name="version" type="string"></attribute>
    108.       </complexType>
    110.       <element name="StorageClusterStatus"
    111.         type="tns:StorageClusterStatus">
    112.       </element>
    114.       <complexType name="StorageClusterStatus">
    115.            <sequence>
    116.               <element name="liveNode" type="tns:Node"
    117.                 maxOccurs="unbounded" minOccurs="0">
    118.               </element>
    119.               <element name="deadNode" type="string" maxOccurs="unbounded"
    120.                 minOccurs="0">
    121.               </element>
    122.         </sequence>
    123.         <attribute name="regions" type="int"></attribute>
    124.         <attribute name="requests" type="int"></attribute>
    125.         <attribute name="averageLoad" type="float"></attribute>
    126.       </complexType>
    128.       <complexType name="Node">
    129.         <sequence>
    130.               <element name="region" type="tns:Region"
    131.               </element>
    132.         </sequence>
    133.         <attribute name="name" type="string"></attribute>
    134.         <attribute name="startCode" type="int"></attribute>
    135.         <attribute name="requests" type="int"></attribute>
    136.         <attribute name="heapSizeMB" type="int"></attribute>
    137.         <attribute name="maxHeapSizeMB" type="int"></attribute>
    138.       </complexType>
    140.       <complexType name="Region">
    141.         <attribute name="name" type="base64Binary"></attribute>
    142.         <attribute name="stores" type="int"></attribute>
    143.         <attribute name="storefiles" type="int"></attribute>
    144.         <attribute name="storefileSizeMB" type="int"></attribute>
    146.         <attribute name="storefileIndexSizeMB" type="int"></attribute>
    147.       </complexType>
    149. </schema>
    1. message Version {
    2.       optional string restVersion = 1;
    3.       optional string jvmVersion = 2;
    4.       optional string osVersion = 3;
    5.       optional string serverVersion = 4;
    6.       optional string jerseyVersion = 5;
    7. }
    9. message StorageClusterStatus {
    10.       message Region {
    11.         required bytes name = 1;
    12.         optional int32 stores = 2;
    13.         optional int32 storefiles = 3;
    14.         optional int32 storefileSizeMB = 4;
    15.         optional int32 memstoreSizeMB = 5;
    16.         optional int32 storefileIndexSizeMB = 6;
    17.       }
    18.       message Node {
    19.         required string name = 1;    // name:port
    20.         optional int64 startCode = 2;
    21.         optional int32 requests = 3;
    22.         optional int32 heapSizeMB = 4;
    23.         optional int32 maxHeapSizeMB = 5;
    24.         repeated Region regions = 6;
    25.     }
    26.       // node status
    27.       repeated Node liveNodes = 1;
    28.       repeated string deadNodes = 2;
    29.       // summary statistics
    30.       optional int32 regions = 3;
    31.       optional int32 requests = 4;
    32.       optional double averageLoad = 5;
    33. }
    35. message TableList {
    36.       repeated string name = 1;
    37. }    
    39. message TableInfo {
    40.       required string name = 1;
    41.       message Region {
    42.         required string name = 1;
    43.         optional bytes startKey = 2;
    44.         optional bytes endKey = 3;
    45.         optional int64 id = 4;
    46.         optional string location = 5;
    47.       }
    48.       repeated Region regions = 2;
    49. }
    51. message TableSchema {
    52.       optional string name = 1;
    53.       message Attribute {
    54.         required string name = 1;
    55.         required string value = 2;
    56.       }
    57.       repeated Attribute attrs = 2;
    58.       repeated ColumnSchema columns = 3;
    59.       // optional helpful encodings of commonly used attributes
    60.       optional bool inMemory = 4;
    61.       optional bool readOnly = 5;
    62. }
    64. message ColumnSchema {
    65.       optional string name = 1;
    66.       message Attribute {
    67.         required string name = 1;
    68.         required string value = 2;
    69.       }
    70.       repeated Attribute attrs = 2;
    71.       // optional helpful encodings of commonly used attributes
    72.       optional int32 ttl = 3;
    73.       optional int32 maxVersions = 4;
    74.       optional string compression = 5;
    75. }
    77. message Cell {
    78.       optional bytes row = 1;       // unused if Cell is in a CellSet
    79.       optional bytes column = 2;
    80.       optional int64 timestamp = 3;
    81.       optional bytes data = 4;
    82. }
    84. message CellSet {
    85.       message Row {
    86.         required bytes key = 1;
    87.         repeated Cell values = 2;
    88.       }
    89.       repeated Row rows = 1;
    90. }
    92. message Scanner {
    93.       optional bytes startRow = 1;
    94.       optional bytes endRow = 2;
    95.       repeated bytes columns = 3;
    96.       optional int32 batch = 4;
    97.       optional int64 startTime = 5;
    98. }

    Documentation about Thrift has moved to Thrift API and Filter Language.

    Example 41. JDO Example

    This example uses JDO to create a table and an index, insert a row into a table, get a row, get a column value, perform a query, and do some additional HBase operations.