镜像相关接口

创建自定义镜像

  • 该接口用于创建自定义镜像,创建后的镜像可用于创建实例,每个用户最多可同时创建20个镜像。
  • 支持通过实例创建和通过快照创建两种方式。
  • 当通过实例创建时,只有 Running 或 Stopped 状态的实例才可以执行成功,否则会提示 409 错误。
  • 仅限通过系统盘快照创建自定义镜像。
  • 当通过快照创建时,只有 Available 状态的快照才可以执行成功,否则会提示 409 错误。

请求结构

POST /v{version}/image?clientToken={clientToken} HTTP/1.1
Host: bcc.bj.baidubce.com
Authorization: authorization string

{
    "imageName" : imageName,
    "instanceId" : instanceId,
    "snapshotId" : snapshotId
}

请求头域

除公共头域外,无其它特殊头域。

请求参数

参数名称 类型 是否必需 参数位置 描述
version String URL参数 API版本号
clientToken String Query参数 幂等性Token,是一个长度不超过64位的ASCII字符串,详见幂等性
imageName String Request Body参数 待创建的自定义镜像名称,支持大小写字母、数字、中文以及-_ /.特殊字符,必须以字母开头,长度1-65。
instanceId String Request Body参数 当从实例创建镜像时,此参数是指用于创建镜像的实例ID。可选参数,与 snapshotId 不同时存在,同时存在时只取instanceId
snapshotId String Request Body参数 当从快照创建镜像时,此参数是指用于创建镜像的快照ID。可选参数,与 instanceId 不同时存在,同时存在时只取instanceId

返回头域

除公共头域,无其它特殊头域。

返回参数

参数名称 类型 描述
imageId String 已创建的镜像的ID

错误码

错误码 错误描述 HTTP状态码 中文解释
Image.ImageNameInvalid Image name is invalid. 400 镜像名称格式不正确
Image.ImageIdIsEmpty Image ID cannot be empty 400 镜像ID格式不能为空
Image.ImageQuotaExceedLimit Image number exceeds the limit. 413 镜像数目超限
Image.InstanceStatusForbidden Instance not in running or stopped status. 409 实例状态不是运行中或者已停止,请确认并重试
Image.SnapshotStatusForbidden Snapshot status is not Available, please confirm and retry. 409 快照状态为不可用,请确认并重试
Image.NonSystemSnapshotForbidden Non system snapshot can not used to create image, please confirm and retry. 403 非系统快照无法创建镜像

请求示例

POST /v2/image?clientToken=1849ef6b-f73c-4f5d-b88b-259ca47af849 HTTP/1.1
Host: bcc.bj.baidubce.com
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de

{
    "imageName" : "template_example_001",
    "instanceId":"i-1849ef6b"
}

返回示例

HTTP/1.1 200 OK
x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
Date: Wed, 03 Dec 2014 06:42:19 GMT
Content-Type: application/json;charset=UTF-8
Server: BWS

{
    "imageId" : "m-nky7qeom"
}

查询镜像列表

  • 该接口用于查询用户所有的镜像信息。
  • 查询的镜像信息中包括系统镜像、自定义镜像和服务集成镜像。
  • 支持按 imageType 来过滤查询,此参数非必需,缺省为 All,即查询所有类型的镜像。

请求结构

GET /v{version}/image?marker={marker}&maxKeys={maxKeys}&imageType={imageType} HTTP/1.1
Host: bcc.bj.baidubce.com
Authorization: authorization string
…

请求头域

除公共头域外,无其它特殊头域。

请求参数

参数名称 类型 是否必需 参数位置 描述
version String URL参数 API版本号
marker String Query参数 批量获取列表的查询的起始位置,是一个由系统生成的字符串
maxKeys int Query参数 每页包含的最大数量,最大数量通常不超过1000。缺省值为1000
imageType String Query参数 指定要查询何种类型的镜像,包括All(所有),System(系统镜像/公共镜像),Custom(自定义镜像),Integration(服务集成镜像),Sharing(共享镜像),GpuBccSystem(GPU专用公共镜像),GpuBccCustom(GPU专用自定义镜像),FpgaBccSystem(FPGA专用公共镜像),FpgaBccCustom(FPGA专用自定义镜像),缺省值为All

返回头域

除公共头域,无其它特殊头域

返回参数

参数名称 类型 描述
marker String 标记查询的起始位置
isTruncated boolean true表示后面还有数据,false表示已经是最后一页。
nextMarker String 获取下一页所需要传递的marker值。当isTruncated为false时,该域不出现。
maxKeys int 每页包含的最大数量
images List<ImageModel> 返回的镜像列表

请求示例

GET /v2/image?marker=m-nky7qeom&maxKeys=1 HTTP/1.1
Host: bcc.bj.baidubce.com
ContentType: application/json
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de

