引擎API v1.19

预计阅读时间：42分钟

1.简介

  • 守护程序会监听，unix:///var/run/docker.sock但是您可以将 Docker绑定到另一个主机/端口或Unix套接字。
  • 该API通常是REST。然而，对于一些复杂的命令，如attach 或pull，HTTP连接被劫持到运输stdout， stdin和stderr。
  • 一个Content-Length标题应该是存在于POST请求发送到期望的身体端点。
  • 要锁定特定版本的API，请在URL前面加上要使用的API版本。例如，/v1.18/info。如果URL中未包含任何版本，则使用支持的最大API版本。
  • 如果守护程序不支持URL中指定的API版本，400 Bad Request则会返回HTTP 错误消息。

2.端点

2.1容器

列出容器

GET /containers/json

列出容器

请求示例：

GET /v1.19/containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json

[
     {
             "Id": "8dfafdbc3a40",
             "Names":["/boring_feynman"],
             "Image": "ubuntu:latest",
             "Command": "echo 1",
             "Created": 1367854155,
             "Status": "Exit 0",
             "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}],
             "Labels": {
                     "com.example.vendor": "Acme",
                     "com.example.license": "GPL",
                     "com.example.version": "1.0"
             },
             "SizeRw": 12288,
             "SizeRootFs": 0
     },
     {
             "Id": "9cd87474be90",
             "Names":["/coolName"],
             "Image": "ubuntu:latest",
             "Command": "echo 222222",
             "Created": 1367854155,
             "Status": "Exit 0",
             "Ports": [],
             "Labels": {},
             "SizeRw": 12288,
             "SizeRootFs": 0
     },
     {
             "Id": "3176a2479c92",
             "Names":["/sleepy_dog"],
             "Image": "ubuntu:latest",
             "Command": "echo 3333333333333333",
             "Created": 1367854154,
             "Status": "Exit 0",
             "Ports":[],
             "Labels": {},
             "SizeRw":12288,
             "SizeRootFs":0
     },
     {
             "Id": "4cb07b47f9fb",
             "Names":["/running_cat"],
             "Image": "ubuntu:latest",
             "Command": "echo 444444444444444444444444444444444",
             "Created": 1367854152,
             "Status": "Exit 0",
             "Ports": [],
             "Labels": {},
             "SizeRw": 12288,
             "SizeRootFs": 0
     }
]

查询参数：

  • 全部– 1 / True / true或0 / False / false，显示所有容器。默认情况下仅显示正在运行的容器（即，默认为false）
  • 限制–显示limit最后创建的容器，包括未运行的容器。
  • since –仅显示自ID之后创建的容器，包括未运行的容器。
  • 之前-仅显示在ID之前创建的容器，包括未运行的容器。
  • size – 1 / True / true或0 / False / false，显示容器大小
  • 过滤器-一个JSON编码的滤波器（的值map[string][]string），以处理容器列表中。可用的过滤器：
  • exited=<int>; -出口代码为的集装箱 <int>;
  • status=（restarting running paused exited）
  • label=key或label="key=value"容器标签的

状态码：

  • 200 –没有错误
  • 400 –错误的参数
  • 500 –服务器错误

创建一个容器

POST /containers/create

创建一个容器

请求示例：

POST /v1.19/containers/create HTTP/1.1
Content-Type: application/json
Content-Length: 12345

{
       "Hostname": "",
       "Domainname": "",
       "User": "",
       "AttachStdin": false,
       "AttachStdout": true,
       "AttachStderr": true,
       "Tty": false,
       "OpenStdin": false,
       "StdinOnce": false,
       "Env": [
               "FOO=bar",
               "BAZ=quux"
       ],
       "Cmd": [
               "date"
       ],
       "Entrypoint": null,
       "Image": "ubuntu",
       "Labels": {
               "com.example.vendor": "Acme",
               "com.example.license": "GPL",
               "com.example.version": "1.0"
       },
       "Volumes": {
         "/volumes/data": {}
       },
       "WorkingDir": "",
       "NetworkDisabled": false,
       "MacAddress": "12:34:56:78:9a:bc",
       "ExposedPorts": {
               "22/tcp": {}
       },
       "HostConfig": {
         "Binds": ["/tmp:/tmp"],
         "Links": ["redis3:redis"],
         "LxcConf": {"lxc.utsname":"docker"},
         "Memory": 0,
         "MemorySwap": 0,
         "CpuShares": 512,
         "CpuPeriod": 100000,
         "CpuQuota": 50000,
         "CpusetCpus": "0,1",
         "CpusetMems": "0,1",
         "BlkioWeight": 300,
         "OomKillDisable": false,
         "PidMode": "",
         "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] },
         "PublishAllPorts": false,
         "Privileged": false,
         "ReadonlyRootfs": false,
         "Dns": ["8.8.8.8"],
         "DnsSearch": [""],
         "ExtraHosts": null,
         "VolumesFrom": ["parent", "other:ro"],
         "CapAdd": ["NET_ADMIN"],
         "CapDrop": ["MKNOD"],
         "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 },
         "NetworkMode": "bridge",
         "Devices": [],
         "Ulimits": [{}],
         "LogConfig": { "Type": "json-file", "Config": {} },
         "SecurityOpt": [],
         "CgroupParent": ""
      }
  }

