table of contents -...

1.1

1.2

1.3

1.4

TableofContents

通用请求

集群操作请求

作业操作请求

数据类型

1

API参考手册

　　本指南提供了KMR（KingsoftMapReduce）API的说明及使用案例。

　　KMR（KingcloudMapReduce）是一个可伸缩的通用数据计算和分析平台，它以

ApacheHadoop和ApacheSpark两大数据计算框架为基础，通过自动调度弹性计算服务

（KEC），帮助您快速构建分布式数据分析系统。

　　KMR提供了用于集群操作的OpenAPI和SDK,您可以根据需要开发应用程序，实现集群创

建、释放，作业下发，集群和作业状态监控等多种自动化任务。

　　通用请求部分介绍了API服务的基本信息，公共参数，签名机制和报错信息等内容。

　　集群操作请求部分介绍了用于KMR集群操作的API和编程示例。

　　作业操作请求部分介绍了集群计算作业相关的API和编程示例。

　　数据类型部分介绍了KMRAPI自定义的数据类型。

API参考手册

68

通用请求

1.服务信息

2.公共参数

3.签名机制

4.通用错误信息

1.服务信息

服务地址

　　金山云KMR服务接入地址：

　　•　北京地区：kmr.cn-beijing-6.api.ksyun.com　　•　上海地区：kmr.cn-shanghai-2.api.ksyu.com

通讯协议

　　支持HTTP或HTTTPS协议进行通信。

请求方法

　　使用POST方法发送请求。

请求参数

　　每个请求都需要指定要执行的操作，即X-Action参数（例如ListClusters），以及每个操

作都需要包含的公共请求参数和指定操作所特有的请求参数。

编码方式

　　请求及返回结果都使用UTF-8字符集进行编码。

返回结果

　　仅支持json格式的返回结果。

2.公共参数

通用请求

69

名称描述是否必须

Host KMR服务的Hostname 是

Authorization 授权参数是

Content-Type 数据结构类型（application/json）是

X-Action 请求的目标操作，例如：ListClusters 是

X-Version 请求的目标操作，例如：2016-05-20 是

X-Ksc-Content-Sha256 Sha256哈希值，用于计算签名否

X-Ksc-Date 请求发出的时间，格式：yyyyMMdd'T'HHmmss'Z' 是

3.签名机制

　　发送给KMR服务的HTTP请求中，必须包含授权参数和其他公共参数。KMR服务使用用

户的AccessKeyID和SecretAccessKey进行加密方式来验证请求者的身份。AccessKeyID和SecretAccessKey由金山云发给用户，AccessKeyID作为用户的身份标识，SecretAccessKey作为用户和服务器端进行签名计算的密钥。

　　Http请求header中Authorization字段是服务的授权参数，其格式为：

Authorization="[HashMethod][空格]Credential=[access_key]/[scope],SignedHeaders=[signed_

headers],Signature=[signature]"

　　其中：

　　[HashMethod]="KSC4-HMAC-SHA256"　　[access_key]=用户AccesskeyID　　[scope]=[timestamp]/[region]/[service][req_type]　　timestamp为yyyyMMdd格式的时间戳，region为请求服务所在区域名，service为访问的

服务名，req_type为请求的类型。

　　[signed_headers]：将Headers按照name升序排列

　　[signed_headers]=[header_name_1];[header_name_2]....

　　签名算法：

[signature]=sha256(sha256(sha256(sha256(sha256("KSC4"+sign_key,timestamp),region),ser

vice),req_type),string_to_sign)

　　其中：

通用请求

70

　　[sign_key]=用户SecretAccessKey　　[stringToSign]="KSC4-HMAC-SHA256"+"\n"　　　　　+[X-Ksc-Date]+"\n"　　　　　+[scope]+“\n”　　　　　+SHA-256([canonical_request])　　[canonical_request]=[HTTPRequestMethod]+"\n"　　　　　+[CanonicalURI]+"\n"　　　　　+[CanonicalQueryString]+"\n"　　　　　+[CanonicalHeaders]+"\n"　　　　　+[signed_headers]+"\n"　　　　　+SHA-256([request_body])　　[HTTPRequestMethod]=POST或GET　　[CanonicalURI]=请求URL中除去Endpoint之外的剩余部分。目前URL等于Endpoint，所

以CanonicalURI为空

　　[CanonicalQueryString]=空　　[CanonicalHeaders]：按照[signed_headers]中的排序方式进行排序

　　[CanonicalHeaders]=　　　　　　LowerCase(HeaderName1)+‘:’+Trim(HeaderValue1)+"\n"　　　+LowerCase(HeaderName2)+‘:’+Trim(HeaderValue2)+"\n"　　　　　　+.......　　[request_body]=Post请求的body部分

　　

　　Python版签名代码示例：

通用请求

71

defcanonical_request(self,http_request,sign_headers):

cr=[]

cr.append(http_request.method.upper())

cr.append(self.canonical_uri(http_request))

cr.append(self.canonical_query_string(http_request))

headers_to_sign=self.headers_to_sign(http_request,sign_headers)

