开始 | Get started (Engine)

开始使用Docker API

在安装 Docker 之后，您可以尝试 Docker API。

或者，为您正在使用的语言安装 SDK。官方 SDK 可用于 Python 和 Go，以及一些社区维护的其他语言库。

了解有关安装和使用 Docker SDK的更多信息。

这些例子展示了如何使用 Python，Go或curl直接使用来执行相同的操作。

版本化的 API

这里使用的 Python 和 Go 示例没有指定要使用的 API 版本，因为它们使用长期以来一直是 Docker 一部分的功能。Docker API完全向后兼容。

要查看 Docker 守护进程和客户端支持的API的最高版本，请使用docker version：

$ docker version

Client:
 Version:      17.04.0-ce
 API version:  1.28
 Go version:   go1.7.5
 Git commit:   4845c56
 Built:        Wed Apr  5 06:06:36 2017
 OS/Arch:      darwin/amd64

Server:
 Version:      17.04.0-ce
 API version:  1.28 (minimum version 1.12)
 Go version:   go1.7.5
 Git commit:   4845c56
 Built:        Tue Apr  4 00:37:25 2017
 OS/Arch:      linux/amd64
 Experimental: true

您可以通过以下方式之一指定要使用的 API 版本：

curl直接使用时，请将版本指定为 URL 的第一部分。例如，如果端点是/containers/，您可以使用/v1.27/containers/。

对于 SDK，或强制 Docker CLI 使用特定版本的 API，请将环境变量DOCKER_API_VERSION设置为正确的版本。这适用于 Linux，Windows 或 MacOS 客户端。

DOCKER_API_VERSION = '1.27'

虽然环境变量已设置，但即使 Docker 守护程序支持较新版本，也会使用该版本的API。

对于 SDK，您还可以通过编程方式指定 API 版本作为client对象的参数。请参阅Go的构造函数或Python SDK文档client。API 示例运行容器第一个示例演示如何使用 Docker API 运行容器。在命令行上，您可以使用该docker run命令，但这同样适用于您自己的应用程序。这与docker run alpine echo hello world在命令提示符下键入相同：

Python

Curl

import docker
client = docker.from_env()
print client.containers.run("alpine", ["echo", "hello", "world"])

package main

import (
  "io"
  "os"

  "github.com/docker/docker/client"
  "github.com/docker/docker/api/types"
  "github.com/docker/docker/api/types/container"
  "golang.org/x/net/context"
)