响应示例：

  HTTP/1.1 201 Created
  Content-Type: application/json

  {
       "Id":"e90e34656806",
       "Warnings":[]
  }

JSON参数：

  • 主机名-一个字符串值，其中包含要用于容器的主机名。
  • 域名-一个字符串值，其中包含要用于容器的域名。
  • 用户-一个字符串值，用于指定容器内的用户。
  • AttachStdin-布尔值，附加到stdin。
  • AttachStdout-布尔值，附加到stdout。
  • AttachStderr-布尔值，附加到stderr。
  • Tty-布尔值，将标准流附加到tty，包括stdin是否未关闭。
  • OpenStdin-布尔值，打开stdin，
  • StdinOnce-布尔值，stdin在连接的1个客户端断开连接后关闭。
  • Env-以下形式的环境变量列表["VAR=value", ...]
  • 标签-将标签图添加到容器中。要指定地图：{"key":"value", ... }
  • Cmd-要运行的命令，指定为字符串或字符串数​​组。
  • 入口点-设置用于容器为字符串或字符串数组的入口点。
  • 图像-一个字符串，指定要用于容器的图像名称。
  • 卷-将容器内的安装点路径（字符串）映射到空对象的对象。
  • WorkingDir-一个字符串，用于指定要在其中运行命令的工作目录。
  • NetworkDisabled-布尔值，如果为true，则禁用容器的联网
  • ExposedPorts-以以下形式将端口映射到空对象的对象： "ExposedPorts": { "<port>/<tcp|udp>: {}" }
  • 主机配置
    • 绑定–此容器的绑定安装列表。每个项目都是以下形式之一的字符串：
      • host-src:container-dest将主机路径绑定安装到容器中。两者host-src，并且container-dest必须是 绝对路径。
      • host-src:container-dest:ro使绑定安装在容器内为只读。两者host-src，并且container-dest必须是绝对路径。
    • 链接-容器的链接列表。每个链接条目应采用的形式container_name:alias。
    • LxcConf -LXC特定的配置。这些配置仅在使用lxc执行驱动程序时有效。
    • 内存-内存限制（以字节为单位）。
    • MemorySwap-总内存限制（内存+交换）；设置-1为启用无限交换。您必须将其与一起使用memory，并使交换值大于memory。
    • CpuShares-包含容器的CPU份额的整数值（即相对于其他容器的相对重量）。
    • CpuPeriod -CPU周期的长度（以微秒为单位）。
    • CpuQuota-容器在CPU周期内可以获得的CPU时间的微秒。
    • CpusetCpus-包含cgroups CpusetCpus要使用的字符串值。
    • CpusetMems-允许执行（0-3，0,1）的内存节点（MEM）。仅在NUMA系统上有效。
    • BlkioWeight-块IO权重（相对权重）接受介于10和1000之间的权重值。
    • OomKillDisable-布尔值，是否为容器禁用OOM Killer。
    • PidMode-设置容器的PID（进程）命名空间模式； "container:<name|id>"：加入另一个容器的PID名称空间 "host"：在容器内使用主机的PID名称空间
    • PortBindings-裸露的容器端口及其应映射到的主机端口的映射。{ <port>/<protocol>: [{ "HostPort": "<port>" }] } 请注意，形式为JSON的JSON对象 port指定为字符串而不是整数值。

    • PublishAllPorts-为容器的所有公开端口分配临时主机端口。指定为布尔值。

      容器停止时将取消分配端口，而容器启动时将分配端口。重新启动容器时，分配的端口可能会更改。

      该端口是从临时端口范围中选择的，该范围取决于内核。例如，在Linux上，范围由定义/proc/sys/net/ipv4/ip_local_port_range。

    • 特权-赋予容器对主机的完全访问权限。指定为布尔值。
    • ReadonlyRootfs-将容器的根文件系统挂载为只读。指定为布尔值。
    • Dns-要使用的容器的DNS服务器列表。
    • DnsSearch -DNS搜索域列表
    • ExtraHosts-要添加到容器/etc/hosts文件中的主机名/ IP映射的列表。以表格形式指定["hostname:IP"]。
    • VolumesFrom-要从另一个容器继承的卷的列表。指定形式<container name>[:<ro|rw>]
    • CapAdd-要添加到容器的内核功能列表。
    • Capdrop-从容器中删除的内核功能列表。
    • RestartPolicy –容器退出时要应用的行为。该值是一个对象，其Name属性"always"为始终重新启动或"on-failure"仅在容器退出代码为非零时重新启动。如果on-failure使用，则MaximumRetryCount 控制放弃前重试的次数。默认为不重新启动。（可选）在每次重新启动之前添加一个不断增加的延迟（从100mS开始，是以前的延迟的两倍），以防止服务器泛滥。
    • NetworkMode-设置容器的联网模式。支持的值是：bridge，host，none，和container:<name|id>
    • 设备-要添加到以JSON对象形式指定的容器中的设备列表 { "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}
    • Ulimits-在容器中设置的ulimit列表，指定为 { "Name": <name>, "Soft": <soft limit>, "Hard": <hard limit> }，例如： Ulimits: { "Name": "nofile", "Soft": 1024, "Hard": 2048 }
    • SecurityOpt：字符串值列表，用于自定义MLS系统（例如SELinux）的标签。
    • LogConfig-容器的日志配置，以JSON对象形式指定 { "Type": "<driver_name>", "Config": {"key1": "val1"}}。可用类型：json-file，syslog，journald，none。 syslog可用的选项有：address。
    • CgroupParent-cgroups在其下cgroup创建容器的路径。如果该路径不是绝对路径，则认为该路径是相对于cgroupsinit进程的路径而言的。如果Cgroup不存在，则会创建它们。

查询参数：

  • 名称–将指定的名称分配给容器。必须匹配/?[a-zA-Z0-9_-]+。

状态码：

  • 201 –没有错误
  • 400 –错误的参数
  • 404 –无此类容器
  • 406 –无法连接（容器未运行）
  • 409 –冲突
  • 500 –服务器错误

检查容器

GET /containers/(id or name)/json

返回容器上的底层信息 id

请求示例：

  GET /v1.19/containers/4fa6e0f0c678/json HTTP/1.1

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json

{
	"AppArmorProfile": "",
	"Args": [
		"-c",
		"exit 9"
	],
	"Config": {
		"AttachStderr": true,
		"AttachStdin": false,
		"AttachStdout": true,
		"Cmd": [
			"/bin/sh",
			"-c",
			"exit 9"
		],
		"Domainname": "",
		"Entrypoint": null,
		"Env": [
			"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
		],
		"ExposedPorts": null,
		"Hostname": "ba033ac44011",
		"Image": "ubuntu",
		"Labels": {
			"com.example.vendor": "Acme",
			"com.example.license": "GPL",
			"com.example.version": "1.0"
		},
		"MacAddress": "",
		"NetworkDisabled": false,
		"OnBuild": null,
		"OpenStdin": false,
		"PortSpecs": null,
		"StdinOnce": false,
		"Tty": false,
		"User": "",
		"Volumes": null,
		"WorkingDir": ""
	},
	"Created": "2015-01-06T15:47:31.485331387Z",
	"Driver": "devicemapper",
	"ExecDriver": "native-0.2",
	"ExecIDs": null,
	"HostConfig": {
		"Binds": null,
		"BlkioWeight": 0,
		"CapAdd": null,
		"CapDrop": null,
		"ContainerIDFile": "",
		"CpusetCpus": "",
		"CpusetMems": "",
		"CpuShares": 0,
		"CpuPeriod": 100000,
		"Devices": [],
		"Dns": null,
		"DnsSearch": null,
		"ExtraHosts": null,
		"IpcMode": "",
		"Links": null,
		"LxcConf": [],
		"Memory": 0,
		"MemorySwap": 0,
		"OomKillDisable": false,
		"NetworkMode": "bridge",
		"PidMode": "",
		"PortBindings": {},
		"Privileged": false,
		"ReadonlyRootfs": false,
		"PublishAllPorts": false,
		"RestartPolicy": {
			"MaximumRetryCount": 2,
			"Name": "on-failure"
		},
		"LogConfig": {
			"Config": null,
			"Type": "json-file"
		},
		"SecurityOpt": null,
		"VolumesFrom": null,
		"Ulimits": [{}]
	},
	"HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname",
	"HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts",
	"LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
	"Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39",
	"Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2",
	"MountLabel": "",
	"Name": "/boring_euclid",
	"NetworkSettings": {
		"Bridge": "",
		"Gateway": "",
		"IPAddress": "",
		"IPPrefixLen": 0,
		"MacAddress": "",
		"PortMapping": null,
		"Ports": null
	},
	"Path": "/bin/sh",
	"ProcessLabel": "",
	"ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf",
	"RestartCount": 1,
	"State": {
		"Error": "",
		"ExitCode": 9,
		"FinishedAt": "2015-01-06T15:47:32.080254511Z",
		"OOMKilled": false,
		"Paused": false,
		"Pid": 0,
		"Restarting": false,
		"Running": true,
		"StartedAt": "2015-01-06T15:47:32.072697474Z"
	},
	"Volumes": {},
	"VolumesRW": {}
}

状态码：

  • 200 –没有错误
  • 404 –无此类容器
  • 500 –服务器错误

列出容器中运行的进程

GET /containers/(id or name)/top

列出在容器内运行的进程id。在Unix系统上，这是通过运行ps命令来完成的。Windows不支持此端点。

请求示例：

GET /v1.19/containers/4fa6e0f0c678/top HTTP/1.1

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json

{
   "Titles" : [
     "UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD"
   ],
   "Processes" : [
     [
       "root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash"
     ],
     [
       "root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10"
     ]
   ]
}

请求示例：

GET /v1.19/containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Titles" : [
    "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND"
  ]
  "Processes" : [
    [
      "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash"
    ],
    [
      "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10"
    ]
  ],
}

