API概述

美团云 (MOS,Meituan Open Service) 提供 EC2 兼容的API访问接口,以方便用户自动化管理云主机及其他云基础设施。 为了访问 MOS 开放接口,MOS为每个用户分配访问的令牌和密码(ACCESS KEY ID和ACCESS SECRET),每个访问请求都需要携带ACCESS KEY ID 以及 SECRET 对请求数据的数字签名。用户可以在MOS管理界面的 ”API密钥页面” 查询访问 API 的 ACCESS KEY ID 以及 ACCESS KEY SECRET。

 

接口支持GET和POST两种方式。参数以key-value形式通过x-form-url-encoded格式编码提交。例如:
https://mosapi.meituan.com/mcs/v1?
    Action=DescribeTemplates&
    AWSAccessKeyId=4ba303cc17454cc7904e044db2a3c912&
    SignatureVersion=2&
    Timestamp=2013-07-20T15%3A02%3A17.000Z&
    SignatureMethod=HmacSHA256&
    Signature=q90E9%2BNtkVb9rJUPQJy75Ec%2F7j6HRCFfaSp2OhWYwuc%3D​

 

请求参数

 
一般,每个接口请求都包含如下参数
参数名称
可选
说明
示例

Action

必选

API请求的类型名称。支持的Action及相关参数参见下文 “Action列表”

“DescribeInstances”

AWSAccessKeyId

必选

访问API请求的ACCESS KEY ID

“4ba303cc17454cc7904e044db2a3c912”

Timestamp

必选

该请求的时间戳,iso8601格式:”YYYY-MM-DDTHH:MM:SS.MMMZ”

“2013-07-20T02:41:04.000Z”

SignatureVersion

必选

数字签名算法版本,目前支持AWS数字签名2.0版本,该值必须为2

“2”

SignatureMethod

必选

数字签名的Hash算法,可能的值为”HmacSHA256”和”HmacSHA1”, 分别对应SHA256和SHA1算法

“HmacSHA256”

Signature

必选

请求内容的数字签名,具体签名生成算法见下文

“m4XAVozDdWIduO8DkOj7fECeNZsUbX41Bv1atOSqMwA=”

Format

可选

返回内容的编码格式,可选值为xml和json,如果未指定, 则默认为xml。如果返回为xml,则返回Content-Type为 application/xml,如果是json格式,则为application/json

“json”

Region

必选

可指定值:华北1“Beijing”,华东1“EastChina1”

“EastChina1”

 

数字签名生成方法

MOS 开放 API 需要签名,遵循”AWS API 2.0签名规范“。 需要将请求内容按如下方法拼接,并按照指定Hash算法获得base64编码的签名字符串:

全部字母大写的HTTP请求方法(GET或POST),以换行(\n)结束。例如:

POST\n

全部字母为小写的API服务主机名,以换行(\n)结束。如果请求端口号为非默认端口(http非80端口,https非443),则需要加上端口,以冒号和host分隔。例如:

mosapi.meituan.com\n

请求绝对路径,以换行(\n)结束。如果路径为空字符串,则为根路径”/”。例如:

/mcs/v1\n

所有请求参数按照请求参数名称的字典顺序排序,并以x-www-form-urlencoded 编码后,再用 = 和 & 拼接在一起。例如:

AWSAccessKeyId=8b5ad48388a347c185b6b7b0ba9e6225&Action=GetBalance&Format=json&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2016-11-14T03%3A10%3A55.000Z

完整的拼接的签名内容为:

POST
mosapi.meituan.com
/mcs/v1
AWSAccessKeyId=8b5ad48388a347c185b6b7b0ba9e6225&Action=GetBalance&Format=json&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2016-11-14T03%3A10%3A55.000Z

最后,以SECRET为Key对上述字符串以HmacSHA256 算法进行Hash后,进行base64编码后获得签名(注意发送请求时也需要对签名进行 x-www-form-urlencoded 编码),结果为:

xOnd5MauvUn8Kx8225Nh7tSYnuIB0oi5H2Jb00UU788=

签名示例代码(php):


<?php
    $key_id = '您自己的 key_id';
    $key_secret = '您自己的 key_secret';
    $url = 'https://mosapi.meituan.com/mcs/v1';

    function signature($post_array){
        $string_to_sign = "POST\n";
        $string_to_sign .= "mosapi.meituan.com\n";
        $string_to_sign .= "/mcs/v1\n";
        $string_to_sign .= array2xform($post_array);
        global $key_secret;
        $signature = base64_encode(hash_hmac('sha256', $string_to_sign, $key_secret, true));
        return $signature;
    }
    function array2xform($post_array){
        $string='';
        foreach ($post_array as $k => $v) {
            $string .= "&$k=".rawurlencode($v);
        }
        $string = substr($string, 1);
        return $string;
    }
    $ch = curl_init();  
    curl_setopt($ch, CURLOPT_URL, $url);
    $post_array = array(
        'AWSAccessKeyId' => $key_id,
        'Action' => 'GetBalance',
        'Format' => 'json',
        'SignatureMethod' => 'HmacSHA256',
        'SignatureVersion' => 2,
        'Timestamp' => date('Y-m-d\TH:i:s.0000\Z', time())
    );
    $sig = signature($post_array);
    $post_array['Signature'] = signature($post_array);
    $post_string = array2xform($post_array);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $out = curl_exec($ch);
    curl_close($ch);
    echo $out;