cr.append(self.canonical_headers(headers_to_sign)+'\n')

cr.append(self.signed_headers(headers_to_sign))

ifself.header_name_content_sha256inhttp_request.headers:

content_hash=self._ensure_bytes(http_request.headers[self.header_name_co

ntent_sha256])

cr.append(content_hash)

else:

cr.append(self.payload(http_request))

return'\n'.join(cr)

defstring_to_sign(self,http_request,canonical_request,scope):

sts=[self.hash_method]

sts.append(http_request.headers[self.header_name_date])

sts.append(scope)

sts.append(sha256(canonical_request.encode('utf-8')).hexdigest())

return'\n'.join(sts)

def_sign(self,key,msg,hex=False):

key=self._ensure_bytes(key)

ifhex:

sig=hmac.new(key,msg.encode('utf-8'),sha256).hexdigest()

else:

sig=hmac.new(key,msg.encode('utf-8'),sha256).digest()

returnsi

defsignature(self,string_to_sign,scope,secret_key):

parts=scope.split('/')

ts=parts[0]

region=parts[1]

service=parts[2]

req_type=parts[3]

k_date=self._sign((self.hash_keyword+secret_key).encode('utf-8'),ts)

k_region=self._sign(k_date,region)

k_service=self._sign(k_region,service)

k_signing=self._sign(k_service,req_type)

returnself._sign(k_signing,string_to_sign,hex=True)

4.通用错误信息

通用请求

72

错误码错误名称错误描述

400 APIExceptionUNKNOWN_EXCEPTION

调用API异常遇到未知的异常

403 FORBIDDEN 请求被禁止

404 NOT_FOUND 未找到请求的API

500 INTERNAL_SERVER_ERROR 服务内部错误

501 NOT_IMPLEMENTED_ERROR API未实现

通用请求

73

集群操作请求

1.ListClusters

2.DescribeCluster

3.LaunchCluster

4.TerminateClusters

5.SetTerminationProtection

6.ListInstanceGroups

7.AddInstanceGroups

8.ModifyInstanceGroups

9.ListInstances

10.ListDistributions

1.ListClusters

功能描述

　　列出当前账户可见的所有KMR集群状态信息，允许您基于特定的条件对这些信息进行筛

选；例如，基于集群创建日期和时间来筛选。每次调用默认返回100个集群，每次最多返回

100个，同时会返回一个Marker来对多次ListClusters请求调用进行分页跟踪。

请求参数

　　关于所有操作使用的通用参数信息，请参考通用请求"公共参数"部分

　　ClusterStates.member.N

　　　　需要列出的集群状态。

　　　　类型：String列表

　　　　可选值：STARTING|RUNNING|RESIZING|TRANSFERINGLOG|TERMINATED|TERMINATED_WITH_ERRORS　　　　是否必须：否

　　CreatedAfter

集群操作请求

74

　　　　列出在某个日期和时间之后创建的集群。

　　　　类型：DateTime　　　　是否必须：否

　　CreatedBefore

　　　　列出在某个日期和时间之前创建的集群。

　　　　类型：DateTime　　　　是否必须：否

　　Marker

　　　　分页标识。

　　　　类型：String　　　　是否必须：否

返回参数

　　返回结果包含以下字段：

　　Clusters

　　　　当前账户满足请求中给出的过滤条件的集群列表

　　　　类型：ClusterSummary列表ClusterSummary

　　Marker

　　　　用于获取下一页结果集的分页标识

　　　　类型：String

错误信息

　　关于所有操作使用的通用错误信息，参考通用请求"通用错误信息"部分

　　InternalServerError

　　　　当KMR服务出现内部错误时出现该错误信息类型

　　　　HTTP状态码：500

　　BadRequest

　　　　当用户输入信息有误时出现该错误信息


样例

　　请求样例

集群操作请求

75

POST/HTTP/1.1

Content-Type:application/json

X-Action:ListClusters

X-Version:2016-05-20

{

"ClusterStates":["RUNNING","TERMINATED"]

"CreatedAfter":"2016-01-08T19:00:00"

}

　　返回样例

HTTP/1.1200OK


Content-Length:xxx

{

"Marker":"offset=15&limit=5",

"Clusters":[

{

"Status":{

"State":"RUNNING"

},

"NormalizedInstanceMins":14,

"Id":"0b875523-9e95-454a-8fff-f9e592303d95",

"Name":"test-cluster-ops-03"

},

{

"Status":{

"State":"RUNNING"

},


"Id":"26e6d8af-18e2-49b6-b7d1-040dfb170b3b",

"Name":"test-cluster-ops-01"

}

]

}

2.DescribeCluster

功能描述

　　列出某个当前用户可见的集群详细信息，包括状态，硬件，软件设置等。

请求参数


　　ClusterId

集群操作请求

76

　　　　需要列出实例组信息的集群标识。

　　　　类型：String　　　　是否必须：是　　

返回参数


　　Cluster

　　　　请求中集群的详细信息

　　　　类型：ClusterConfigClusterConfig

错误信息





　　BadRequest



样例

　　请求样例

POST/HTTP/1.1


