引擎API v1.20

预计阅读时间：47分钟

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.20/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=（created restarting running paused exited）
  • label=key或label="key=value"容器标签的

状态码：

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

创建一个容器

POST /containers/create

创建一个容器

请求示例：

POST /v1.20/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,
         "MemorySwappiness": 60,
         "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"],
         "GroupAdd": ["newgroup"],
         "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之间的权重值。
    • MemorySwappiness-调整容器的内存交换行为。接受0到100之间的整数。
    • 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-从容器中删除的内核功能列表。
    • GroupAdd-容器进程将作为其运行的其他组的列表
    • 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，gelf，none。 json-file日志记录驱动程序。
    • CgroupParent-cgroups在其下cgroup创建容器的路径。如果该路径不是绝对路径，则认为该路径是相对于cgroupsinit进程的路径而言的。如果Cgroup不存在，则会创建它们。

查询参数：

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

状态码：

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

检查容器

GET /containers/(id or name)/json

返回容器上的底层信息 id

请求示例：

  GET /v1.20/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,
		"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"
	},
	"Mounts": [
		{
			"Source": "/data",
			"Destination": "/data",
			"Mode": "ro,Z",
			"RW": false
		}
	]
}

状态码：

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

列出容器中运行的进程

GET /containers/(id or name)/top

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

请求示例：

GET /v1.20/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.20/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.20/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.20/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.20/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.20/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.20/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.20/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.20/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.20/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.20/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.20/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.20/containers/e90e34656806/pause HTTP/1.1

响应示例：

HTTP/1.1 204 No Content

状态码：

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

取消暂停容器

POST /containers/(id or name)/unpause

取消暂停容器 id

请求示例：

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

响应示例：

HTTP/1.1 204 No Content

状态码：

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

附加到容器

POST /containers/(id or name)/attach

附着在容器上 id

请求示例：

POST /v1.20/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.20/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.20/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.20/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

弃用赞成的archive下方端点。

请求示例：

POST /v1.20/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 –服务器错误

检索有关容器中文件和文件夹的信息

HEAD /containers/(id or name)/archive

请参阅X-Docker-Container-Path-Stat以下部分中的标头说明。

获取容器中文件系统资源的存档

GET /containers/(id or name)/archive

在container的文件系统中获取资源的tar存档id。

查询参数：

  • path-容器文件系统中要归档的资源。必需的。

    如果不是绝对路径，则它是相对于容器的根目录的。路径指定的资源必须存在。要断言该资源应为目录，则路径应以/或 结尾/. （假设的路径分隔符为/）。如果path以结尾，/.则表明仅路径目录的内容应被复制。一个符号链接总是可以解决它的目标。

    注：这是不可能的某些系统文件拷贝如在资源/proc，/sys，/dev，并在容器中的用户创建的坐骑。

请求示例：

GET /v1.20/containers/8cce319429b2/archive?path=/root HTTP/1.1

响应示例：

HTTP/1.1 200 OK
Content-Type: application/x-tar
X-Docker-Container-Path-Stat: eyJuYW1lIjoicm9vdCIsInNpemUiOjQwOTYsIm1vZGUiOjIxNDc0ODQwOTYsIm10aW1lIjoiMjAxNC0wMi0yN1QyMDo1MToyM1oiLCJsaW5rVGFyZ2V0IjoiIn0=


{{ TAR STREAM }}

成功后，X-Docker-Container-Path-Stat将将响应标头设置为base64编码的JSON对象，其中包含有关已归档资源的一些文件系统标头信息。上面的示例值将解码为以下JSON对象（为便于阅读而添加了空格）：

{
    "name": "root",
    "size": 4096,
    "mode": 2147484096,
    "mtime": "2014-02-27T20:51:23Z",
    "linkTarget": ""
}

甲HEAD请求可以如果只有此信息被需要，也可以向此端点制成。

状态码：

  • 200-成功，返回复制资源的存档
  • 400-客户端错误，错误的参数，JSON响应正文中的详细信息，其中之一：
    • 必须指定路径参数（路径不能为空）
    • 不是目录（断言路径是目录，但作为文件存在）
  • 404-客户端错误，找不到资源，其中之一：–不存在这样的容器（容器id不存在）
    • 没有这样的文件或目录（路径不存在）
  • 500-服务器错误

将文件或文件夹的存档提取到容器中的目录

PUT /containers/(id or name)/archive

将要提取的tar存档上传到container的文件系统中的路径 id。

查询参数：

  • path-容器中用于将存档内容提取到的目录的路径。必需的。

    如果不是绝对路径，则它是相对于容器的根目录的。该路径的资源必须存在。

  • noOverwriteDirNonDir-如果为“ 1”，“ true”或“ True”，则解压缩给定内容将导致现有目录被非目录替换，反之亦然。

请求示例：

PUT /v1.20/containers/8cce319429b2/archive?path=/vol1 HTTP/1.1
Content-Type: application/x-tar


{{ TAR STREAM }}

响应示例：

HTTP/1.1 200 OK

状态码：

  • 200 –内容已成功提取
  • 400-客户端错误，错误的参数，JSON响应正文中的详细信息，其中之一：
    • 必须指定路径参数（路径不能为空）
    • 不是目录（路径应该是目录，但作为文件存在）
    • 无法用非目录覆盖现有目录（如果noOverwriteDirNonDir）
    • 无法用目录覆盖现有的非目录（如果noOverwriteDirNonDir）
  • 403-客户端错误，权限被拒绝，卷或容器rootfs被标记为只读。
  • 404-客户端错误，找不到资源，其中之一：–不存在这样的容器（容器id不存在）
    • 没有这样的文件或目录（路径资源不存在）
  • 500 –服务器错误

2.2图片

列出图片

GET /images/json

请求示例：

GET /v1.20/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.20/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.20/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已指定，则将其忽略，并指向一个外部Dockerfile。
  • t –名称和可选标签，以name:tag格式应用到图像。如果省略，tag则使用默认latest值。
  • 远程– Git存储库URI或HTTP / HTTPS上下文URI。如果URI指向单个文本文件，则将文件的内容放入名为的文件中，Dockerfile并从该文件构建图像。如果URI指向压缩包，则守护程序会下载文件