API-Reference

概览

对象 方法
Workflow（工作流） CreateWorkflow, PutWorkflow, GetWorkflow, DeleteWorkflow, ActivateWorkflow, ListWorkflow, GetExecutableWorkflow, ListExecutableWorkflow
Task（任务） ListTask, GetTask, StopTask, DeleteTask, ListJob , GetJob
Tool (工具) CreateTool, PutTool, DeleteTool, ListTool, GetTool, GetToolParameterTemplate, GetToolDetails

服务入口

GeneDock服务入口是访问GeneDock资源的URL，与Project所在的区域（Region）有关，目前GeneDock已经有两个Region，在各Region内的公网服务入口如下：

    北京域：cn-beijing-api.genedock.com

    深圳域：cn-shenzhen-api.genedock.com

当用户访问某个具体的Project时，需要根据Project名称及其所在的Region组合出最终访问地址。具体格式如下：

    <region>:<account-name>:<project-name>

在现阶段，GeneDock还不支持创建多个Project，用户默认只有一个以default的Project。

例如访问账户为default的项目空间default，所在区域为深圳，则对应访问地址如下：

    cn-shenzhen-api.genedock.com/accounts/default/projects/default/

访问密钥

访问密钥是GeneDock为用户使用API来访问GeneDock资源设计的”安全口令”。你可以用它来签名API请求内容以通过服务端的安全验证。该访问秘钥成对（AccessKeyId与AccessKeySecret）生成和使用。由于访问秘钥是GeneDock对API请求进行安全验证的关键因子，请妥善保管你的访问秘钥。如果秘钥对出现泄漏风险，建议及时删除该秘钥对并生成新的替代秘钥对。

公共请求头

GeneDock API是基于HTTP协议的REST风格接口，它支持一组可以在所有API请求中使用的公共请求头（是否必选请仔细阅读相关说明。），其详细定义如下：

Header名称 类型 说明
Accept 字符串 客户端希望服务端返回的类型，支持json。仅对GET请求有效，具体取值以各个接口定义为准。 可选。
Accept-Encoding 字符串 客户端希望服务端返回的压缩算法，例如gzip，具体取值以接口定义为准。 可选。
Authorization 字符串 签名内容，细节参考请求签名部分。必选。
Content-Language 字符串 请求Body所采用的自然语言。可选。
Content-Length 字符串 HTTP请求Body长度。 可选。
Content-MD5 字符串 请求Body经过MD5计算后的字符串，计算结果为大写。可选。
Content-Type 字符串 HTTP请求Body类型。如果没有Body部分，则不需要提供该请求头，具体取值以各个接口定义为准。 可选。
Date 字符串 当前发送时刻的时间，使用GMT标准时间。格式化字符串如下：%a, %d %b %Y %H:%M:%S GMT (如：Mon, 3 Jan 2010 08:33:47 GMT)。 必选。
Host 字符串 HTTP请求的完整HOST名字（不包括http或https这样的协议头），例如cn-shenzhen-api.genedock.com或cn-shenzhen-api.genedock.com:80。 可选。
x-gd-apiversion 字符串 API版本号, 默认为最新版本。 本次版本为1.0。 可选。
x-gd-bodyrawsize 数值 请求的Body原始大小。当无Body时该字段为0，当Body是压缩数据，则为压缩前的原始数据大小。可选。
x-gd-compresstype 字符串 API请求中Body部分使用压缩算法，如果不压缩，可以不提供该请求头。可选。
x-gd-date 字符串 当前发送时刻的时间，格式与Date一直。如果请求中包含改公共请求头，它的值会取代Date标准头的值用于服务器请求验证。无论是否有x-gd-date，HTTP标准Date头都必须提供。可选。
x-gd-signaturemethod 字符串 签名计算方法，以实现为准。 默认值为hmac-sha1-v1。 可选。

说明：

  1. 请求中Date所表示的时间与服务器接收到该请求的时间最大可接受误差为15分钟，如果超过15分钟服务器端会拒绝该请求。如果请求中设置了x-gd-date头部，则该时间误差计算基于x-gd-date头的值。

  2. 如果请求指明压缩算法（在x-gd-compresstype中指定），则需要把原始数据压缩后放到HTTP Body部分，而对应的Content-Length、Content-MD5头部也是按照压缩后的Body部分计算。

  3. 由于某些平台上发送HTTP请求时无法指定Date头（由平台自身的库内部自动指定为发送当前时间），造成无法使用正确的Date值计算请求签名。在这种情况下，请指定x-gd-date头并用该请求头的值参与请求签名计算。GeneDock服务端在接受到API请求后会首先判断是否有x-gd-date头，如果有则用它的值来做签名验证，否则就用HTTP的标准头Date做签名验证。

