使用指紋驗證套件版本 ID

您可以使用構件指紋，在 Artifact Registry 存放區中明確識別套件。

將套件推送至存放區時，Artifact Registry 會計算該套件版本的指紋。指紋是密碼編譯上不可變動的參照，可用於驗證在 Compute Engine 和 Cloud Build 等 Google Cloud系統之間移動時，套件是否經過修改。擷取套件指紋後，您可以在特定 Artifact Registry API 要求期間使用指紋，確保套件有效。您也可以手動計算本機指紋，並與存放區中的指紋比較，藉此驗證相同套件的本機和存放區執行個體。

事前準備

啟用 Artifact Registry，包括啟用 Artifact Registry API 和安裝 Google Cloud CLI。
(選用) 設定 gcloud 指令的預設值。

必要的角色

如要取得在 Artifact Registry 存放區中查看套件版本指紋所需的權限，請要求管理員授予您 Google Cloud 專案的「Artifact Registry 讀取者」 (roles/artifactregistry.reader) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

擷取存放區中套件版本的指紋

指紋的結構如下：

VERSION@DIRSUM_SHA256:HASH_VALUE

如要擷取 Artifact Registry 存放區中套件版本的指紋，請在 Google Cloud CLI 中輸入下列內容：

gcloud artifacts versions describe VERSION --repository=REPOSITORY --location=LOCATION --package=PACKAGE_NAME

其中：

VERSION 是套件版本，例如 1.0543。
REPOSITORY 是包含您要評估套件的存放區
LOCATION 是存放區的區域或多區域位置。如果您設定預設位置，可以省略這個標記。
PACKAGE_NAME 是套件名稱。

回應的形式如下所示：

fingerprints:
- type: DIRSUM_SHA256
  value: 7c07b910c6dd6df6984a5591d00ad0074fe24cd81145d2c681cdfda3b3d65a04
name: projects/test-project/locations/us-west1/repositories/test-repo/packages/test-pkg/versions/v1
updateTime: '2025-08-15T00:03:41.809228Z'

指紋的完整地址是套件版本，後面接著指紋類型和雜湊值。在本範例中，指紋地址為 VERSION@DIRSUM_SHA256:7c07b910c6dd6df6984a5591d00ad0074fe24cd81145d2c681cdfda3b3d65a04。

在 Artifact Registry API 中，將指紋驗證為不可變動的參照

如果套件的指紋格式如下，特定 Artifact Registry API 要求就會驗證您存放區中的套件：

VERSION@DIRSUM_SHA256:HASH_VALUE

舉例來說，您想在存放區的套件中建立附件。在下列指令中，為 target 定義的套件格式，可讓 Artifact Registry 驗證套件的指紋：

  gcloud artifacts attachments create my-attachment --target='projects/test-project/locations/us-west1/repositories/test-repo/packages/test-pkg/versions/v1@dirsum_sha256:30330c6b65a26ebf1a13e1b9ded4068b4c36d72ed3b62226e3243b5bee18fd31' --attachment-type="application/vnd.in-toto+json" --attachment-namespace="mynamespace.com" --files=att.txt

如果提供的指紋與目前版本的指紋不符，Artifact Registry 就會拒絕 API 要求，並顯示 failed_precondition 錯誤。

透過 API 程式庫、Google Cloud CLI 和 curl 傳遞時，下列要求會驗證提供的指紋：

透過 API 程式庫和 curl 傳遞指紋時，系統會驗證下列要求：

ListAttachments

驗證套件的本機和存放區例項是否相同

如要驗證套件在Google Cloud 系統之間移動時未經過修改，請在存放區外部手動計算該套件例項的指紋。

如要手動計算指紋，請按照下列步驟操作：

按照「查看存放區中套件的指紋」一文的說明，在 Artifact Registry 中找出套件的指紋。
手動計算外部套件的指紋：
1. 取得套件中每個檔案的簡短檔案名稱和個別 SHA256 雜湊值：
  1. 在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面：
    
    開啟「存放區」頁面
  2. 選取存放區，然後選取含有要驗證套件版本的映像檔。
  3. 按一下「檔案」分頁標籤。
  4. 找出頁面顯示的每個檔案的短檔案名稱和 SHA256 雜湊。短檔案名稱是檔案位置後方的最後一個字串。舉例來說，下列螢幕截圖顯示 Maven 存放區中套件的六個 Version 5.0 檔案。每個檔案名稱開頭都是 my-app-5.0。每個檔案的雜湊值會顯示在「Hashes」欄下方：
2. 按檔案名稱的字母順序排序。
3. 針對每個排序後的檔案項目，將檔案資訊合併為下列縮短的字串，在雜湊值和檔案名稱之間加入兩個空格，並以空值位元結尾：
  
  HASH_VALUE FILE_NAME/0
4. 將每個縮短的字串合併為一個完整序列，每個字串之間不得有空格或字元。
5. 計算完整序列的 SHA256 雜湊值。最終 SHA256 雜湊值是外部套件的 dirsum_sha256。
比較手動計算的指紋和存放區中套件的指紋。如果兩項指紋相同，表示存放區中的套件執行個體未經過修改。