[开源夏令营][四] Docker remote API 之 镜像篇

列出镜像

列出镜像，有两个可选參数，一个是all，一个是filter，all可选值有，0/False/false，1/True/true，默觉得0；filter是一个包括一个过滤对象的json，形式如‘{"dangling":["true"]}'

GET /images/json

我们能够尝试请求一下

curl -s -XGET theegg.me/docker/images/json?all=0 | python -mjson.tool

能够看到例如以下的返回值：

[
    {
        "Created": 1405461399,
        "Id": "88b42ffd1f7cc87c46edf70924b3e24f18da0eb69337deff4db2979d6e1032d8",
        "ParentId": "c69cab00d6ef21152755a3de928625d7a02860ebe918b8fe9d1dd6aba15229b2",
        "RepoTags": [
            "fedora:latest"
        ],
        "Size": 373742581,
        "VirtualSize": 373742581
    },
    {
        "Created": 1403128361,
        "Id": "e54ca5efa2e962582a223ca9810f7f1b62ea9b5c3975d14a5da79d3bf6020f37",
        "ParentId": "6c37f792ddacad573016e6aea7fc9fb377127b4767ce6104c9f869314a12041e",
        "RepoTags": [
            "ubuntu:latest"
        ],
        "Size": 8,
        "VirtualSize": 276100357
    }
]

返回值相应的含义：

Created：创建的时间，这是一个UNIX时间，以1970为起点，单位为秒

Id：是一个SHA256值，是该镜像的标识。

ParentId：是一个SHA256值，是该镜像的父镜像的标识。

RepoTags：是一个字符串数组，是标明在仓库中它的标签。一个镜像可能会带有多个标签。

Size：是镜像的实际的大小，即镜像占硬盘空间的大小。

VirtualSize：是镜像的虚拟大小，或者就是镜像的大小。镜像的实际大小为父镜像的虚拟大小减去该镜像的虚拟大小。

创建镜像

POST /images/create

请求參数：

-   **fromImage** – 镜像的名字
-   **fromSrc** – 镜像的来源，即标准输入
-   **repo** – 仓库
-   **tag** – 标签
-   **registry** – 从哪个registry

演示样例请求：

curl -s -XPOST theegg.me/docker/images/create?fromImage=base

返回：

開始：

{
    "status": "Pulling repository base"
}

过程中：

{
    "status": "Downloading", 
    "progressDetail": {
        "current": 528384, 
        "total": 94863360, 
        "start": 1405907686
    }, 
    "progress": "[>                                                  ] 528.4 kB/94.86 MB 6m30s", 
    "id": "27cf78414709"
}