查询参数：

  • ps_args –ps要使用的参数（例如aux），默认为-ef

状态码：

  • 200 –没有错误
  • 404 –无此类容器
  • 500 –服务器错误

获取容器日志

GET /containers/(id or name)/logs

从容器获取stdout并stderr记录日志id

注意：此端点仅适用于带有json-file或journald日志记录驱动程序的容器。

请求示例：

 GET /v1.19/containers/4fa6e0f0c678/logs?stderr=1&stdout=1&timestamps=1&follow=1&tail=10&since=1428990821 HTTP/1.1

响应示例：

 HTTP/1.1 101 UPGRADED
 Content-Type: application/vnd.docker.raw-stream
 Connection: Upgrade
 Upgrade: tcp

 
 {{ STREAM }}

查询参数：

  • 跟进– 1 / True / true或0 / False / false，返回流。默认值false。
  • 标准输出– 1 / True / true或0 / False / false，显示stdout日志。默认值false。
  • stderr – 1 / True / true或0 / False / false，显示stderr日志。默认值false。
  • 从– UNIX时间戳（整数）开始，用于过滤日志。指定时间戳记只会输出自该时间戳记以来的日志条目。默认值：0（未过滤）
  • 时间戳– 1 / True / true或0 / False / false，为每个日志行打印时间戳。默认值false。
  • tail –在日志末尾输出指定的行数：all或<number>。全部默认。

