返回结果

最近更新时间:2019-06-25 18:00:06

返回值结构

如无特别说明, 每次请求的返回值中, 都会包含下面的字段:

名称 类型 描述 必选
code Int 返回结果的错误码,0表示成功,其它值表示失败。具体错误码的含义可以参考 错误码 页面 Yes
message String 请求结果 Yes

例如:
使用公共参数部分的示例请求:

 https://live/v2/index.php?Action=DescribeInstances&SecretId=xxxxxxx&Region=gz
 &Timestamp=1402992826&Nonce=345122&Signature=mysignature&instanceId=101

可能的返回结果如下:

{
    "code":0,
    "message": "success",
    "instanceSet":
   [{
        "instanceId":"qcvm1234",
        "cpu":1,
        "mem":2,
        "disk":20,
        "bandwidth":65535,
        "os":"centos_62_64",
        "lanIp":"10.207.248.186",
        "wanIp":null,
        "status":0
   }]
}

错误码

响应包体内的返回码(code), 反映了腾讯云 API 调用和执行的概要结果.
当返回码不为0时, 表示请求未正常执行, 返回码也称为错误码, 错误描述(message)对该结果进行了细化补充,用户可根据错误码判断 API 的执行情况。
message 在部分终端(例如浏览器),中文会显示成 unicode 编码,需要解码。

腾讯云 API 可能返回的错误码表如下:

错误代码 错误类型 描述
4000 请求参数非法 缺少必要参数,或者参数值格式不正确,具体错误信息请查看错误描述 message 字段。
4100 鉴权失败 签名鉴权失败,请参考文档中鉴权部分。
4200 请求过期 请求已经过期,请参考文档中请求有效期部分。
4300 拒绝访问 帐号被封禁,或者不在接口针对的用户范围内等。
4400 超过配额 请求的次数超过了配额限制,请参考文档请求配额部分。
4500 重放攻击 请求的 Nonce 和 Timestamp 参数用于确保每次请求只会在服务器端被执行一次,所以本次的 Nonce 和上次的不能重复, Timestamp 与腾讯服务器相差不能超过2小时。
4600 协议不支持 协议不支持,请参考文档说明。
5000 资源不存在 资源标识对应的实例不存在,或者实例已经被退还,或者访问了其他用户的资源。
5100 资源操作失败 对资源的操作失败,具体错误信息请查看错误描述 message 字段,稍后重试或者联系客服人员帮忙解决。
5200 资源购买失败 购买资源失败,可能是不支持实例配置,资源不足等等。
5300 资源购买失败 购买资源失败,余额不足。
5400 部分执行成功 批量操作部分执行成功, 详情见方法返回值。
5500 用户资质审核未通过 购买资源失败,用户资质审核未通过。
6000 服务器内部错误 服务器内部出现错误,请稍后重试或者联系客服人员帮忙解决。
6100 版本暂不支持 本版本内不支持此接口或该接口处于维护状态等。注意: 出现这个错误时, 请先确定接口的域名是否正确, 不同的模块, 域名可能不一样。
6200 接口暂时无法访问 当前接口处于停服维护状态,请稍后重试。

异步任务接口返回格式

1. 普通异步任务接口返回格式

一次请求只能操作一个资源的异步任务接口,例如创建负载均衡,重置主机操作系统等。

名称 类型 描述 必选
code Int 返回结果的错误码,0表示成功,其它值表示失败。 Yes
message String 返回结果的错误信息 No
requestId String 任务编号 Yes

2. 批量异步任务接口返回格式

一次请求能操作多个资源的异步任务接口,例如修改密码,启动机器,停止机器等。

名称 类型 描述 必选
code Int 返回结果的错误码,0表示成功,其它值表示失败。 Yes
message String 返回结果的错误信息 No
detail Array 以资源 ID 为 key, 返回对该资源操作的 code,message,requestId Yes

例如:

{
        "code":0,
        "message": "success",
        "detail":
        {
             "qcvm6a456b0d8f01d4b2b1f5073d3fb8ccc0":
            {
             "code":0,
             "message":"",
             "requestId":"1231231231231"
            },
              "qcvm6a456b0d8f01d4b2b1f5073d3fb8ccc0":
            {
              "code":0,
              "message":"",
              "requestId":"1231231231232"
            }
        }
}

注意:

资源全部操作成功,则最外层 code 为0
资源全部操作失败,则最外层 code 会返回5100
资源部分操作失败,则最外层 code 会返回5400
在第3种情况下,终端可以通过 detail 得到失败部分的操作信息。

代码示例

1. SDK代码下载

示例代码 PHP 版
示例代码 Java 版
示例代码 Python 版
示例代码 .NET 版

将示例代码中的 YOUR_SECRET_ID 和 YOUR_SECRET_KEY 替换成实际的 SecretId 和 SecretKey
示例代码仅供参考, 请根据实际情况使用。