X-Action:DescribeCluster


{

"ClusterId":"ffd8270a-48e0-4f68-8a35-0f8562302ad6"

}

　　返回样例

集群操作请求

77

HTTP/1.1200OK


Content-Length:xxx

{

"InstanceAttributes":[],

"Name":"lxk-quota-test-0",

"ServiceRole":null,

"TerminationProtected":false,

"HadoopVersion":"hadoop2.6.0",

"LogUri":"ks3://kmrhkbj/lxk-log",

"AutoTerminate":false,

"Status":{

"State":"RUNNING"

},

"MasterPublicDnsName":"120.168.113.60",


"Applications":[

"hadoop"

],

"Id":"ffd8270a-48e0-4f68-8a35-0f8562302ad6"

}

3.LaunchCluster

功能描述

　　创建集群操作，操作成功后会创建一个KMR集群，如果参数中带有作业配置，则集群创

建成功后将自动运行指定的作业。如果AutoTerminate设置为True，则作业运行完毕后集群不

会释放，反之集群会在所有作业完成后自动释放；关于参数中TerminationProtected的设置及

原理介绍请参见SetTerminationProtection部分。

请求参数


　　Distribution

　　　　Hadoop发行版本说明。支持“kmr-1.0.0”与“kmr-2.0.0”。　

　　　　类型：String　　　　默认：“kmr-2.0.0”　　　　是否必须：否

　　Applications.member.N

集群操作请求

78

　　　　安装应用列表。可选值

为“hadoop”，“hive”，“hbase”，“spark”，“storm”，“kafka”等，区分大小写。如果不填则默认

为“hadoop”。　　　　类型：String列表

　　　　是否必须：否

　　InstanceGroups.member.N

　　　　集群里虚机的配置和数目信息。

　　　　类型：InstanceGroupConfig列表InstanceGroupConfig　　　　是否必须：是

　　IsTransient

　　　　是否为临时集群。

　　　　类型：Boolean　　　　默认：False　　　　是否必须：否

　　ChargeType

　　　　集群计费类型：包年包月"Monthly"，按需付费"Minutely"，免费试用"FreeTrial"。　　　　包年包月"Monthly"：包月集群，有到期时间。

　　　　按需付费"Minutely"：按分钟计费，按月结算。

　　　　免费试用"FreeTrial"：用户有试用quota时能创建出免费试用集群。

　　　　类型：String　　　　默认："Minutely"　　　　是否必须：否

　　PurchaseTime

　　　　集群购买时长，单位月。“包年包月”必须要选择，有效值1-36；其余计费类无需此项

内容（系统按0处理）。

　　　　类型：Integer　　　　是否必须：否

　　MetaDatabaseUri

　　　　元数据管理的数据库信息。

　　　　元数据主要指集群监控元数据，Hive的元数据管理等。当用户选择集群外的RDS或者自建MySql来管理元数据时需要填写。

　　　　类型：String　　　　格式：mysql://{username}:{password}@{hostname}:{port}　　　　是否必须：否

集群操作请求

79

　　TerminationProtected

　　　　集群是否启用释放保护锁。

　　　　类型：Boolean　　　　默认：True　　　　是否必须：否

　　VpcDomainId

　　　　集群所属的虚拟专有网络（VPC）信息。

　　　　类型：String　　　　是否必须：是

　　VpcSubnetId

　　　　集群所属的虚拟专有网络（VPC）子网信息。


　　VpcEndpointId

　　　　集群所属的虚拟专有网络（VPC）的Endpoint子网信息，用于创建KMR部署使用的

相关网络资源比如内网LB。　　　　类型：String　　　　是否必须：是

　　LogUri

　　　　日志输出的KS3路径，格式为：“KS3://bucket/object_key”。如果不填则日志不会输

出到KS3。　　　　类型：String　　　　是否必须：否

　　Name

　　　　集群的名称。仅支持大小写字母、数字、减号和下划线。


　　Steps.member.N

　　　　自定义需要运行的作业列表。(常驻集群暂不支持)　　　　类型：StepConfig列表StepConfig　　　　是否必须：否

　　EnableEIP

集群操作请求

80

　　　　是否启用eip信息，如果设置为True，则集群的Master节点会被分配一个外网ip，默

认为False。　　　　类型：String　　　　是否必须：否

　　Configurations.member.N

　　　　所创建集群的配置信息。

　　　　类型：Configuration列表Configuration　　　　是否必须：否

　　BootstrapActions.member.N

　　　　集群引导操作列表

　　　　类型：BootstrapAction列表BootstrapAction　　　　是否必须：否　　

返回参数


　　ClusterId

　　　　创建成功的集群ID　　　　类型：String

错误信息





　　BadRequest



样例

　　请求样例

集群操作请求

81

POST/HTTP/1.1


X-Action:LaunchCluter