状态码：

  • 101 –没有错误，提示代理有关劫持
  • 200 –没有错误，没有找到升级头
  • 404 –无此类容器
  • 500 –服务器错误

检查容器文件系统上的更改

GET /containers/(id or name)/changes

检查容器id文件系统上的更改

请求示例：

GET /v1.19/containers/4fa6e0f0c678/changes HTTP/1.1

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json

[
     {
             "Path": "/dev",
             "Kind": 0
     },
     {
             "Path": "/dev/kmsg",
             "Kind": 1
     },
     {
             "Path": "/test",
             "Kind": 1
     }
]

值Kind：

  • 0： 调整
  • 1： 添加
  • 2： 删除

状态码：

  • 200 –没有错误
  • 404 –无此类容器
  • 500 –服务器错误

导出容器

GET /containers/(id or name)/export

导出容器中的内容 id

请求示例：

GET /v1.19/containers/4fa6e0f0c678/export HTTP/1.1

响应示例：

HTTP/1.1 200 OK
Content-Type: application/octet-stream


{{ TAR STREAM }}

状态码：

  • 200 –没有错误
  • 404 –无此类容器
  • 500 –服务器错误

根据资源使用情况获取容器统计信息

GET /containers/(id or name)/stats

该端点返回容器资源使用情况统计信息的实时流。

