Docker Registry API – Listing Images and Tags – Docker Registry API – 列出图像和标签

最后修改: 2022年 5月 31日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

In this tutorial, we’ll explore how to list images in a remote Docker registry and how to fetch tags for an image.

在本教程中，我们将探讨如何在远程Docker注册表中列出图像，以及如何为图像获取标签。

This is useful for finding out what versions of a particular image are available in a registry and deciding which one to use.

这对于找出注册表中有哪些特定映像的版本并决定使用哪个版本很有用。

2. Docker Registry API

2.Docker注册表API

A Docker registry provides an API to interact with the registry. This API contains the various endpoints used in the background by the Docker CLI to perform various tasks like pulling, pushing, and tagging images.

Docker注册中心提供了一个与注册中心进行交互的API。该API包含Docker CLI在后台使用的各种端点，以执行各种任务，如拉动、推送和标记图像。。

We can also use these endpoints directly to interact with a registry without using the Docker CLI.

我们也可以直接使用这些端点来与注册表进行交互，而无需使用Docker CLI。

Let’s look at the format of an endpoint of the registry API:

让我们来看看注册表API的端点的格式。

/<api-version>/<repository-name>/<resource>/<params>

Let’s examine the different components of this endpoint:

让我们研究一下这个端点的不同组成部分。

  • API version – the version of the API. For example, the current version is v2.
  • Repository(image) name – The name of the image. The name also can contain a path separated by slashes if it is a nested repository. For example, /ubuntu/nginx or /redis.
  • Resource – The subdivision of the API we want to interact with. For example, manifests will work with manifests of a particular image.
  • Parameters – These are optional parameters that can be used to further refine the operation. For example, manifests/latest will fetch the manifest for the latest tag.

Based on the above rules, below is a concrete example of an endpoint:

基于上述规则，下面是一个具体的端点例子。

GET /v2/ubuntu/nginx/manifests/latest

3. Docker Registry API V2

3.Docker Registry API V2

At the time of writing, V2 is the current version of the Registry API. Let’s explore how to use it to list images and tags from a remote registry.

在撰写本文时，V2是注册表API的当前版本。让我们来探讨一下如何使用它来列出来自远程注册表的图像和标签。

Let’s assume we have a registry deployed at the URL https://my-registry.io. We’ll use curl to execute the HTTP requests.

让我们假设我们有一个部署在URL https://my-registry.io 的注册表。我们将使用curl来执行HTTP请求。

3.1. Listing Images

3.1.上市图片

To list images in a registry, we can use the _/catalog endpoint:

要列出注册表中的图像，我们可以使用_/catalog端点。

$ curl -X GET my-registry.io/v2/_catalog
{"repositories":["centos","ubuntu"]}

We should note that authentication may be required to access certain repositories if it has been enabled. In such cases, we can pass in the username and password as parameters to the curl command using the -u option.

我们应该注意到，如果已经启用了认证，访问某些资源库可能需要认证。在这种情况下，我们可以使用-u选项将用户名和密码作为参数传递给curl命令。

$ curl -u user:password -X GET my-registry.io/v2/_catalog 
{"repositories":["centos","ubuntu"]}

3.2. Paginated Listing Images

3.2.分页的列表图像

Sometimes, a registry will have a large number of images. In such cases, we can add an n=<number of results> parameter to the _/catalog endpoint to get a paginated response:

有时，一个注册表会有大量的图片。在这种情况下，我们可以在_/catalog端点添加一个n=<number of results>参数，以获得一个分页响应：。

$ curl -X GET my-registry.io/v2/_catalog?n=1
{"repositories":["centos"]}

The response contains only the first image now.

响应现在只包含第一张图片。

We can use the response to the first request to get the next page of results. This needs two changes to the curl command:

我们可以使用第一个请求的响应来获得下一页的结果。这需要对curl命令做两个修改。

  • A last parameter to the _/catalog endpoint containing the last image name returned in the previous request.
  • A header linking the new request to the previous one. The header has the format below:
Link: <my-registry.io/v2/_catalog?n=1&last=centos>; rel="next"

The brackets around the URL are required. The URL is the same as the URL of the new request. A rel=”next” header indicates that the new request is a continuation of the previous one as per RFC 5988.