{

"Name":"api-test",

"AutoTerminate":False，

"InstanceGroups":[

{

"InstanceType":"kmr.general",

"InstanceCount":1,

"InstanceGroupType":"MASTER"

},

{

"InstanceType":"kmr.general",

"InstanceCount":2,

"InstanceGroupType":"CORE"

}

],

"Steps":[

{

"ActionOnFailure":"CONTINUE",

"Name":"java_test",

"HadoopJarStep":{

"Args":[

"ks3://kmr-bj-test/input",

"ks3://kmr-bj-test/output"

],

"Type":"MapReduce",

"Jar":"ks3://kmr-bj-test/jobtest/job.jar",

"MainClass":"org.apache.hadoop.examples.WordCount"

}

}

]

}

　　返回样例

HTTP/1.1200OK


Content-Length:xxx

{

"ClusterId":"ffd8270a-48e0-4f68-8a35-0f8562302ad6"

}

4.TerminateClusters

集群操作请求

82

功能描述

　　释放指定的一个或者多个集群。当集群释放时，尚未完成的作业将被取消，集群所使用

的云主机都将被释放，但如果集群设置了日志归集功能（创建集群时给出了LogUri），则所

有日志都会被完整的上传至KS3。

　　请求允许释放的最大集群数量为10。集群释放是一个异步操作，请求会立即返回，根据

集群的配置，可能需要5-20分钟才能完全释放掉集群所有的资源，比如云主机实例。

请求参数


　　ClusterIds.member.N

　　　　需要释放的集群ID列表。


　　　　长度限制：最小0个，最大10个　　　　是否必须：是

返回参数

　　返回结果不包含任何字段

错误信息





　　BadRequest



样例

　　请求样例

POST/HTTP/1.1


X-Action:TerminateClusters


{

"ClusterIds":["26e6d8af-18e2-49b6-b7d1-040dfb170b3b"]

}

集群操作请求

83

　　返回样例

HTTP/1.1200OK


Content-Length:2

{}

5.SetTerminationProtection

功能描述

　　设置集群释放保护锁。保护集群和云主机不会因为用户干预（控制台、API调用等）而被

释放。

　　如果集群设置了自动释放功能，而且所有作业运行完毕，则集群将不受释放保护功能的

影响，可以自动释放。

　　如果想释放开启了释放保护锁的集群，则必须要先调通此API，将释放保护设置为false，然后释放集群。

请求参数


　　ClusterIds.member.N

　　　　需要释放的集群ID列表。


　　　　长度限制：最小0个，最大10个　　　　是否必须：是


　　　　指示是否开启释放保护功能的布尔值。

　　　　类型：Boolean　　　　是否必须：是

返回参数


错误信息



集群操作请求

84



　　BadRequest



样例

　　请求样例

POST/HTTP/1.1


X-Action:SetTerminationProtection


{

"ClusterIds":["26e6d8af-18e2-49b6-b7d1-040dfb170b3b"],

"TerminationProtected":true

}

　　返回样例

HTTP/1.1200OK


Content-Length:2

{}

6.ListInstanceGroups

功能描述

　　提供了集群中每个实例组的详细信息。

请求参数


　　ClusterId



　　Marker

集群操作请求

85



返回参数


　　InstanceGroups

　　　　基于给定过滤条件返回指定集群的实例组列表

　　　　类型：InstanceGroup列表InstanceGroup

　　Marker



错误信息





　　BadRequest



样例

　　请求样例

POST/HTTP/1.1


X-Action:ListInstanceGroups


{

"ClusterId":"e1b637b5-210d-45b3-bc16-0338b3c8cf8e"

}

　　返回样例

集群操作请求

86

HTTP/1.1200OK


Content-Length:462

Date:Thu,07Jan201602:57:57GMT

{

"Marker":null,

"InstanceGroups":[

{

"Status":{

"State":"RUNNING"

},

"InstanceCount":2,

"Name":"gn-e51f56af-CORE",

"InstanceGroupType":"CORE",

"InstanceType":"kmr.compute",

"Id":"e1b637b5-210d-45b3-bc16-0338b3c8cf8e-gn-e51f56af-CORE"

},

{

"Status":{

"State":"RUNNING"

},

"InstanceCount":1,

"Name":"gn-e51f56af-MASTER",

"InstanceGroupType":"MASTER",

"InstanceType":"kmr.compute",

"Id":"e1b637b5-210d-45b3-bc16-0338b3c8cf8e-gn-e51f56af-MASTER"

}

]

}

7.AddInstanceGroups

功能描述

　　AddInstanceGroups用于添加实例组，目前仅支持添加一个任务实例组。一个集群中最多

只能有一个任务实例组。

请求参数


　　ClusterId

　　　　需要添加实例组信息的集群标识。



集群操作请求

87

　　　　需要添加的InstanceGroup配置列表

　　　　类型：InstanceGroupConfig列表InstanceGroupConfig　　　　是否必须：是　　

返回参数


　　InstanceGroupIds

　　　　添加成功的实例组ID列表。


错误信息





　　BadRequest



样例

　　请求样例

POST/HTTP/1.1


X-Action:AddInstanceGroups


{

"ClusterId":"e1b637b5-210d-45b3-bc16-0338b3c8cf8e",

"InstanceGroups":[

{

"InstanceGroupType":"TASK",

"InstanceCount":1,

"InstanceType":"kmr.compute"

}

]

}