请求示例：

GET /v1.19/containers/redis1/stats HTTP/1.1

响应示例：

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
     "read" : "2015-01-08T22:57:31.547920715Z",
     "network" : {
        "rx_dropped" : 0,
        "rx_bytes" : 648,
        "rx_errors" : 0,
        "tx_packets" : 8,
        "tx_dropped" : 0,
        "rx_packets" : 8,
        "tx_errors" : 0,
        "tx_bytes" : 648
     },
     "memory_stats" : {
        "stats" : {
           "total_pgmajfault" : 0,
           "cache" : 0,
           "mapped_file" : 0,
           "total_inactive_file" : 0,
           "pgpgout" : 414,
           "rss" : 6537216,
           "total_mapped_file" : 0,
           "writeback" : 0,
           "unevictable" : 0,
           "pgpgin" : 477,
           "total_unevictable" : 0,
           "pgmajfault" : 0,
           "total_rss" : 6537216,
           "total_rss_huge" : 6291456,
           "total_writeback" : 0,
           "total_inactive_anon" : 0,
           "rss_huge" : 6291456,
           "hierarchical_memory_limit" : 67108864,
           "total_pgfault" : 964,
           "total_active_file" : 0,
           "active_anon" : 6537216,
           "total_active_anon" : 6537216,
           "total_pgpgout" : 414,
           "total_cache" : 0,
           "inactive_anon" : 0,
           "active_file" : 0,
           "pgfault" : 964,
           "inactive_file" : 0,
           "total_pgpgin" : 477
        },
        "max_usage" : 6651904,
        "usage" : 6537216,
        "failcnt" : 0,
        "limit" : 67108864
     },
     "blkio_stats" : {},
     "cpu_stats" : {
        "cpu_usage" : {
           "percpu_usage" : [
              8646879,
              24472255,
              36438778,
              30657443
           ],
           "usage_in_usermode" : 50000000,
           "total_usage" : 100215355,
           "usage_in_kernelmode" : 30000000
        },
        "system_cpu_usage" : 739306590000000,
        "throttling_data" : {"periods":0,"throttled_periods":0,"throttled_time":0}
     },
     "precpu_stats" : {
        "cpu_usage" : {
           "percpu_usage" : [
              8646879,
              24350896,
              36438778,
              30657443
           ],
           "usage_in_usermode" : 50000000,
           "total_usage" : 100093996,
           "usage_in_kernelmode" : 30000000
        },
        "system_cpu_usage" : 9492140000000,
        "throttling_data" : {"periods":0,"throttled_periods":0,"throttled_time":0}
     }
  }

的precpu_stats是的CPU统计先前读取，其被用于计算的CPU使用率百分比。它不是该cpu_stats字段的确切副本。

查询参数：

  • 流– 1 / True / true或0 / False / false，提取一次统计信息然后断开连接。默认值true。

状态码：

  • 200 –没有错误
  • 404 –无此类容器
  • 500 –服务器错误

调整容器的TTY大小

POST /containers/(id or name)/resize?h=<height>&w=<width>

使用调整容器的TTY大小 id。您必须重新启动容器才能使调整大小生效。

请求示例：

  POST /v1.19/containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1

响应示例：

  HTTP/1.1 200 OK
  Content-Length: 0
  Content-Type: text/plain; charset=utf-8

查询参数：

  • h –tty会话高度
  • w –宽度

状态码：

  • 200 –没有错误
  • 404 –没有这样的容器
  • 500 –无法调整容器大小

启动一个容器

POST /containers/(id or name)/start

启动容器 id

注意：为了向后兼容，此端点接受一个HostConfigJSON编码的请求正文。有关详细信息，请参见创建容器。

请求示例：

POST /v1.19/containers/e90e34656806/start HTTP/1.1

响应示例：

HTTP/1.1 204 No Content

状态码：

  • 204 –没有错误
  • 304 –容器已经开始
  • 404 –无此类容器
  • 500 –服务器错误

停止容器

POST /containers/(id or name)/stop

停止容器 id

请求示例：

POST /v1.19/containers/e90e34656806/stop?t=5 HTTP/1.1

响应示例：

HTTP/1.1 204 No Content

查询参数：

  • t –杀死容器之前要等待的秒数

状态码：

  • 204 –没有错误
  • 304 –容器已停止
  • 404 –无此类容器
  • 500 –服务器错误

重新启动容器

POST /containers/(id or name)/restart

重新启动容器 id

请求示例：

POST /v1.19/containers/e90e34656806/restart?t=5 HTTP/1.1