公共响应头

GeneDock API是基于HTTP协议的REST风格接口。所有的API响应都提供一组公共响应头，其详细定义如下：

Header名称 类型 说明
x-gd-requestid 字符串 服务端产生的标示该请求的唯一ID。主要用于跟踪和调查问题。例如用户希望调查出现问题的API请求，可以提供该ID
Content-Length 数值 HTTP响应内容长度
Content-MD5 字符串 HTTP响应内容的MD5值
Content-Type 字符串 HTTP相应内容类型，例如json
Date 字符串 当前返回时刻的时间，使用GMT标准格式。格式化字符串如下：%a, %d %b %Y %H:%M:%S GMT (如：Mon, 3 Jan 2010 08:33:47 GMT)。

请求签名

为了保证用户数据的安全，GeneDock API的所有HTTP请求都必须经过安全验证。目前，该安全验证基于GeneDock访问密钥，使用对称加密算法完成的。其工作流程如下：

  • 请求端根据API请求内容（包括HTTP Header和Body）生成签名字符串；
  • 请求端使用GeneDock的访问密钥对（AccessKeyID和AccessKeySecret）对第一步生成的签名字符串进行签名，形成该API请求的数字签名；
  • 请求端把API请求内容和数字签名一起发给服务端；
  • 服务端在接到请求后会重复第一、二两步工作并在服务端计算出该请求期望的数字签名；（注：服务端会在后台取得该请求使用的用户访问密钥对）
  • 服务端用期望的数字签名和请求端发送过来的数字签名做对比，如果一致则认为该请求通过安全验证，否则拒绝该请求。
    通过上述安全验证流程，我们可以达到以下目的：
  • 确认是谁在做API请求：发送请求前需要用户指定生成数字签名的密钥对，在服务端可通过该密钥对确定用户身份，进而可做访问权限管理。
  • 确认用户请求在网络传输过程中有没有被篡改：服务端会对接收到的请求内容重新计算数字签名，一旦请求内容在网络上被篡改，则无法通过数字签名比对。

签名API请求

用户可以在HTTP请求中增加Authorization(授权)的Head来包含签名(Signature)信息，表明这个消息已被授权。

Authorization字段计算的方法

"Authorization: GeneDock " + AccessKeyId + ":" + Signature
Signature = base64(hmac-sha1(AccessKeySecret,
      VERB + "\n"
      + Content-MD5 + "\n"
      + Content-Type + "\n"
      + Date + "\n"
      + CanonicalizedGDHeaders
      + CanonicalizedResource))

AccessKeySecret表示签名所需的密钥；

  • VERB表示HTTP请求的方法名称，如PUT、GET等；
  • Content-MD5表示请求内容数据的MD5值，详情参照RFC2616；
  • Content-Type表示请求内容的类型；
  • Date表示此次操作的时间，且必须为HTTP1.1中支持的GMT格式，内容为HTTP的Date请求头。如果存在x-gd-date，则以此头中所标识的时间为准；
  • CanonicalizedGDHeaders表示以”x-gd-“为前缀的HTTP Header的组合；
  • CanonicalizedResource表示用户想要访问的GeneDock服务的资源。

其中，Date和CanonicalizedResource不能为空；如果请求中Date所表示的时间与服务器接收到该请求的时间最大可接受误差为15分钟，如果超过15分钟服务器端会拒绝该请求。

构建CanonicalizedGDHeaders的方法

所有以”x-gd-“为前缀的HTTP Header被称为CanonicalizedGDHeaders。它的构建方法如下：

  • 将所有以”x-gd-“为前缀的HTTP Header请求头的名字转换成小写字母，如”x-gd-Auth-Sign:Test”转换成”x-gd-auth-sign:Test”；
  • 将上一步得到的所有HTTP 请求头按照名字的字典序进行升序排列；
  • 如果有相同名字的请求头，则根据标准RFC2616 4.2章进行合并(两个值之间只用逗号分隔)。例如两个名为”x-gd-auth-sign”的请求头，对应的值分别为”Test”和”Alpha”，则合并后为”x-gd-auth-sign:Test,Alpha”;
  • 删除请求头和内容之间分隔符两端出现的任何空格。如”x-gd-auth-sign: Test,Alpha”转换为”x-gd-auth-sign:Test,Alpha”;
  • 将所有的头和内容用”\n”分隔符分隔拼成最后的CanonicalizedGDHeaders。