?>

 

返回格式

如果API请求成功,服务器返回HTTP 200,body包含返回数据。返回数据根据请求的Format参数进行格式化。 

如果API请求失败,服务器返回HTTP 4xx,body包含错误信息,消息格式示例如下:

Json格式错误响应

{"ErrorResponse":
    {"Error":
        {"message": "Not enough balance",
         "code": 406
        }
    }
}

其中,code 为错误代码,message 为错误消息。code 和返回消息的HTTP错误代码相同。 

获取云主机套餐列表

DescribeInstanceTypes 接口用于列出所有用户可以使用的虚拟机套餐类型,在创建虚拟机,更改虚拟机类型时,需要相关信息。
 

请求 URL

https://mosapi.meituan.com/mcs/v1?
    Action=DescribeInstanceTypes&
    请求参数&
    AUTHDATA

请求参数

参数名
类型
说明
可选值
示例
备注
Limit integer 本次请求返回的数量 可选    
Offset integer 本次请求返回的偏移量 可选    

返回参数

InstanceTypeSet:

 

参数名
类型
说明
示例
备注
InstanceType complextype 虚拟机类型定义    
Total integer 返回符合条件的虚拟机类型总量    
Offset integer 返回虚拟机类型的偏移量    
Limit integer 返回虚拟机类型的数量    


InstanceType:

 

参数名
类型
说明
示例
备注

instanceTypeId

string

虚拟机类型ID

   
internalBandwidth string 该类型虚拟机内网接入带宽,单位为Mbps    
instanceType integer 虚拟机类型名称    
volume integer 该类型虚拟机虚拟存储大小,单位为MB    
memory integer 该类型虚拟机内存大小,单位为MB    

cpu

integer

该类型虚拟机CPU核数,单位为个

   


返回示例

 
{
    "DescribeInstanceTypesResponse": {
        "InstanceTypeSet": {
            "InstanceType": [
                {
                    "instanceTypeId": "72e53bb0-715f-45df-8bb5-e5c3fdb0737c",
                    "internalBandwidth": 1000,
                    "externalBandwidth": 0,
                    "instanceType": "C2_M2",
                    "volume": 0,
                    "memory": 2048,
                    "cpu": 2
                },
                {
                    "instanceTypeId": "70a5a133-25f3-4237-a7a2-e2c1265203fe",
                    "internalBandwidth": 1000,
                    "externalBandwidth": 0,
                    "instanceType": "C1_M1",
                    "volume": 0,
                    "memory": 1024,
                    "cpu": 1
                }
            ]
        }
    }
} 

获取账户余额

GetBalance 接口用于获得用户的当前帐户余额。

请求 URL

https://mosapi.meituan.com/mcs/v1?
    Action=GetBalance&
    请求参数&
    AUTHDATA

请求参数



返回参数

参数名
类型
说明
示例
备注

balance

decimal(10,2)

帐户余额

 

 

timestamp

datetime

最后一次帐户余额发生变化的时间,iso8601格式。 如果该帐户从未发生过交易,则余额为0,无timestamp字段

 

 

返回示例(JSON)

{"GetBalanceResponse":
    {"timestamp": "2016-10-14T03:00:28Z",
     "balance": 16.66
    }
}

获取可用区列表

DescribeAvailabilityZones 接口用于列出当前区域中所有的可用域。
可用域(AvailabilityZone)是一个区域内独立的IDC资源,所有的资源(如虚拟机,IP地址等)都归属于一个特定的可用域。用户可以在创建资源时指定该资源所在的可用域,以分散自己的资源到不同可用域,以便构建高可用的系统架构。
 

请求 URL

https://mosapi.meituan.com/mcs/v1?
    Action=DescribeAvailabilityZones&
    请求参数&
    AUTHDATA

请求参数

参数名
类型
说明
可选值
示例
备注
Limit integer 可选 本次请求返回的最多数量    
Offset integer 可选 本次请求返回的偏移量    

返回参数

参数名
类型
说明
示例
备注

Status

string

可用域状态

 

 

availabilityZoneName

string

可用域名称

 

 

availabilityZoneName_CN

string

可用域中文名称

 

 

availabilityZoneId

string

可用域ID

   