响应示例：

HTTP/1.1 204 No Content

查询参数：

  • t –杀死容器之前要等待的秒数

状态码：

  • 204 –没有错误
  • 404 –无此类容器
  • 500 –服务器错误

杀死一个容器

POST /containers/(id or name)/kill

杀死容器 id

请求示例：

POST /v1.19/containers/e90e34656806/kill HTTP/1.1

响应示例：

HTTP/1.1 204 No Content

查询参数：

  • 信号-信号发送到容器：整数或字符串等SIGINT。如果未设置，SIGKILL则假定为该调用并等待容器退出。

状态码：

  • 204 –没有错误
  • 404 –无此类容器
  • 500 –服务器错误

重命名容器

POST /containers/(id or name)/rename

将容器重命名id为new_name

请求示例：

POST /v1.19/containers/e90e34656806/rename?name=new_name HTTP/1.1

响应示例：

HTTP/1.1 204 No Content

查询参数：

  • 名称-容器的新名称

状态码：

  • 204 –没有错误
  • 404 –无此类容器
  • 409-冲突名称已分配
  • 500 –服务器错误

暂停容器

POST /containers/(id or name)/pause

暂停容器 id

请求示例：

POST /v1.19/containers/e90e34656806/pause HTTP/1.1

响应示例：

HTTP/1.1 204 No Content

状态码：

  • 204 –没有错误
  • 404 –无此类容器
  • 500 –服务器错误

取消暂停容器

POST /containers/(id or name)/unpause

取消暂停容器 id

请求示例：

POST /v1.19/containers/e90e34656806/unpause HTTP/1.1

响应示例：

HTTP/1.1 204 No Content

状态码：

  • 204 –没有错误
  • 404 –无此类容器
  • 500 –服务器错误

附加到容器

POST /containers/(id or name)/attach

附着在容器上 id

请求示例：

POST /v1.19/containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1

响应示例：

HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp


{{ STREAM }}

查询参数：

  • logs – 1 / True / true或0 / False / false，返回日志。默认值false。
  • 流– 1 / True / true或0 / False / false，返回流。默认值false。
  • stdin – 1 / True / true或0 / False / false，如果stream=true附加到stdin。默认值false。
  • stdout – 1 / True / true或0 / False / false，如果logs=true返回 stdout日志，则stream=true附加到stdout。默认值false。
  • stderr – 1 / True / true或0 / False / false，如果logs=true返回 stderr日志，则stream=true附加到stderr。默认值false。

状态码：

  • 101 –没有错误，提示代理有关劫持
  • 200 –没有错误，没有找到升级头
  • 400 –错误的参数
  • 404 –无此类容器
  • 500 –服务器错误

流详细信息：

在中启用使用TTY设置时 POST /containers/create ，流是来自进程PTY和客户端的的原始数据stdin。禁用TTY时，将对流进行多路复用以分隔 stdout和stderr。

格式为标题和有效负载（框架）。

标题

标头包含流写入的信息（stdout或 stderr）。它还包含在最后四个字节（uint32）中编码的关联帧的大小。

它在前八个字节上进行编码，如下所示：

header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}

STREAM_TYPE 可：

  • 0 ：（stdin写在上stdout）
  • 1： stdout
  • 2： stderr

SIZE1, SIZE2, SIZE3, SIZE4是uint32编码为big endian的大小的四个字节。

有效载荷

有效负载是原始流。

执行

实现Attach协议的最简单方法如下：

1.  Read eight bytes.
2.  Choose `stdout` or `stderr` depending on the first byte.
3.  Extract the frame size from the last four bytes.
4.  Read the extracted size and output it on the correct output.
5.  Goto 1.

附加到容器（网络套接字）

GET /containers/(id or name)/attach/ws

id通过websocket附加到容器

根据RFC 6455实现websocket协议握手

范例要求

GET /v1.19/containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1

回应范例

{{ STREAM }}

查询参数：

  • logs – 1 / True / true或0 / False / false，返回日志。默认值false。
  • 流– 1 / True / true或0 / False / false，返回流。默认值false。
  • stdin – 1 / True / true或0 / False / false，如果stream=true附加到stdin。默认值false。
  • stdout – 1 / True / true或0 / False / false，如果logs=true返回 stdout日志，则stream=true附加到stdout。默认值false。
  • stderr – 1 / True / true或0 / False / false，如果logs=true返回 stderr日志，则stream=true附加到stderr。默认值false。