　　返回样例

集群操作请求

88

HTTP/1.1200OK


Content-Length:2

{"InstanceGroupIds":[

"bb26aa5a-4032-4b0d-9037-82c6b715c241"

]

}

8.ModifyInstanceGroups

功能描述

　　ModifyInstanceGroups用于修改集群实例组的实例个数或实例组配置信息，如果修改了

实例组个数,集群就会进行相应的扩容或缩容。

请求参数


　　ClusterId




　　　　InstanceGroup类型列表。

　　　　类型：InstanceGroupConfig列表InstanceGroupConfig　　　　是否必须：是

返回参数


错误信息





　　BadRequest

集群操作请求

89



样例

　　请求样例

POST/HTTP/1.1


X-Action:ModifyInstanceGroups


{


"InstanceGroups":[

{

"InstanceGroupId":"e1b637b5-210d-45b3-bc16-0338b3c8cf8e-gn-e51f56af-CORE"

,

"InstanceCount":3,

"InstanceIdsToTerminate":[]

}

]

}

　　返回样例

HTTP/1.1200OK


Content-Length:2

{}

9.ListInstances

功能描述

　　提供了KMR集群中的实例信息，这些实例是您在创建集群时由KMR服务帮您申请的虚拟

机实例。您可以根据实例组标识、实例组角色选择您想查看的实例，每次调用可以返回最多

50个实例，但可以返回一个marker来跟踪跨多个ListInstances簇列表分页调用。

请求参数


　　ClusterId

集群操作请求

90



　　InstanceGroupId

　　　　需要列出实例的实例组ID，如果不提供默认值，列出所有实例组的实例


　　InstanceGroupTypes

　　　　需要列出的实例的实例组角色，合法的实例组角色有:MASTER、CORE、TASK，如果不提供默认提供所有角色的实例组中的实例



　　Marker



返回参数


　　Instances

　　　　Instance结果

　　　　类型：Instance列表Instance

　　Marker



错误信息





　　BadRequest

集群操作请求

91



样例

　　请求样例

GET/HTTP/1.1

POST/HTTP/1.1


X-Action:ListInstances


{


"InstanceGroupId":"",

"InstanceGroupTypes":["MASTER"]

}

　　返回样例

HTTP/1.1200OK


Content-Length:186


{

"Marker":null,

"Instances":[

{

"Status":{

"State":"RUNNING"

},

"Id":"079d2b1f-cb1f-4365-acbb-c1b3f7424831",

"PrivateIpAddress":"10.168.113.134",

"PublicIpAddress":"10.168.113.134"

}

]

}

10.ListDistributions

功能描述

　　提供了KMR集群可用的发行版信息，以及发行版里面支持的应用信息。

请求参数


集群操作请求

92

返回参数


　　Distributions

　　　　发行版列表

　　　　类型：Distribution列表Distribution

错误信息





　　BadRequest



样例

　　请求样例

GET/HTTP/1.1

POST/HTTP/1.1


X-Action:ListDistributions


{

}

　　返回样例

集群操作请求

93

HTTP/1.1200OK


Content-Length:328


{

"Distributions":

[

{

"Release":"1.0.0",

"Applications":

[

{

"Release":"2.6.0",

"Required":true,

"Name":"hadoop"

},

{

"Release":"0.14.0",

"Required":true,

"Name":"hive"

},

{

"Release":"0.10.0",

"Required":true,

"Name":"pig"

},

{

"Release":"1.5.2",

"Required":false,

"Name":"spark"

}

],

"Vendor":"KSYUN",

"Name":"kmr-1.0.0"

}

]

}

集群操作请求

94

作业操作请求

1.ListSteps

2.DescribeStep

3.AddSteps

1.ListSteps

功能描述

　　列出指定集群的作业状态信息，允许您基于特定的条件对这些信息进行筛选；例如，基

于作业状态筛选。每次调用默认返回100个作业，每次最多返回100个，同时会返回一个

Marker来对多次ListSteps请求调用进行分页跟踪。

请求参数


　　ClusterId

　　　　需要查询的集群ID。　　　　类型：String　　　　是否必须：是

　　StepIds

　　　　需要列出的作业ID，用于过滤条件。

　　　　类型：Sting列表


　　StepStates.member.N

　　　　需要列出的集群状态。


　　　　可选值：PENDING|RUNNING|COMPLETED|CANCELLED|FAILED|INTERRUPTED|TRANSFERINGLOG　　　　是否必须：否

　　Marker

作业操作请求

95



返回参数


　　Steps

　　　　满足请求中给出的过滤条件的作业列表。

　　　　类型：Step列表Step

　　Marker

　　　　用于获取下一页结果集的分页标识。


错误信息





　　BadRequest



样例

　　请求样例

POST/HTTP/1.1


X-Action:ListSteps


{

"StepStates":["RUNNING","PENDING"]

}

　　返回样例

作业操作请求

96

HTTP/1.1200OK


Content-Length:xxx