func main() {
  ctx := context.Background()
  cli, err := client.NewEnvClient()
  if err != nil {
    panic(err)
  }

  _, err = cli.ImagePull(ctx, "docker.io/library/alpine", types.ImagePullOptions{})
  if err != nil {
    panic(err)
  }

  resp, err := cli.ContainerCreate(ctx, &container.Config{
    Image: "alpine",
    Cmd:   []string{"echo", "hello world"},
  }, nil, nil, "")
  if err != nil {
    panic(err)
  }

  if err := cli.ContainerStart(ctx, resp.ID, types.ContainerStartOptions{} err != nil {
    panic(err)
  }

  if _, err = cli.ContainerWait(ctx, resp.ID err != nil {
    panic(err)
  }

  out, err := cli.ContainerLogs(ctx, resp.ID, types.ContainerLogsOptions{ShowStdout: true})
  if err != nil {
    panic(err)
  }

  io.Copy(os.Stdout, out)
}

$ curl --unix-socket /var/run/docker.sock -H "Content-Type: application/json" \
  -d '{"Image": "alpine", "Cmd": ["echo", "hello world"]}' \
  -X POST http:/v1.24/containers/create
{"Id":"1c6594faf5","Warnings":null}

$ curl --unix-socket /var/run/docker.sock -X POST http:/v1.24/containers/1c6594faf5/start

$ curl --unix-socket /var/run/docker.sock -X POST http:/v1.24/containers/1c6594faf5/wait
{"StatusCode":0}

$ curl --unix-socket /var/run/docker.sock "http:/v1.24/containers/1c6594faf5/logs?stdout=1"
hello world

在后台运行一个容器

你也可以在后台运行容器，相当于输入docker run -d bfirsh/reticulate-splines：

Python

Curl

import docker
client = docker.from_env()
container = client.containers.run("bfirsh/reticulate-splines", detach=True)
print container.id

package main

import (
  "fmt"
  "io"
  "os"

  "github.com/docker/docker/api/types"
  "github.com/docker/docker/api/types/container"
  "github.com/docker/docker/client"
  "golang.org/x/net/context"
)

func main() {
  ctx := context.Background()
  cli, err := client.NewEnvClient()
  if err != nil {
    panic(err)
  }

  imageName := "bfirsh/reticulate-splines"

  out, err := cli.ImagePull(ctx, imageName, types.ImagePullOptions{})
  if err != nil {
    panic(err)
  }
  io.Copy(os.Stdout, out)

  resp, err := cli.ContainerCreate(ctx, &container.Config{
    Image: imageName,
  }, nil, nil, "")
  if err != nil {
    panic(err)
  }

  if err := cli.ContainerStart(ctx, resp.ID, types.ContainerStartOptions{} err != nil {
    panic(err)
  }

  fmt.Println(resp.ID)
}

$ curl --unix-socket /var/run/docker.sock -H "Content-Type: application/json" \
  -d '{"Image": "bfirsh/reticulate-splines"}' \
  -X POST http:/v1.24/containers/create
{"Id":"1c6594faf5","Warnings":null}

$ curl --unix-socket /var/run/docker.sock -X POST http:/v1.24/containers/1c6594faf5/start

列出并管理容器

您可以使用 API 列出正在运行的容器，就像使用一样docker ps：

Python

Curl

import docker
client = docker.from_env()
for container in client.containers.list():
  print container.id

package main

import (
  "context"
  "fmt"

  "github.com/docker/docker/api/types"
  "github.com/docker/docker/client"
)

func main() {
  cli, err := client.NewEnvClient()
  if err != nil {
    panic(err)
  }

  containers, err := cli.ContainerList(context.Background(), types.ContainerListOptions{})
  if err != nil {
    panic(err)
  }

  for _, container := range containers {
    fmt.Println(container.ID)
  }
}

$ curl --unix-socket /var/run/docker.sock http:/v1.24/containers/json
[{
  "Id":"ae63e8b89a26f01f6b4b2c9a7817c31a1b6196acf560f66586fbc8809ffcd772",
  "Names":["/tender_wing"],
  "Image":"bfirsh/reticulate-splines",
  ...
}]

停止所有运行的容器

现在您知道存在哪些容器，您可以对它们执行操作。例如，要停止所有正在运行的容器：

Python

Curl

import docker
client = docker.from_env()
for container in client.containers.list():
  container.stop()

package main

import (
  "context"

  "github.com/docker/docker/api/types"
  "github.com/docker/docker/client"
)

func main() {
  ctx := context.Background()
  cli, err := client.NewEnvClient()
  if err != nil {
    panic(err)
  }

  containers, err := cli.ContainerList(ctx, types.ContainerListOptions{})
  if err != nil {
    panic(err)
  }

  for _, container := range containers {
    if err := cli.ContainerStop(ctx, container.ID, nil err != nil {
      panic(err)
    }
  }
}

$ curl --unix-socket /var/run/docker.sock http:/v1.24/containers/json
[{
  "Id":"ae63e8b89a26f01f6b4b2c9a7817c31a1b6196acf560f66586fbc8809ffcd772",
  "Names":["/tender_wing"],
  "Image":"bfirsh/reticulate-splines",
  ...
}]

$ curl --unix-socket /var/run/docker.sock \
  -X POST http:/v1.24/containers/ae63e8b89a26/stop

打印特定容器的日志

您也可以对单个容器执行操作。这个例子打印给定 ID 的容器的日志：

Python

Curl

import docker
client = docker.from_env()
container = client.containers.get('f1064a8a4c82')
print container.logs()

package main

import (
  "context"
  "io"
  "os"

  "github.com/docker/docker/api/types"
  "github.com/docker/docker/client"
)

func main() {
  ctx := context.Background()
  cli, err := client.NewEnvClient()
  if err != nil {
    panic(err)
  }

  options := types.ContainerLogsOptions{ShowStdout: true}
  out, err := cli.ContainerLogs(ctx, "f1064a8a4c82", options)
  if err != nil {
    panic(err)
  }

  io.Copy(os.Stdout, out)
}

$ curl --unix-socket /var/run/docker.sock "http:/v1.24/containers/ca5f55cdb/logs?stdout=1"
Reticulating spline 1...
Reticulating spline 2...
Reticulating spline 3...
Reticulating spline 4...
Reticulating spline 5...

列出所有图像

列出引擎上的图像，类似于docker images：

Python

Curl

import docker
client = docker.from_env()
for image in client.images.list():
  print image.id

package main

import (
  "context"
  "fmt"

  "github.com/docker/docker/api/types"
  "github.com/docker/docker/client"
)

func main() {
  cli, err := client.NewEnvClient()
  if err != nil {
    panic(err)
  }

  images, err := cli.ImageList(context.Background(), types.ImageListOptions{})
  if err != nil {
    panic(err)
  }

  for _, image := range images {
    fmt.Println(image.ID)
  }
}

$ curl --unix-socket /var/run/docker.sock http:/v1.24/images/json
[{
  "Id":"sha256:31d9a31e1dd803470c5a151b8919ef1988ac3efd44281ac59d43ad623f275dcd",
  "ParentId":"sha256:ee4603260daafe1a8c2f3b78fd760922918ab2441cbb2853ed5c439e59c52f96",
  ...
}]

Pull image

Pull images，像docker pull：

Python

Curl

import docker
client = docker.from_env()
image = client.images.pull("alpine")
print image.id

package main

import (
  "io"
  "os"

  "github.com/docker/docker/api/types"
  "github.com/docker/docker/client"
  "golang.org/x/net/context"
)

func main() {
  ctx := context.Background()
  cli, err := client.NewEnvClient()
  if err != nil {
    panic(err)
  }

  out, err := cli.ImagePull(ctx, "alpine", types.ImagePullOptions{})
  if err != nil {
    panic(err)
  }

  defer out.Close()

  io.Copy(os.Stdout, out)
}

$ curl --unix-socket /var/run/docker.sock \
  -X POST "http:/v1.24/images/create?fromImage=alpine"
{"status":"Pulling from library/alpine","id":"3.1"}
{"status":"Pulling fs layer","progressDetail":{},"id":"8f13703509f7"}
{"status":"Downloading","progressDetail":{"current":32768,"total":2244027},"progress":"[\u003e                                                  ] 32.77 kB/2.244 MB","id":"8f13703509f7"}
...

Pull images with authentication

docker pull通过身份验证提取图片，例如：

注意：凭证以明文形式发送。Docker 官方注册管理机构使用 HTTPS。私人注册管理机构也应配置为使用 HTTPS。

Python

Curl

Python SDK 从凭证存储文件中检索认证信息并与凭证助手集成。可以覆盖这些凭据，但这不在本入门指南的范围之内。使用后docker login，Python SDK会自动使用这些凭据。

import docker
client = docker.from_env()
image = client.images.pull("alpine")
print image.id

package main

import (
  "io"
  "os"
  "encoding/json"
  "encoding/base64"

  "github.com/docker/docker/api/types"
  "github.com/docker/docker/client"
  "golang.org/x/net/context"
)


func main() {
  ctx := context.Background()
  cli, err := client.NewEnvClient()
  if err != nil {
    panic(err)
  }

  authConfig := types.AuthConfig{
      Username: "username",
      Password: "password",
  }
  encodedJSON, err := json.Marshal(authConfig)
  if err != nil {
      panic(err)
  }
  authStr := base64.URLEncoding.EncodeToString(encodedJSON)

  out, err := cli.ImagePull(ctx, "alpine", types.ImagePullOptions{RegistryAuth:
  authStr})
  if err != nil {
    panic(err)
  }

  defer out.Close()
  io.Copy(os.Stdout, out)
}

这个例子会将证书留在你 shell 的历史记录中，所以认为这是一个天真的实现。凭证以 Base-64 编码的 JSON结构形式传递。

$ JSON=$(echo '{"username": "string", "password": "string", "serveraddress": "string"}' | base64)

$ curl --unix-socket /var/run/docker.sock \
  -H "Content-Type: application/tar" 
  -X POST "http:/v1.24/images/create?fromImage=alpine"
  -H "X-Registry-Auth"
  -d "$JSON"
{"status":"Pulling from library/alpine","id":"3.1"}
{"status":"Pulling fs layer","progressDetail":{},"id":"8f13703509f7"}
{"status":"Downloading","progressDetail":{"current":32768,"total":2244027},"progress":"[\u003e                                                  ] 32.77 kB/2.244 MB","id":"8f13703509f7"}
...

提交容器

提交容器以从其内容创建图像：

Python

Curl

import docker
client = docker.from_env()
container = client.containers.run("alpine", ["touch", "/helloworld"], detach=True)
container.wait()
image = container.commit("helloworld")
print image.id

package main

import (
  "fmt"

  "github.com/docker/docker/api/types"
  "github.com/docker/docker/api/types/container"
  "github.com/docker/docker/client"
  "golang.org/x/net/context"
)

func main() {
  ctx := context.Background()
  cli, err := client.NewEnvClient()
  if err != nil {
    panic(err)
  }

  createResp, err := cli.ContainerCreate(ctx, &container.Config{
    Image: "alpine",
    Cmd:   []string{"touch", "/helloworld"},
  }, nil, nil, "")
  if err != nil {
    panic(err)
  }

  if err := cli.ContainerStart(ctx, createResp.ID, types.ContainerStartOptions{} err != nil {
    panic(err)
  }

  if _, err = cli.ContainerWait(ctx, createResp.ID err != nil {
    panic(err)
  }

  commitResp, err := cli.ContainerCommit(ctx, createResp.ID, types.ContainerCommitOptions{Reference: "helloworld"})
  if err != nil {
    panic(err)
  }

  fmt.Println(commitResp.ID)
}

$ docker run -d alpine touch /helloworld
0888269a9d584f0fa8fc96b3c0d8d57969ceea3a64acf47cd34eebb4744dbc52
$ curl --unix-socket /var/run/docker.sock\
  -X POST "http:/v1.24/commit?container=0888269a9d&repo=helloworld"
{"Id":"sha256:6c86a5cd4b87f2771648ce619e319f3e508394b5bfc2cdbd2d60f59d52acda6c"}

下一步

Python SDK的完整文档

Go SDK的完整文档

HTTPAPI的完整文档

开发，api，sdk，开发人员，休息，卷曲，蟒蛇，去