返回示例

HTTP/1.1 200 OK
x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
Date: Wed, 03 Dec 2014 06:42:19 GMT
Content-Type: application/json;charset=UTF-8
Server: BWS
{
    "maxKeys":1,
    "marker":"m-nky7qeom",
    "isTruncated":true,
    "nextMarker":"m-I88RTNWG",
    "images":[
        {
            "id": "m-nky7qeom",
            "createTime": "2015-06-17T10:37:02Z",
            "name": "ubuntu-14.04.1-server-amd64-201506171832",
            "type": "System",
            "osType": "linux",
            "osVersion": "14.04.1 LTS",
            "osName": "Ubuntu",
            "osBuild": "2015061700",
            "osArch": "x86_64 (64bit)",
            "status": "Available",
            "desc": null
        }
    ]
}

查询镜像详情

  • 该接口用于根据指定镜像ID查询单个镜像的详细信息。

请求结构

GET /v{version}/image/{imageId} HTTP/1.1
Host: bcc.bj.baidubce.com
Authorization: authorization string

请求头域

除公共头域外,无其它特殊头域。

请求参数

参数名称 类型 是否必需 参数位置 描述
version String URL参数 API版本号
imageId String URL参数 待查询的镜像ID

返回头域

除公共头域,无其它特殊头域。

返回参数

参数名称 类型 描述
image ImageModel 返回的镜像信息

请求示例

GET /v2/image/m-nky7qeom HTTP/1.1
Host: bcc.bj.baidubce.com
ContentType: application/json
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de

返回示例

HTTP/1.1 200 OK
x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
Date: Wed, 03 Dec 2014 06:42:19 GMT
Content-Type: application/json;charset=UTF-8
Server: BWS

{
    "images":{
    "id": "m-nky7qeom",
    "createTime": "2015-06-17T10:37:02Z",
    "name": "ubuntu-14.04.1-server-amd64-201506171832",
    "type": "System",
    "osType": "linux",
    "osVersion": "14.04.1 LTS",
    "osName": "Ubuntu",
    "osBuild": "2015061700",
    "osArch": "x86_64 (64bit)",
    "status": "Available",
    "desc": null
    }
}

删除自定义镜像

  • 该接口用于删除用户自己的指定的自定义镜像,仅限自定义镜像,系统镜像和服务集成镜像不能删除。
  • imageId 所指定的镜像不存在,提示404错误。
  • 镜像删除后无法恢复,不能再用于创建、重置实例。

请求结构

DELETE /v{version}/image/{imageId} HTTP/1.1
Host: bcc.bj.baidubce.com
Authorization: authorization string

请求头域

除公共头域外,无其它特殊头域。

请求参数

参数名称 类型 是否必需 参数位置 描述
version String URL参数 API版本号
imageId String URL参数 待删除的镜像ID

返回头域

除公共头域,无其它特殊头域。

返回参数

无特殊返回参数

错误码

错误码 错误描述 HTTP状态码 中文解释
Image.UnCustomImageCannotBeDeleted Only custom image can be deleted. 403 非自定义镜像不能删除
Image.CreatingImageCannotBeDeleted Cannot delete image when creating. 409 创建中的镜像不能删除
Image.ImageHasBeenSharedToOthers Image has been shared to others. 409 镜像已被共享给其他用户,无法删除

请求示例

DELETE /v2/image/m-nky7qeom HTTP/1.1
Host: bcc.bj.baidubce.com
ContentType: application/json
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de

返回示例

HTTP/1.1 200 OK
x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
Date: Wed, 03 Dec 2014 06:42:19 GMT
Content-Type: application/json;charset=UTF-8
Server: BWS

跨区域复制自定义镜像

描述

  • 该接口用于用户跨区域复制自定义镜像,仅限自定义镜像,系统镜像和服务集成镜像不能复制。
  • imageId 所指定的镜像不存在,提示404错误。
  • 镜像复制成功后,用户可在目的区域使用此镜像创建、重置实例。

请求结构

POST /v{version}/image/{imageId}?{action} HTTP/1.1
Host: bcc.bj.baidubce.com
Authorization: authorization string

{
    "name" : "destImageName",
    "destRegion" : ["bj","gz"]
}

请求头域

除公共头域外,无其它特殊头域。

请求参数

参数名称 类型 是否必需 参数位置 描述
version String URL参数 API版本号
imageId String URL参数 待复制的镜像ID
action String Query参数 对镜像执行的动作,当前取值remoteCopy
name String Request Body参数 复制镜像名
destRegion List Request Body参数 目的regionId,可以传多个

返回头域

除公共头域,无其它特殊头域。

返回参数

无特殊返回参数

错误码