{

"Marker":null,

"Steps":[

{

"Status":{

"State":"RUNNING"

},

"HadoopJarStep":{

"Args":[

"-input",

"ks3://yourbucket/input",

"-output",

"ks3://yourbucket/output",

"-mapper",

"ks3://yourbucket/mapper.py",

"-reducer"

"ks3://yourbucket/reducer.py",

"-numMapTasks",

"1",

"-numReduceTasks",

"1",

"-args",

""

],

"Type":"MapReduce.Streaming",

"Jar":"ks3://kmr/libs/hadoop-streaming.jar",

"Properties":{}

},

"DurationMins":2,

"Name":"streaming-type-job"


"StepType":"MapReduce",

"Id":"56964e88c-cb6e-4592-be97-53a5e2a2bfde",

"CreatedAt":"2016-01-08T12:10:07"

}

]

}

2.DescribeStep

功能描述

　　查询指定集群中一个指定作业的详细信息

请求参数

作业操作请求

97


　　ClusterId

　　　　需要查询的集群ID。　　　　类型：String　　　　是否必须：是

　　StepId

　　　　需要列出的作业ID　　　　类型：Sting　　　　是否必须：是

返回参数


　　Step

　　　　需要查询作业的详细信息。

　　　　类型：StepStep

错误信息





　　BadRequest



样例

　　请求样例

POST/HTTP/1.1


X-Action:DescribeStep


{

"ClusterId":"366bb23b-ef63-494d-acb8-3d26d6375da9",

"StepId":"56964e88c-cb6e-4592-be97-53a5e2a2bfde"

}

作业操作请求

98

　　返回样例

HTTP/1.1200OK


Content-Length:2

{

"Step":{

"Status":{

"State":"RUNNING"

},

"HadoopJarStep":{

"Args":[

"-input",


"-output",


"-mapper",


"-reducer"


"-numMapTasks",

"1",

"-numReduceTasks",

"1",

"-args",

""

],



"Properties":{}

},



"Id":"56964e88c-cb6e-4592-be97-53a5e2a2bfde"

}

}

3.AddSteps

功能描述

　　向指定集群批量添加作业。您需要指定集群ID以及相应的作业参数。支持MapReduce、MapReduce.Streming、Pig、Hive、Spark共5种类型作业。（常驻集群暂不支持）

请求参数


作业操作请求

99

　　ClusterId

　　　　需要添加作业的目标集群ID。　　　　类型：String　　　　是否必须：是

　　Steps.member.N

　　　　需要添加的自定义作业列表。

　　　　类型：StepConfig列表StepConfig　　　　是否必须：是　

返回参数


　　StepIds

　　　　添加成功的作业ID列表。


错误信息





　　BadRequest



样例

　　请求样例

作业操作请求

100

POST/HTTP/1.1


X-Action:AddSteps


{

"JobFlowId":"366bb23b-ef63-494d-acb8-3d26d6375da9",

"Steps":[

{

"HadoopJarStep":{

"Args":[

"-input",


"-output",


"-mapper",


"-reducer"


"-numMapTasks",

"1",

"-numReduceTasks",

"1",

"-args",

""],


"Properties":{}

},




}

]

}

　　返回样例

HTTP/1.1200OK


Content-Length:xxx

{

"StepIds":[

"56964e88c-cb6e-4592-be97-53a5e2a2bfde"

]

}

作业操作请求

101

数据类型

　　KMRAPI使用了多种自定义数据类型，本章节将对这些数据类型做详细介绍

1.ClusterConfig

2.ClusterStatus

3.StepConfig

4.Step

5.HadoopJarStepConfig

6.StepStatus

7.ClusterSummary

8.InstanceGroup

9.InstanceGroupStatus

10.Instance

11.InstanceStatus

12.InstanceGroupConfig

13.Configuration

14.BootstrapAction

15.ScriptBootstrapAction

16.Distribution

17.Application

1.ClusterConfig

　　Applications

　　　　集群安装的应用列表。


　　　　可选值:可选值为“hadoop”，“hive”，“pig”与“spark”，区分大小写。任何集群都会默

数据类型

102

认会带上“hadoop”　　　　是否必须：否

　　IsTransient

　　　　是否为临时集群。

　　　　类型：Boolean　　　　是否必须：否

　　ChargeType

　　　　集群计费类型：包年包月"Monthly"，按需付费"Minutely"，免费试用"FreeTrial"。　　　　包年包月"Monthly"：包月集群，有到期时间。

　　　　按需付费"Minutely"：按分钟计费，按月结算。

　　　　免费试用"FreeTrial"：用户有试用quota时能创建出免费试用集群。


　　Distribution

　　　　集群选用的Hadoop发行版本信息，支持“kmr-1.0.0”与“kmr-2.0.0”。　　　　类型：String　　　　是否必须：否

　　PurchaseTime

　　　　集群购买时长，单位为月，仅限“包年包月”计费类型。


　　MetaDatabaseUri

　　　　元数据管理的数据库信息。

　　　　元数据主要指集群监控元数据，Hive的元数据管理等。


　　Id

　　　　集群ID。　　　　类型：String　　　　是否必须：否

　　InstanceAttributes

数据类型

103