出错时：(来自官方文档，但实际curl操作的时候是显示504超时，原因还没有查明）

{"error":"Invalid..."}

返回值含义：

status：表示状态，当前操作状态

progressDetail：表示进度细节，里面包括三个值，current当前位置，total总共多少，start从何处開始

progress：表示进度，是一个能直接输出的进度显示条（ascii图）

id：标示符

error：出错信息

插入文件到镜像中

POST /images/(name)/insert
将url指定的文件插入到名字为name的镜像的路径path中
演示样例请求：


不清楚为什么无法请求

检查镜像

GET /images/(name)/json

返回一些指定镜像名的底层信息


演示样例请求：

curl -s -XGET theegg.me/docker/images/base/json | python -mjson.tool

{
    "Architecture": "",
    "Author": "",
    "Comment": "",
    "Config": null,
    "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0",
    "ContainerConfig": {
        "AttachStderr": false,
        "AttachStdin": false,
        "AttachStdout": false,
        "Cmd": [
            "/bin/bash"
        ],
        "CpuShares": 0,
        "Cpuset": "",
        "Domainname": "",
        "Entrypoint": null,
        "Env": null,
        "ExposedPorts": null,
        "Hostname": "",
        "Image": "base",
        "Memory": 0,
        "MemorySwap": 0,
        "NetworkDisabled": false,
        "OnBuild": null,
        "OpenStdin": true,
        "PortSpecs": null,
        "StdinOnce": false,
        "Tty": true,
        "User": "",
        "Volumes": null,
        "WorkingDir": ""
    },
    "Created": "2013-03-23T22:24:18.818426-07:00",
    "DockerVersion": "",
    "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
    "Os": "",
    "Parent": "27cf784147099545",
    "Size": 77
}

返回值解析：
Architecture：架构
Author：作者
Comment：评注
Config：配置
Container：当前使用该镜像的容器
ContainerConfig：容器的配置
Created：创建时间
DockerVersion：Docker的版本号
Id：Id值
Os：操作系统
Parent：父镜像的Id
Size：大小


ContainerConfig中：
AttachStderr：错误输出是否有附着
AttachStdin：标准输入是否有附着
AttachStdout：标准输出是否有附着
Cmd：运行的命令，是一个数组
CpuShares：共享CPU值
Cpuset：所属CPU集合
Domainname：域名
Entrypoint：实体点
Env：环境
ExposedPorts：对外暴露的port
Hostname：主机名
Image：镜像名
Memory：内存占用
MemorySwap：内存交换
NetworkDisabled：是否禁用网络
OnBuild：在构建
OpenStdin：是否打开标准输入
PortSpecs：指定port
StdinOnce：以前使用标准输入
Tty：是否使用TTY
User：用户
Volumes: 使用卷
WorkingDir：工作文件夹


返回状态码：
200：没有错误
404：没有找到指定镜像
500：server错误

获取镜像历史

GET /images/(name)/history

返回镜像name的历史


演示样例请求：

curl -XGET -s theegg.me/docker/images/base/history | python -mjson.tool
[
    {
        "Created": 1364102658,
        "CreatedBy": "/bin/bash",
        "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
        "Size": 77,
        "Tags": [
            "base:latest",
            "base:ubuntu-12.10",
            "base:ubuntu-quantal",
            "base:ubuntu-quantl"
        ]
    },
    {
        "Created": 1364068391,
        "CreatedBy": "",
        "Id": "27cf784147099545",
        "Size": 175306958,
        "Tags": null
    }
]

返回值：
是一个数组，表示一系列镜像




返回状态码：
200：没有错误
404：没有找到指定镜像
500：server错误

上传镜像到registry

POST /images/(name)/push

将名为name的镜像上传到registry
请求參数：
registry：你想要上传到的registry


请求头部：
X-Registry-Auth：包括一个base64编码的AuthConfig对象，即{'username': string, 'password': string, 'email': string, 'serveraddress' : string}


返回状态码：
返回状态码：
200：没有错误
404：没有找到指定镜像
500：server错误

将镜像打上仓库的标签

POST /images/(name)/tag

将名为name的镜像打上仓库的标签

curl -XPOST theegg.me/docker/images/base/tag?repo=a -i

HTTP/1.1 201 Created
Server: nginx
Date: Tue, 29 Jul 2014 02:26:24 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 0
Connection: keep-alive

请求參数：
repo：指定要打的标签的仓库名
force：是否强制，默觉得false


返回状态码：
201：没有错误
400：參数有误
404：没有找到指定的镜像
409：矛盾
500：server错误

删除一个镜像

DELETE /images/(name)

从文件系统上删除名为name的镜像

curl -XDELETE theegg.me/docker/images/base
[
    {
        "Untagged": "base:latest"
    }
]

请求參数：
force：是否强制
noprune：是否啰嗦（待确定）


返回状态码：
200：没有错误
404：没有找到指定镜像
500：server错误

搜索镜像

GET /images/search

在Docker Hub上搜索指定镜像
演示样例请求：

curl -XGET -s theegg.me/docker/images/search?term=sshd | python -mjson.tool

[
    {
        "description": "SSH Daemon created in the ssh daemon documentation example",
        "is_official": false,
        "is_trusted": false,
        "name": "dhrp/sshd",
        "star_count": 5
    },
    {
        "description": "Ubuntu 13.10 with openssh based on the stackbrew/ubuntu:13.10 image.",
        "is_official": false,
        "is_trusted": false,
        "name": "stephens/sshd",
        "star_count": 2
    },...
]

返回的是一个镜像数组，每一个镜像有：
description：描写叙述信息
is_official：是否官方
is_trusted：是否受信任
name：名字
star_count：标星数


返回状态码：
200：没有错误
500：server错误