Docker Engine API を用いた開発

読む時間の目安: 3 分

Docker では Docker デーモンとやりとりを行う API（Docker Engine API と呼ぶ）を提供しています。 これに合わせて Go 言語向け SDK、Python 向け SDK も提供します。 SDK を利用すれば Docker アプリの構築やスケール変更を、よりすばやく簡単に実現できます。 Go 言語向けや Python 向けの SDK が動作しなかったとしても、Docker Engine API を直接利用することができます。

Docker Engine SDK の詳細は Docker Engine SDK を利用した開発 を参照してください。

Docker Engine API は RESTful API です。 したがってwgetやcurlなどの HTTP クライアント、あるいは最近のほとんどのプログラミング言語に含まれる HTTP ライブラリからアクセスできます。

API リファレンスの参照

API リファレンスは 最新バージョン あるいは 特定のバージョン を参照できます。

API と SDK のバージョン対応

Docker Engine API のどのバージョンを利用するかは、Docker デーモンおよび Docker クライアントのバージョンによります。

Docker Engine SDK のバージョンでは、Docker Engine API の特定のバージョンとそれ以前のバージョンに対応しています。 重大な変更が発生した際には、わかりやすく文書提供します。

デーモンとクライアントでの API バージョン相違

Docker デーモンとクライアントのバージョンは、常に同一でなければならないというわけでもありません。 ただし以下の点に留意しておく必要があります。

  • クライアントよりもデーモンのバージョンの方が新しい場合、デーモンに新たな機能があってもクライアントにはわかりません。 また廃止決定となった API エンドポイントもわかりません。

  • デーモンよりもクライアントのバージョンの方が新しい場合、デーモンがわかっていない API リクエストエンドポイントをクライアントが送信することがありえます。

新たな機能が API に追加されると、API の新バージョンとしてリリースされます。 Docker API には下位互換性があるため、新たな機能を活用する目的がなければ、API を利用するコードを更新する必要はありません。

Docker デーモンとクライアントが対応している最新 API バージョンを確認するにはdocker versionを実行します。

$ docker version

Client: Docker Engine - Community
 Version:           20.10.0
 API version:       1.41
 Go version:        go1.13.15
 Git commit:        7287ab3
 Built:             Tue Dec  8 19:00:39 2020
 OS/Arch:           linux/amd64
 Context:           default
 Experimental:      true
Server: Docker Engine - Community
 Engine:
  Version:          20.10.0
  API version:      1.41 (minimum version 1.12)
  Go version:       go1.13.15
  Git commit:       eeddea2
  Built:            Tue Dec  8 18:58:12 2020
  OS/Arch:          linux/amd64
  ...

利用する API のバージョンを指定するには、以下のいずれかの方法をとります。

  • SDK を利用する場合には、できるだけ最新バージョンを利用します。 最低でも必要とする機能を実現する API バージョンを利用します。

  • curlを直接利用する場合は、URL の冒頭部分にバージョンを指定します。 たとえばエンドポイントが/containers/である場合は/v1.41/containers/とします。

  • Docker CLI や Docker Engine SDK が利用する API バージョンをdocker versionに示されるバージョンではなく、それよりも古いものを利用するには、環境変数DOCKER_API_VERSIONにそのバージョンを指定します。 これは Linux、Windows、macOS の各クライアントにおいて動作します。

    $ DOCKER_API_VERSION='1.41'

    この環境変数が設定されている間は、Docker デーモンがより新しいバージョンに対応していても、そのバージョンの API が利用されます。 この環境変数を設定すると API バージョンのネゴーシエーションが無効になるため、これを利用するのは API の特定バージョンがどうしても必要な場合、あるいはデバッグ目的で利用する場合のみとしてください。

  • Go 言語向け SDK では API バージョンのネゴーシエーションが有効になります。 つまりクライアントと Docker Engine の両方に対応する API バージョンが自動的に選択されます。

  • SDK の利用時では、API バージョンをプログラム内から指定することもできます。 これはclientオブジェクトに対する引数として指定するものです。 詳しくは Go 言語のコンストラクター または Python SDK ドキュメントの client の項 を参照してください。

API バージョン表

Docker バージョン 最大 API バージョン 変更履歴
20.10 1.41 変更履歴
19.03 1.40 変更履歴
18.09 1.39 変更履歴
18.06 1.38 変更履歴
18.05 1.37 変更履歴
18.04 1.37 変更履歴
18.03 1.37 変更履歴
18.02 1.36 変更履歴
17.12 1.35 変更履歴
17.11 1.34 変更履歴
17.10 1.33 変更履歴
17.09 1.32 変更履歴
17.07 1.31 変更履歴
17.06 1.30 変更履歴
17.05 1.29 変更履歴
17.04 1.28 変更履歴
17.03.1 1.27 変更履歴
17.03 1.26 変更履歴
1.13.1 1.26 変更履歴
1.13 1.25 変更履歴
1.12 1.24 変更履歴
1.11 1.23 変更履歴
1.10 1.22 変更履歴
1.9 1.21 変更履歴
1.8 1.20 変更履歴
1.7 1.19 変更履歴
1.6 1.18 変更履歴

アーカイブ API バージョン

より古い API のドキュメントはアーカイブされています。 これは GitHub 上の Docker コードリポジトリ から参照できます。

developing, api