2. PHP语言的示例代码

<?php


/***************真实调用时,需要根据不同接口修改下面的参数*********************************/
/***************此处以DescribeInstances为例说明 如何获取指定 instanceId 的云服务器**********/

/*DescribeInstances 接口的 URL地址为 cvm.api.qcloud.com,可从对应的接口说明 “1.接口描述” 章节获取该接口的地址*/
$HttpUrl="cvm.api.qcloud.com";

/*除非有特殊说明,如MultipartUploadVodFile,其它接口都支持GET及POST*/
$HttpMethod="GET"; 

/*是否https协议,大部分接口都必须为https,只有少部分接口除外(如MultipartUploadVodFile)*/
$isHttps =true;

/*需要填写您的密钥,可从  https://console.cloud.tencent.com/capi 获取 SecretId 及 $secretKey*/
$secretKey='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';


/*下面这五个参数为所有接口的 公共参数;对于某些接口没有地域概念,则不用传递Region(如DescribeDeals)*/
$COMMON_PARAMS = array(
        'Nonce'=> rand(),
        'Timestamp'=>time(NULL),
        'Action'=>'DescribeInstances',
        'SecretId'=> 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
        'Region' =>'gz',
);

/*下面这两个参数为 DescribeInstances 接口的私有参数,用于查询特定的云服务器列表*/
$PRIVATE_PARAMS = array(
        'instanceIds.0'=> 'qcvm00001',
        'instanceIds.1'=> 'qcvm00002',
);


/***********************************************************************************/


CreateRequest($HttpUrl,$HttpMethod,$COMMON_PARAMS,$secretKey, $PRIVATE_PARAMS, $isHttps);


function CreateRequest($HttpUrl,$HttpMethod,$COMMON_PARAMS,$secretKey, $PRIVATE_PARAMS, $isHttps)
{
    $FullHttpUrl = $HttpUrl."/v2/index.php";

    /***************对请求参数 按参数名 做字典序升序排列,注意此排序区分大小写*************/
    $ReqParaArray = array_merge($COMMON_PARAMS, $PRIVATE_PARAMS);
    ksort($ReqParaArray);

    /**********************************生成签名原文**********************************
     * 将 请求方法, URI地址,及排序好的请求参数  按照下面格式  拼接在一起, 生成签名原文,此请求中的原文为 
     * GETcvm.api.qcloud.com/v2/index.php?Action=DescribeInstances&Nonce=345122&Region=gz
     * &SecretId=AKIDz8krbsJ5yKBZQ    ·1pn74WFkmLPx3gnPhESA&Timestamp=1408704141
     * &instanceIds.0=qcvm12345&instanceIds.1=qcvm56789
     * ****************************************************************************/
    $SigTxt = $HttpMethod.$FullHttpUrl."?";

    $isFirst = true;
    foreach ($ReqParaArray as $key => $value)
    {
        if (!$isFirst) 
        { 
            $SigTxt = $SigTxt."&";
        }
        $isFirst= false;

        /*拼接签名原文时,如果参数名称中携带_,需要替换成.*/
        if(strpos($key, '_'))
        {
            $key = str_replace('_', '.', $key);
        }

        $SigTxt=$SigTxt.$key."=".$value;
    }

    /*********************根据签名原文字符串 $SigTxt,生成签名 Signature******************/
    $Signature = base64_encode(hash_hmac('sha1', $SigTxt, $secretKey, true));


    /***************拼接请求串,对于请求参数及签名,需要进行urlencode编码********************/
    $Req = "Signature=".urlencode($Signature);
    foreach ($ReqParaArray as $key => $value)
    {
        $Req=$Req."&".$key."=".urlencode($value);
    }

    /*********************************发送请求********************************/
    if($HttpMethod === 'GET')
    {
        if($isHttps === true)
        {
            $Req="https://".$FullHttpUrl."?".$Req;
        }
        else
        {
            $Req="http://".$FullHttpUrl."?".$Req;
        }

        $Rsp = file_get_contents($Req);

    }
    else
    {
        if($isHttps === true)
        {
            $Rsp= SendPost("https://".$FullHttpUrl,$Req,$isHttps);
        }
        else
        {
            $Rsp= SendPost("http://".$FullHttpUrl,$Req,$isHttps);
        }
    }

    var_export(json_decode($Rsp,true));
}

function SendPost($FullHttpUrl,$Req,$isHttps)
{

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $Req);

        curl_setopt($ch, CURLOPT_URL, $FullHttpUrl);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        if ($isHttps === true) {
            curl_setopt($ch, CURLOPT_SSL_VERIFYPEER,  false);
            curl_setopt($ch, CURLOPT_SSL_VERIFYHOST,  false);
        }

        $result = curl_exec($ch);

        return $result;
}