错误码 错误描述 HTTP状态码 中文解释
Image.RegionNotSupportCopy Region not support copy. 409 目的region不支持复制
Image.ImageStorageFormatInvalid Image storage format is invalid. 409 镜像存储格式不支持复制
Image.ImageNotSupportCopy Image not support copy. 409 非自定义镜像不能复制
Image.ImageStatusForbidden Image status is not Available. 409 镜像状态为不可用
Image.LargeImageCopyForbidden Image is larger than 200G. 409 镜像大于200G不支持复制

请求示例

POST /v2/image/m-nky7qeom?remoteCopy HTTP/1.1
Host: bcc.bj.baidubce.com
ContentType: application/json
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de

{
  "name": "test-copy-image",
  "destRegion": ["bj","gz"]
}

返回示例

HTTP/1.1 200 OK
x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
Date: Wed, 03 Dec 2014 06:42:19 GMT
Content-Type: application/json;charset=UTF-8
Server: BWS

取消跨区域复制自定义镜像

描述

  • 该接口用于取消跨区域复制自定义镜像,仅限自定义镜像,系统镜像和服务集成镜像不能共享。
  • imageId是目的区域的镜像id,若指定的镜像不存在,提示404错误。

请求结构

POST /v{version}/image/{imageId}?{action} HTTP/1.1
Host: bcc.bj.baidubce.com
Authorization: authorization string

请求头域

除公共头域外,无其它特殊头域。

请求参数

参数名称 类型 是否必需 参数位置 描述
version String URL参数 API版本号
imageId String URL参数 待取消复制的镜像ID
action String Query参数 对镜像执行的动作,当前取值cancelRemoteCopy

返回头域

除公共头域,无其它特殊头域。

返回参数

无特殊返回参数

错误码

错误码 错误描述 HTTP状态码 中文解释
Image.ImageStatusForbidden Image status is not dest_copying. 409 镜像不是复制中状态,无法取消

请求示例

POST /v2/image/m-nky7qeom?cancelRemoteCopy HTTP/1.1
Host: bcc.bj.baidubce.com
ContentType: application/json
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de

返回示例

HTTP/1.1 200 OK
x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
Date: Wed, 03 Dec 2014 06:42:19 GMT
Content-Type: application/json;charset=UTF-8
Server: BWS

共享自定义镜像

描述

  • 该接口用于共享用户自己的指定的自定义镜像,仅限自定义镜像,系统镜像和服务集成镜像不能共享。
  • imageId 所指定的镜像不存在,提示404错误。
  • 镜像共享后,被共享的用户可以使用此镜像创建、重置实例。
  • 请求参数中的account和accountId均为可选参数,但不能全部为空,当两个参数同时出现时,服务端会自动去重。

请求结构

POST /v{version}/image/{imageId}?{action} HTTP/1.1
Host: bcc.bj.baidubce.com
Authorization: authorization string

{
    "account" : "account",
    "accountId" : "accountId"
}

请求头域

除公共头域外,无其它特殊头域。

请求参数

参数名称 类型 是否必需 参数位置 描述
version String URL参数 API版本号
imageId String URL参数 待共享的镜像ID
action String Query参数 对镜像执行的动作,当前取值share
account String Request Body参数 待共享的用户名
accountId String Request Body参数 待共享的用户ID

返回头域

除公共头域,无其它特殊头域。

返回参数

无特殊返回参数

错误码

错误码 错误描述 HTTP状态码 中文解释
Image.UnCustomImageCannotBeShared Only custom image can be shared. 403 非自定义镜像不能共享
Image.InvalidAccount Account is invalid. 400 无效的用户
Image.AccountListIsEmpty Account list is empty. 400 用户列表为空
Image.ExceedSharedToUserNumQuota Exceed shared to user num quota. 413 超出可共享的用户数量限制
Image.CannotShareToOwner Cannot share to owner. 403 镜像不能共享给所属用户
Image.AccountHasBeenShared Account has been shared. 409 用户已接收到此共享镜像,不能重复共享
Image.ExceedAcceptSharedImageNumQuota Exceed accept shared image num quota 413 超出可接受共享的镜像数量限制

请求示例

POST /v2/image/m-nky7qeom?share HTTP/1.1
Host: bcc.bj.baidubce.com
ContentType: application/json
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de

{
    "account" : "ceshizhanghao",
    "accountId" : "ab1d7802cb9b436bafaf3361fe482ca6"
}

返回示例

HTTP/1.1 200 OK
x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
Date: Wed, 03 Dec 2014 06:42:19 GMT
Content-Type: application/json;charset=UTF-8
Server: BWS

取消共享自定义镜像

描述

  • 该接口用于取消共享用户自己的指定的自定义镜像,仅限自定义镜像,系统镜像和服务集成镜像不能共享。
  • imageId 所指定的镜像不存在,提示404错误。
  • 镜像取消共享后,被取消共享的用户不能再使用此镜像创建、重置实例。
  • 请求参数中的account和accountId均为可选参数,但不能全部为空,当两个参数同时出现时,服务端会自动去重。