URL周围的括号是必须的。该URL与新请求的URL相同。一个rel=”next”头表示新的请求是前一个请求的延续，按照RFC 5988的规定。。

So let’s make the next request:

因此，让我们提出下一个要求。

$ curl -H 'Link: <my-registry.io/v2/_catalog?n=1&last=centos>; rel="next"' -X GET "my-registry.io/v2/_catalog?n=1&last=centos"
{"repositories":["ubuntu"]}

The response returns the next page of results containing one image.

响应返回包含一张图片的下一页结果。

3.3. Listing Tags

3.3.上市标签

To list the tags of an image, we can use the /tags/list endpoint:

要列出图片的标签，我们可以使用/tags/list端点。

$ curl -X GET my-registry.io/v2/ubuntu/tags/list
{"name":"ubuntu","tags":["latest","16.04"]}

The response contains the name of the image and an array of the tags associated with it.

响应包含图像的名称和与之相关的标签阵列。

We can also use pagination with the same rules as we saw for image listing.

4. Docker Registry API V1

4.Docker Registry API V1

Registry API v1 was deprecated in Docker 17.06 and removed in Docker 17.12. However, if we come across a registry hosted before the deprecation, we can use the v1 API. Let’s explore how our requests change in this case.

注册表API v1在Docker 17.06中被废弃，在Docker 17.12中被移除。然而，如果我们遇到一个在弃用之前托管的注册表，我们可以使用v1版API。让我们探讨一下在这种情况下我们的请求是如何变化的。

4.1. Listing Images

4.1.上市图片

There is no direct endpoint to list images in v1. Instead, we can use the docker search command to search for images containing a given string:

在v1中没有直接的端点来列出图片，相反，我们可以使用docker search命令来搜索包含指定字符串的图片。

$ docker search my-registry.io/centos

This returns a list of images that contain the string “centos” in their name or description.

这将返回名称或描述中包含 “centos “字符串的图像列表。

If we do not specify the registry, the search will be performed in the default registry. The default repository is the Docker Hub repository.

如果我们不指定注册库，搜索将在默认注册库中进行。默认的存储库是Docker Hub存储库。

For example, the below image shows the output when we search for the term “ubuntu” without specifying any repository.

例如，下面的图片显示了当我们搜索 “ubuntu “一词而不指定任何存储库时的输出。

Docker search ubuntu command run in a terminal and results displaying all the images matching the search query

4.2. Listing Tags

4.2.上市标签

The method to list tags is similar to the v2 API. However, the output is different in this case:

列出标签的方法与v2版的API类似。然而，在这种情况下，输出是不同的。

$ curl -X GET https://registry.hub.docker.com/v1/repositories/baeldung/mesos-marathon-demo/tags
[{"layer": "", "name": "32"}, {"layer": "", "name": "33"}, {"layer": "", "name": "34"}]

As we can see, instead of a single array of tags, we have an array of objects. Each object includes the name of the tag and the layer ID of the image.

正如我们所看到的，我们有一个对象的数组，而不是一个单一的标签数组。每个对象包括标签的名称和图像的层ID。

If needed, we can convert the response to an array. To do so, let’s pipe the output into the jq command and parse the JSON:

如果需要，我们可以将响应转换为一个数组。要做到这一点，让我们把输出的数据输入jq命令并解析JSON。

$ curl -s GET https://registry.hub.docker.com/v1/repositories/baeldung/mesos-marathon-demo/tags | jq -r '[.[].name]'
[
  "32",
  "33",
  "34"
]

Let’s understand the jq command and expressions used here:

让我们了解一下这里使用的jq命令和表达方式。

  • The -r flag returns the output as raw text.
  • The expression .[].name returns the name property from each object from the curl output.
  • The square brackets [] around the expression indicate that we want to collect the output in an array.

Finally, the -s flag used with the curl command is required to suppress the progress bar output.

最后，需要使用与curl命令一起使用的 -s标志来抑制进度条的输出。

5. Conclusion

5.总结

In this article, we’ve explored how to use the Docker Registry API to list images and tags in a remote registry.

在这篇文章中，我们已经探讨了如何使用Docker注册表API来列出远程注册表中的图像和标签。

We also looked at how to send paginated requests for images and tags and how to parse JSON responses.

我们还研究了如何为图片和标签发送分页请求以及如何解析JSON响应。