如何通过REST API检查Azure Docker Registry中Docker标签是否存在（不使用az工具）

我之前在CI流程里也遇到过一模一样的问题——想用纯HTTP API检查Azure私有容器注册表（ACR）里的镜像标签是否存在，不用az cli工具，结果一开始照搬Docker Hub的API路径直接404。后来研究了ACR的REST API规范，终于搞定了，给你一步步说怎么实现：

第一步：获取ACR的访问令牌 #

ACR的所有v2 API请求都需要带有效的Bearer令牌认证，所以首先得用ACR的访问密钥生成令牌。你可以在Azure门户的ACR资源里，进入「访问密钥」页面，开启管理员用户，然后复制用户名（就是你的ACR名称）和其中一个密码。

用curl生成令牌的命令如下：

# 替换成你的ACR名称、访问密钥和目标镜像仓库名
ACR_NAME="my-acr-registry"
ACR_PASSWORD="my-acr-admin-password"
TARGET_REPO="my-app-image"

# 请求获取访问令牌
TOKEN=$(curl -s -u "$ACR_NAME:$ACR_PASSWORD" \
  "https://$ACR_NAME.azurecr.io/oauth2/token?service=$ACR_NAME.azurecr.io&scope=repository:$TARGET_REPO:pull" \
  | jq -r '.access_token')

这里的scope参数指定了我们只需要目标仓库的pull权限，足够用来检查标签存在性了。如果没有jq的话，也可以用awk或者sed来提取token，比如：

TOKEN=$(curl -s -u "$ACR_NAME:$ACR_PASSWORD" "https://$ACR_NAME.azurecr.io/oauth2/token?service=$ACR_NAME.azurecr.io&scope=repository:$TARGET_REPO:pull" | grep -o '"access_token":"[^"]*"' | cut -d'"' -f4)

第二步：检查目标标签是否存在 #

有了令牌之后，就可以通过请求镜像manifest的方式来判断标签是否存在。ACR的v2 API中，访问特定标签的manifest路径是https://<ACR_NAME>.azurecr.io/v2/<REPO_NAME>/manifests/<TAG_NAME>：

TARGET_TAG="v1.2.3"

# 发送HEAD请求（比GET更轻量，只返回响应码）
RESPONSE_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $TOKEN" \
  "https://$ACR_NAME.azurecr.io/v2/$TARGET_REPO/manifests/$TARGET_TAG")

# 根据响应码判断
if [ "$RESPONSE_CODE" -eq 200 ]; then
  echo "✅ 标签 $TARGET_TAG 已存在于仓库 $TARGET_REPO 中，跳过推送"
  # 这里写CI中跳过推送的逻辑
else
  echo "❌ 标签 $TARGET_TAG 不存在，开始执行推送流程"
  # 这里写你的镜像推送命令，比如 docker push $ACR_NAME.azurecr.io/$TARGET_REPO:$TARGET_TAG
fi

• 如果返回200，说明标签存在；
• 如果返回404，说明标签不存在；
• 如果返回401，那大概率是令牌无效或者权限不够，检查一下ACR的用户名密码、scope参数是否正确。

补充：批量获取仓库所有标签 #

如果你需要一次性获取某个仓库的所有标签，也可以用这个API：

curl -s -H "Authorization: Bearer $TOKEN" "https://$ACR_NAME.azurecr.io/v2/$TARGET_REPO/tags/list"

返回的JSON会包含一个tags数组，你可以用jq或者其他工具检查目标标签是否在数组里，但这种方式比直接查manifest要低效，尤其是仓库标签很多的时候，所以更推荐上面的manifest检查方式。

内容的提问来源于stack exchange，提问作者alonisser