　　　　集群主机的参数，现阶段为空。



　　LogUri

　　　　日志归集的KS3路径。


　　MasterPublicIP

　　　　如果集群创建EnableEIP，则为公网IP地址，否则为空。


　　Name

　　　　集群名称。


　　ServingMinutes

　　　　集群运行时间，从实例创建成功到集群释放，以分钟为单位。如果集群已经结束，

则计时段为创建时间至释放时间；如果集群尚未结束，则为创建时间至现在的分钟数。本时

间只是对集群运行时间的预估，并不反应实际记费时间。


　　Status

　　　　集群状态信息。

　　　　类型：ClusterStatusClusterStatus　　　　是否必须：否


　　　　集群是否启用释放保护锁。

　　　　类型：Boolean　　　　是否必须：否

　　VpcDomainId

　　　　集群所属的虚拟专有网络（VPC）信息。


数据类型

104

　　VpcSubnetId

　　　　集群所属的虚拟专有网络（VPC）子网信息。


　　VpcEndpointId

　　　　集群所属的虚拟专有网络（VPC）的Endpoint子网信息，用于创建KMR部署使用的

相关网络资源比如内网LB。　　　　类型：String　　　　是否必须：否

　　Configurations

　　　　集群配置信息


　　BootstrapActions

　　　　集群引导操作列表

　　　　类型：BootstrapAction列表BootstrapAction　　　　是否必须：否

2.ClusterStatus

　　State

　　　　集群状态。

　　　　类型：String　　　　可选值：STARTING|RUNNING|TERMINATING|TERMINATED|TERMINATED_WITH_ERRORS　　　　是否必须：否

3.StepConfig

　　ActionOnFailure

　　　　作业失败策略。

　　　　类型：String　　　　可选值:TERMINATE_JOB_FLOW|TERMINATE_CLUSTER|

数据类型

105

CANCEL_AND_WAIT|CONTINUE　　　　是否必须：否

　　HadoopJarStep

　　　　配置作业使用的jarfile。　　　　类型：HadoopJarStepConfigHadoopJarStepConfig　　　　是否必须：是

　　Name

　　　　作业名称。

　　　　类型：String　　　　长度限制：0-256　　　　是否必须：是

　　Type

　　　　作业类型。

　　　　类型：String　　　　可选值：MapReduce|MapReduce.Streming|Pig|Hive|Spark　　　　是否必须：是

4.Step

　　ActionOnFailure

　　　　作业失败策略。

　　　　类型：String　　　　可选值:TERMINATE_JOB_FLOW|TERMINATE_CLUSTER|CANCEL_AND_WAIT|CONTINUE　　　　是否必须：否

　　HadoopJarStep

　　　　配置作业使用的jarfile。　　　　类型：HadoopJarStepConfigHadoopJarStepConfig　　　　是否必须：否

　　Name

　　　　作业名称。

　　　　类型：String　　　　长度限制：0-256

数据类型

106


　　Type

　　　　作业类型。

　　　　类型：String　　　　可选值：MapReduce、MapReduce.Streming、Pig、Hive、Spark　　　　是否必须：是

　　Id

　　　　作业ID。　　　　类型：String　　　　是否必须：否

　　Status

　　　　作业状态。

　　　　类型：StepStatusStepStatus　　　　是否必须：否

5.HadoopJarStepConfig

　　Args

　　　　指定命令行列表传递给jarfile的main函数。



　　Jar

　　　　指定作业的jarfile路径。


　　MainClass

　　　　指定javefile中mainclass名称。如果没有指定，jarfile需要在manifest文件中指定。


　　Properties

数据类型

107

　　　　为作业运行指定key-value列表，你可以在你的主函数中使用这些key-value。　　　　类型：KeyValue列表


6.StepStatus

　　State

　　　　作业运行状态。

　　　　类型：String　　　　可选值：PENDING|RUNNING|COMPLETED|CANCELLED|FAILED|INTERRUPTED|TRANSFERINGLOG　　　　是否必须：否

7.ClusterSummary

　　Id

　　　　集群的唯一标识符，通常为UUID格式


　　Name

　　　　集群名称


　　ServingMinutes

　　　　集群运行时间，从实例创建成功到集群释放，以分钟为单位。如果集群已经结束，

则计时段为创建时间至释放时间；如果集群尚未结束，则为创建时间至现在的分钟数。本时

间只是对集群运行时间的预估，并不反应实际记费时间。


　　Status

　　　　集群当前的状态信息

　　　　类型：ClusterStatusClusterStatus　　　　是否必须：否

数据类型

108

8.InstanceGroup

　　Id

　　　　实例组Id　　　　类型：String　　　　是否必须：否

　　Name

　　　　实例组名


　　InstanceGroupType

　　　　实例组类型，相同的机器类型与相同的服务角色列表组成的一组机器。在"KMR2.0.0"中无TASK类型实例组。


　　　　合法值：MASTER|CORE|TASK

　　InstanceType

　　　　实例组中实例的配置类别（flavor信息）