构建CanonicalizedRresource的方法

用户发送请求中想访问的GeneDock服务的目标资源被称为CanonicalizedRresource，它的构建方法如下：

  • 将CanonicalizedRresource置为空字符串(“ “);
  • 放入要访问的GeneDock服务资源，如”/datas/dataname”(无dataname则不填)；
  • 如请求包含查询字符串(QUERY_STRING)，则在CanonicalizedRresource字符串尾部添加”?”和查询字符串。

其中QUERY_STRING是URL中请求参数按字典排序后的字符串，其中参数名和值之间用”=”(等号)相隔组成字符串，并对参数名-值对按照字典序升序排序，然后以”&”符号连接构成字符串。其公式化描述如下：

QUERY_STRING = "KEY1=VALUE1" + "&" + "KEY2=VALUE2"

请求签名示例

我们举例来演示整个过程，假设用户用作GeneDock API签名的访问密钥对如下：

AccessKeyId = "oHFcHbORoZCavj7GPtytUg=="
AccessKeySecret = "OldPPab5mqZWU4oHHaIbD9aCthB="

示例：

用户需要发送Get请求列出当前project下所有的task，其HTTP请求如下：

GET /tasks/ HTTP 1.1
Fri, 06 May 2016 09:12:23 GMT
Host: cn-shenzhen-api.genedock.com
x-gd-apiversion: 1.0
x-gd-signaturemethod: hmac-sha1-v1

如上GeneDock API请求生成的签名字符串为

GET\n\n\nFri, 06 May 2016 09:12:23 GMT\nx-gd-apiversion:1.0\nx-gd-signaturemethod:hmac-sha1-v1\n/tasks/?offset=1&size=100&taskid=56efe765c21f960013c0f7cf

由于是GET请求，该请求无任何HTTP Body，所以生成的签名字符串Content-Type与Content-MD5域为空字符串。那么以前面指定用户的AccessKeySecret做签名运算后得到的签名为：

qG656Uepw+U78ODJu7uYWVreSgk=

最后发送经过数字签名的请求内容如下：

GET /tasks/ HTTP 1.1
Fri, 06 May 2016 09:12:23 GMT
Host: cn-shenzhen-api.genedock.com
x-gd-apiversion: 1.0
x-gd-signaturemethod: hmac-sha1-v1
Authorization：GeneDock oHFcHbORoZCavj7GPtytUg==:qG656Uepw+U78ODJu7uYWVreSgk=

通用错误码

当API请求发生错误的时候，服务端会返回错误信息，包括HTTP的Status Code和响应Body的具体错误细节。其中响应Body中的错误细节格式如下：

{
    "error_code": <ErrorCode>,
    "error_message": <ErrorMessage>,
    "error_message_chs": <错误信息>
}
HTTP状态码(status) 错误码(Error Code) 错误消息(Error Message) 描述(Description)
400 MissingAuthorization Authorization field is empty or it does not exist. Authorization字段为空或不存在。
400 IllegalAuthorizationFormat Authorization field value {value} is illegal. 无效的Authorization格式。
400 MissingDate Date field is empty. HTTP标准请求头Date为空或不存在。
400 InvalidDateFormat Date {value} format is invalid. Date字段值格式无效。
400 InvalidAccessKeyIdFormat Invalid AccessKeyId format: {format}. 无效的AccessKeyId格式。
401 UnauthorizedAccessKey The AccessKeyId is unauthorized. 提供的AccessKeyId值未授权。
400 InvalidSignatureMethod Signature method {method} is not supported. 不支持的签名方法。
403 RequestTimeSkewed Date within request has been expired. request time: {time} 请求的发送时间超过当前服务处理时间前后15分钟的范围。
403 SignatureNotMatch Authorization signature is not correct, please verify AccessKeyId or AccessKeySecret. Authorization签名不正确, 请检查AccessKeyId或AccessKeySecret。
403 ContentMD5NotMatch Content-MD5 does not match content md5. 内容计算的MD5值与Content-MD5不一致。
400 InvalidAPIVersion Invalid API version: {version} 无效API版本号。
400 NotImplementedAPIVersion NotImplemented API version: {version} 未实现的API版本号。
404 ProjectNotExists Cannot find project: {project} 无法找到项目。
401 UnauthorizedResource The credential is unauthorized to access the resource. 所访问的资源未授权给当前身份。
403 Forbidden The credential is forbidden to access the resource. 使用当前身份访问资源时被禁用。
500 InternalServerError Internal server error message. 服务器内部错误。
上一页下一页