返回示例(JSON)

 {
  "DescribeAvailabilityZonesResponse": {
    "AvailabilityZoneSet": {
      "AvailabilityZone": [
        {
          "Status": "soldout",
          "availabilityZoneName": "jxq",
          "availabilityZoneName_CN": "北京1区",
          "availabilityZoneId": "9a3490ec-6615-4782-b08e-926decc8a6b8"
        },
        {
          "Status": "soldout",
          "availabilityZoneName": "digitalbj",
          "availabilityZoneName_CN": "北京2区",
          "availabilityZoneId": "a4030042-02ab-471e-a04e-6d911cd50ab3"
        },
        {
          "Status": "enable",
          "availabilityZoneName": "yongfeng",
          "availabilityZoneName_CN": "北京3区",
          "availabilityZoneId": "c76a6cd7-dc15-46c6-95a2-3bff38116eff"
        },
        {
          "Status": "enable",
          "availabilityZoneName": "runze",
          "availabilityZoneName_CN": "北京4区",
          "availabilityZoneId": "df2e198b-a8cd-45a5-8a9e-d6314e809031"
        }
      ]
    }
  }
}

获取密钥列表

DescribeKeyPairs 接口用于列出用户所有的密钥(SSH Key)。

请求 URL

https://mosapi.meituan.com/mcs/v1?
    Action=DescribeKeyPairs&
    请求参数&
    AUTHDATA
 

请求参数

参数名
类型
说明
可选值
示例
备注
Limit integer 可选 本次请求返回的最多数量    
Offset integer 可选 本次请求返回的偏移量  


返回参数

参数名
类型
说明
示例
备注
keyId string SSH Key的ID    
keyName string SSH Key的名称    
keyScheme string SSH Key的加密方式    
keyNotes string SSH Key的备注信息    
keyFingerprint string SSH 公钥(public key)的指纹(fingerprint)  


返回示例(JSON)

{"DescribeKeyPairsResponse":
    {"KeyPairSet":
        {"KeyPair": [
            {"keyId": "cb97eb8b-de94-4148-849f-2b931cfce97a",
             "keyName": "testkey",
             "keyScheme": "RSA",
             "keyFingerprint": "0a:43:d9:7b:17:a1:24:26:9a:0e:ce:dc:f4:0a:03:44",
             "keyNotes": "for test"
            },
            {"keyId": "b7bfd341-e6d1-4971-8c45-d3ed6f97a846",
             "keyName": "mackey",
             "keyScheme": "DSA",
             "keyFingerprint": "18:0e:d1:45:82:54:78:be:60:f1:a6:8f:cf:64:88:1e",
             "keyNotes": "for test"
            }
         ]
        }
    }
}

新建密钥

CreateKeyPair 接口用于新建密钥(SSH Key)。
 

请求 URL

https://mosapi.meituan.com/mcs/v1?
    Action=CreateKeyPair&
    请求参数&
    AUTHDATA

请求参数

参数名
类型
说明
可选值
示例
备注
KeyName string SSH Key名称      
KeyScheme string SSH Key加密方式 可选 RSA or DSA  
KeyNotes string SSH Key备注 可选    
 

返回参数

参数名
类型
说明
示例
备注

keyMaterial

string

SSH Key内容

 

 

keyName

string

SSH Key名称

 

 

keyScheme

string SSH Key加密方式    
 

返回示例(JSON)

{
  "CreateKeyPairResponse": {
    "KeyPair": {
      "keyMaterial": "-----BEGIN RSA PRIVATE KEY-----XXXX----END RSA PRIVATE KEY-----",
      "keyName": "mostest",
      "keyScheme": "RSA"
    }
  }
} 

倒入密钥

ImportKeyPair 接口用于导入一个已有的密钥对的公钥。用户自己使用 ssh-keygen 等工具生成密钥对后,将公钥信息导入。支持 RSA 或 DSA 加密的密钥对。
 

请求 URL

https://mosapi.meituan.com/mcs/v1?
    Action=ImportKeyPair&
    请求参数&
    AUTHDATA

请求参数

参数名
类型
说明
可选值
示例
备注
keyName string SSH Key名称 必须    
PublicKeyMaterial string SSH Key的public key 必须    
KeyNotes string SSH Key的备注信息 可选    
 

返回参数

参数名
类型
说明
示例
备注
keyId string SSH Key的ID    
keyScheme string SSH Key加密方式, RSA 或者 DSA    
keyName string SSH Key的名称    
keyFingerprint string SSH 公钥(public key)的指纹(fingerprint)    
KeyNotes string SSH Key的备注信息    
 

返回示例(JSON)

{"ImportKeyPairResponse":
    {"KeyPair":
        {"keyId": "0f4697a4-6439-4ae7-b6fe-be29ace2303c",
         "keyName": "newkey",
         "keyScheme": "RSA",
         "keyFingerprint": "0a:43:d9:7b:17:a1:24:26:9a:0e:ce:dc:f4:0a:03:44",
         "keyNotes": "testkey"
        }
    }
}

删除密钥

DeleteKeyPair 接口用于删除一个SSH Key。

 

请求 URL

https://mosapi.meituan.com/mcs/v1?
    Action=DeleteKeyPair&
    请求参数&
    AUTHDATA
 

请求参数

参数名
类型
说明
可选值
示例
备注
KeyId string SSH Key ID 必选    
 

返回参数

参数名
类型
说明
示例
备注
return bool  是否成功    
 

返回示例(JSON)

{
    "DeleteKeyPairResponse":{
        "return": "True"
    }
}