状态码：

  • 200 –没有错误
  • 400 –错误的参数
  • 404 –无此类容器
  • 500 –服务器错误

等待一个容器

POST /containers/(id or name)/wait

阻塞直到容器id停止，然后返回退出代码

请求示例：

POST /v1.19/containers/16253994b7c4/wait HTTP/1.1

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json

{"StatusCode": 0}

状态码：

  • 200 –没有错误
  • 404 –无此类容器
  • 500 –服务器错误

取出容器

DELETE /containers/(id or name)

id从文件系统中删除容器

请求示例：

DELETE /v1.19/containers/16253994b7c4?v=1 HTTP/1.1

响应示例：

HTTP/1.1 204 No Content

查询参数：

  • v – 1 /真/真或0 /假/假，删除与容器关联的卷。默认值false。
  • 强制-1 /真/真或0 /假/假，杀死然后取出容器。默认值false。
  • link -1 / True / true或0 / False / false，删除与容器关联的指定链接。默认值false。

状态码：

  • 204 –没有错误
  • 400 –错误的参数
  • 404 –无此类容器
  • 409 –冲突
  • 500 –服务器错误

从容器复制文件或文件夹

POST /containers/(id or name)/copy

复制容器的文件或文件夹 id

请求示例：

POST /v1.19/containers/4fa6e0f0c678/copy HTTP/1.1
Content-Type: application/json
Content-Length: 12345

{
     "Resource": "test.txt"
}

响应示例：

HTTP/1.1 200 OK
Content-Type: application/x-tar


{{ TAR STREAM }}

状态码：

  • 200 –没有错误
  • 404 –无此类容器
  • 500 –服务器错误

2.2图片

列出图片

GET /images/json

请求示例：

GET /v1.19/images/json?all=0 HTTP/1.1

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
     "RepoTags": [
       "ubuntu:12.04",
       "ubuntu:precise",
       "ubuntu:latest"
     ],
     "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
     "Created": 1365714795,
     "Size": 131506275,
     "VirtualSize": 131506275,
     "Labels": {}
  },
  {
     "RepoTags": [
       "ubuntu:12.10",
       "ubuntu:quantal"
     ],
     "ParentId": "27cf784147099545",
     "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
     "Created": 1364102658,
     "Size": 24653,
     "VirtualSize": 180116135,
     "Labels": {
        "com.example.version": "v1"
     }
  }
]

带有摘要信息的示例请求：

GET /v1.19/images/json?digests=1 HTTP/1.1

带有示例摘要信息的示例响应：

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "Created": 1420064636,
    "Id": "4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125",
    "ParentId": "ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2",
    "RepoDigests": [
      "localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf"
    ],
    "RepoTags": [
      "localhost:5000/test/busybox:latest",
      "playdate:latest"
    ],
    "Size": 0,
    "VirtualSize": 2429728,
    "Labels": {}
  }
]

该响应显示了Id与两个存储库（RepoTags）相关联的单个图像localhost:5000/test/busybox：:和playdate。调用者可以使用任何一个RepoTags值localhost:5000/test/busybox:latest或 playdate:latest引用图像。

您也可以使用RepoDigests值来引用图像。在此响应中，数组只有一个引用，即对localhost:5000/test/busybox存储库的引用 。该playdate存储库没有摘要。您可以使用以下值引用此摘要： localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d...

有关命令行上摘要和标记引用的示例，请参见docker run和docker build命令。

查询参数：

  • 全部-1 / True / true或0 / False / false，默认为false
  • 过滤器–过滤器的JSON编码值（要在图片列表上处理的map [string] [] string）。可用的过滤器：
  • dangling=true
  • label=key或label="key=value"图片标签的
  • 过滤器-仅返回具有指定名称的图像

从Dockerfile构建映像

POST /build

从Dockerfile构建映像

请求示例：

POST /v1.19/build HTTP/1.1
Content-Type: application/x-tar


{{ TAR STREAM }}

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json