请求结构

POST /v{version}/image/{imageId}?{action} HTTP/1.1
Host: bcc.bj.baidubce.com
Authorization: authorization string

{
    "account" : "account",
    "accountId" : "accountId"
}

请求头域

除公共头域外,无其它特殊头域。

请求参数

参数名称 类型 是否必需 参数位置 描述
version String URL参数 API版本号
imageId String URL参数 待取消共享的镜像ID
action String Query参数 对镜像执行的动作,当前取值unshare
account String Request Body参数 待取消共享的用户名
accountId String Request Body参数 待取消共享的用户ID

返回头域

除公共头域,无其它特殊头域。

返回参数

无特殊返回参数

错误码

错误码 错误描述 HTTP状态码 中文解释
Image.UnCustomImageCannotBeShared Only custom image can be shared. 403 非自定义镜像不能共享
Image.InvalidAccount Account is invalid. 400 无效的用户
Image.AccountListIsEmpty Account list is empty. 400 用户列表为空

请求示例

POST /v2/image/m-nky7qeom?unshare HTTP/1.1
Host: bcc.bj.baidubce.com
ContentType: application/json
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de

{
    "accountId" : "ab1d7802cb9b436bafaf3361fe482ca6"
}

返回示例

HTTP/1.1 200 OK
x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
Date: Wed, 03 Dec 2014 06:42:19 GMT
Content-Type: application/json;charset=UTF-8
Server: BWS

查询镜像已共享的用户列表

描述

  • 该接口用于查询镜像已共享的用户列表。
  • imageId 所指定的镜像不存在,提示404错误。

请求结构

GET /v{version}/image/{imageId}/sharedUsers HTTP/1.1
Host: bcc.bj.baidubce.com
Authorization: authorization string

请求头域

除公共头域外,无其它特殊头域。

请求参数

参数名称 类型 是否必需 参数位置 描述
version String URL参数 API版本号
imageId String URL参数 待查询的镜像ID

返回头域

除公共头域,无其它特殊头域。

返回参数

参数名称 类型 描述
users List\<SharedUser> 返回的共享用户列表

错误码

错误码 错误描述 HTTP状态码 中文解释
Image.UnCustomImageCannotBeShared Only custom image can be shared. 403 非自定义镜像不能共享

请求示例

GET /v2/image/m-nky7qeom/sharedUsers HTTP/1.1
Host: bcc.bj.baidubce.com
ContentType: application/json
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de

返回示例

HTTP/1.1 200 OK
x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
Date: Wed, 03 Dec 2014 06:42:19 GMT
Content-Type: application/json;charset=UTF-8
Server: BWS

{
    users:[
        {
            account:'ceshizhanghao',
            accountId : 'ab1d7802cb9b436bafaf3361fe482ca6'
        }
    ]
}

根据实例ID批量查询OS信息

  • 该接口用于根据实例ID批量查询实例的操作系统信息。
  • 该参数非必须,缺省返回结果空。

请求结构

POST /v{version}/image/os HTTP/1.1
Host: bcc.bj.baidubce.com
Authorization: authorization string

{
"instanceIds": ["instanceId"]
}

请求头域

除公共头域外,无其它特殊头域。

请求参数

参数名称 类型 是否必需 参数位置 描述
instanceIds List Request Body参数 实例ID列表

返回头域

除公共头域,无其他特殊头域

返回参数

参数名称 类型 描述
osInfo OsModel 返回的OS列表

请求示例

POST /v2/image/os HTTP/1.1
Host: bcc.bj.baidubce.com
ContentType: application/json
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de
{
    "instanceIds": [
    "i-ZeVPsPzv",
    "i-HmGPcF2D",
    "i-FAlSyeUz"
 ]
}

返回示例

HTTP/1.1 200 OK
x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
Date: Wed, 03 Dec 2014 06:42:19 GMT
Content-Type: application/json;charset=UTF-8
Server: BWS
"osInfo": [
    {
        "instanceId": "i-FAlSyeUz",
        "osArch": "i386 (32bit)",
        "osVersion": "14.04.1 LTS",
        "osName": "Ubuntu",
        "osType": "linux"
    },
    {
        "instanceId": "i-ZeVPsPzv",
        "osArch": "i386 (32bit)",
        "osVersion": "14.04.1 LTS",
        "osName": "Ubuntu",
        "osType": "linux"
    },
    {
        "instanceId": "i-HmGPcF2D",
        "osArch": "i386 (32bit)",
        "osVersion": "14.04.1 LTS",
        "osName": "Ubuntu",
        "osType": "linux"
    }
]