　　　　类型：String　　　　合法值：kmr.general|kmr.memory|kmr.storage|kmr.compute|kmr.general.2x|kmr.memory.2x|kmr.storage.2x|kmr.compute.2x　　　　是否必须：否

　　InstanceCount

　　　　实例组中实例个数


　　Status

　　　　实例组状态

　　　　类型：InstanceGroupStatusInstanceGroupStatus　　　　是否必须：否


数据类型

109

　　　　实例组配置信息，可以针对每个实例组单独设置配置项


　　ServiceRoles.Member.N

　　　　实例组角色列表，如"NameNode","ResourceManager","HiveServer"等　　　　类型：String列表


　　DeploymentHints

　　　　实例组部署需求，如"AntiAffinity:Host"，"AntiAffinity:Rack"等　　　　类型：String　　　　是否必须：否

9.InstanceGroupStatus

　　State

　　　　实例组状态


　　　　合法值：PROVISIONING|RUNNING|RESIZING|TERMINATING|TERMINATED|ARRESTING

10.Instance

　　Id

　　　　实例标识


　　PrivateIpAddress

　　　　实例的私有ip地址


　　PublicIpAddress

数据类型

110

　　　　实例的公网ip地址


　　Status

　　　　实例状态

　　　　类型：InstanceStatusInstanceStatus　　　　是否必须：否

11.InstanceStatus

　　State

　　　　实例状态信息


　　　　合法值：PROVISIONING|RUNNING|RESIZING|TERMINATED

12.InstanceGroupConfig

　　InstanceGroupType

　　　　实例组类型，相同的机器类型与相同的服务角色列表组成的一组机器。在"KMR2.0.0"中无TASK类型实例组。


　　　　合法值：MASTER、CORE、TASK

　　InstanceType

　　　　实例组中实例的配置类别（flavor信息）

　　　　类型：String　　　　合法值：kmr.general|kmr.memory|kmr.storage|kmr.compute|kmr.general.2x|kmr.memory.2x|kmr.storage.2x|kmr.compute.2x　　　　是否必须：是

　　InstanceCount

数据类型

111

　　　　实例组中实例个数

　　　　类型：Integer　　　　是否必须：是


　　　　实例组配置信息，可以针对每个实例组单独设置配置项


　　ServiceRoles.Member.N

　　　　实例组角色列表，如"NameNode","ResourceManager","HiveServer"等　　　　类型：String列表


　　DeploymentHints

　　　　实例组部署需求，如"AntiAffinity:Host"，"AntiAffinity:Rack"等　　　　类型：String　　　　是否必须：否

13.Configuration

　　所创建集群的配置信息。

　　Classification

　　　　配置信息类别


　　　　可选值：

数据类型

112

Classification FileName

core-site core-site.xml

hdfs-site hdfs-site.xml

mapred-site mapred-site.xml

yarn-site yarn-site.xml

capacity-scheduler capacity-scheduler.xml

hadoop-env hadoop-env.sh

httpfs-env.sh httpfs-env.sh

mapred-env mapred-env.sh

yarn-env yarn-env.sh

hadoop-log4j log4j.properties

hive-env hive-env.sh

hive-site hive-site.xml

hive-exec-log4j hive-exec-log4j.properties

hive-log4j hive-log4j.properties

spark-env spark-env.sh

spark-defaults spark-defaults.conf

spark-log4j log4j.properties

httpfs-site httpfs-site.xml

　　Properties

　　　　配置信息属性和值的集合

　　　　Type：map<string,string>



　　　　Configuration列表


　　Configuration类型数据示例：

数据类型

113

{

"Configurations":[

{

"Classification":"yarn-env",

"Configurations":[

{

"Classification":"export",

"Properties":{

"YARN_NODEMANAGER_OPTS":"-Xmx2049m"

}

}

]

},

{

"Classification":"mapred-site",

"Properties":{

"mapred.tasktracker.map.tasks.maximum":"5"

}

}

]

}

14.BootstrapAction

　　Name

　　　　引导操作名字　

　　　　类型：string　　　　是否必须：是

　　NodeGroups

　　　　引导操作运行的实例组类型

　　　　类型：string列表

　　　　合法值：MASTER|CORE|TASK　　　　是否必须：否，如果不填默认在所有节点上都运行

　　ScriptBootstrapAction

　　　　引导操作脚本配置

　　　　类型：ScriptBootstrapActionScriptBootstrapAction　　　　是否必须：是

15.ScriptBootstrapAction

数据类型

114

　　Path

　　　　引导操作脚本位置

　　　　类型：string　　　　是否必须：是

　　Args

　　　　引导操作参数

　　　　类型：string列表


16.Distribution

　　Name

　　　　发行版名称

　　　　类型：string　　　　是否必须：否

　　Release

　　　　发行版的版本号信息


　　Vendor

　　　　发行商名称


　　Applications

　　　　发行版支持的应用信息

　　　　类型：Application列表Application　　　　是否必须：否

16.Application

　　Name

数据类型

115

　　　　应用名称


　　Release

　　　　应用版本


　　Required

　　　　应用是否必选

　　　　类型：boolean　　　　是否必须：否

数据类型

116

table of contents -...

Documents