{"stream": "Step 1/5..."}
{"stream": "..."}
{"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}}

输入流必须是tar与下列算法之一压缩存档：identity（无压缩）， ，gzip，。bzip2xz

归档文件必须包含一个构建说明文件，通常Dockerfile在归档文件的根目录中调用 。该dockerfile参数可用于指定其他构建指令文件。为此，其值必须是要使用的替代构建说明文件的路径。

归档文件可以包含任意数量的其他文件，这些文件可以在构建上下文中访问（请参阅ADD build命令）。

Docker守护程序Dockerfile在开始构建之前对进行了初步验证，如果语法不正确，则返回错误。此后，每条指令将被逐一运行，直到输出新映像的ID。

如果客户端通过退出或终止连接来断开连接，则构建将被取消。

查询参数：

  • dockerfile-构建上下文中Dockerfile的路径。如果remote已指定，则将其忽略，并指向单个文件名。
  • t –名称和可选标签，以name:tag格式应用到图像。如果省略，tag则使用默认latest值。
  • 远程– Git存储库URI或HTTP / HTTPS URI构建源。如果URI指定文件名，则文件的内容将放入名为的文件中Dockerfile。
  • q –禁止详细的生成输出。
  • nocache –构建映像时不要使用缓存。
  • 拉-试图把图像即使旧的图像本地存在。
  • rm-成功构建后删除中间容器（默认行为）。
  • forcerm-务必卸下中间容器（包括rm）。
  • 内存-设置构建的内存限制。
  • memswap-总内存（内存+交换），-1以启用无限交换。
  • cpushares -CPU份额（相对权重）。
  • cpusetcpus-允许执行的CPU（例如0-3，0,1）。
  • cpuperiod -CPU周期的长度（以微秒为单位）。
  • cpuquota-容器在CPU周期内可以获得的CPU时间的微秒。

请求标头：

  • 内容类型–设置为"application/x-tar"。
  • X-Registry-Config – base64编码的ConfigFile对象

状态码：

  • 200 –没有错误
  • 500 –服务器错误

建立影像

POST /images/create

通过从注册表中提取图像或将其导入来创建图像

请求示例：

POST /v1.19/images/create?fromImage=busybox&tag=latest HTTP/1.1

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "Pulling..."}
{"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}}
{"error": "Invalid..."}
...

使用此终结点从注册表中提取图像时， X-Registry-Auth标头可用于包含base64编码的AuthConfig对象。

查询参数：

  • fromImage –要拉取的图像的名称。
  • fromSrc –要导入的源。该值可以是可以从中检索图像或-从请求正文读取图像的URL 。
  • repo –存储库名称。
  • 标签–标签。如果在拉动图像时为空，则将拉动给定图像的所有标签。

请求标头：

  • X-Registry-Auth – base64编码的AuthConfig对象

状态码：

  • 200 –没有错误
  • 404-存储库不存在或没有读取权限
  • 500 –服务器错误

检查图像

GET /images/(name)/json

返回图像上的底层信息 name

请求示例：

GET /v1.19/images/ubuntu/json HTTP/1.1

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json

{
   "Created": "2013-03-23T22:24:18.818426-07:00",
   "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0",
   "ContainerConfig": {
      "Hostname": "",
      "User": "",
      "AttachStdin": false,
      "AttachStdout": false,
      "AttachStderr": false,
      "Tty": true,
      "OpenStdin": true,
      "StdinOnce": false,
      "Env": null,
      "Cmd": ["/bin/bash"],
      "Dns": null,
      "Image": "ubuntu",
      "Labels": {
         "com.example.vendor": "Acme",
         "com.example.license": "GPL",
         "com.example.version": "1.0"
      },
      "Volumes": null,
      "VolumesFrom": "",
      "WorkingDir": ""
   },
   "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
   "Parent": "27cf784147099545",
   "Size": 6824592
}

状态码：

  • 200 –没有错误
  • 404 –无此图片
  • 500 –服务器错误

获取图像的历史记录

GET /images/(name)/history

返回图像的历史记录 name

请求示例：

GET /v1.19/images/ubuntu/history HTTP/1.1

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
        "Created": 1398108230,
        "CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
        "Tags": [
            "ubuntu:lucid",
            "ubuntu:10.04"
        ],
        "Size": 182964289,
        "Comment": ""
    },
    {
        "Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
        "Created": 1398108222,
        "CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
        "Tags": null,
        "Size": 0,
        "Comment": ""
    },
    {
        "Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
        "Created": 1371157430,
        "CreatedBy": "",
        "Tags": [
            "scratch12:latest",
            "scratch:latest"
        ],
        "Size": 0,
        "Comment": "Imported from -"
    }
]

状态码：

  • 200 –没有错误
  • 404 –无此图片
  • 500 –服务器错误

将图像推送到注册表

POST /images/(name)/push

将映像推送到name注册表

请求示例：

POST /v1.19/images/test/push HTTP/1.1

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "Pushing..."}
{"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}}
{"error": "Invalid..."}
...

如果您希望将映像推送到私有注册表，则该映像必须已经在引用该注册表hostname和的存储库中具有标签port。这个仓库