管理 Python 套件

本頁面說明如何新增、查看及刪除 Python 套件和套件版本。

事前準備

1. 安裝並初始化 Google Cloud CLI。

   如要執行 Python 存放區的指令，必須使用 Google Cloud CLI 354.0.0 以上版本。您可以使用下列指令查看版本：

   gcloud version
   

2. 如果目標存放區不存在，請建立新的 Python 套件存放區。

3. 確認是否已安裝 Python 3。如需安裝操作說明，請參閱Google Cloud Python 設定教學課程。

4. (選用) 設定 gcloud 指令的預設值。

5. 如果您使用鑰匙圈驗證和 gcloud 憑證，請使用使用者帳戶或服務帳戶登入 Google Cloud CLI。

必要的角色

如要取得管理套件所需的權限，請要求管理員為您授予存放區的下列 IAM 角色：

• 查看套件或套件中的檔案： Artifact Registry 讀取器 (roles/artifactregistry.reader)
• 下載或安裝套件： Artifact Registry Reader (roles/artifactregistry.reader)
• 將套件新增至存放區： Artifact Registry Writer (roles/artifactregistry.writer)
• 刪除套件： Artifact Registry Repository Administrator (roles/artifactregistry.repoAdmin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

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

新增套件

存放區模式：標準

建構 Python 專案時，發布檔案會儲存在專案的 dist 子目錄中。接著，您可以使用 Twine 將套件上傳至標準存放區。

建議您採用下列套件最佳做法：

• 請為私人套件使用不重複的名稱，以免與 pypi.org 上的套件名稱相符，特別是當 pip 設定包含多個套件索引時。
• 請使用 PEP 440 中的版本 ID 規格，為套件版本編號命名。根據預設，pip 只會安裝穩定版本。它會使用版本 ID 規格來區分穩定版和預發布版，並剖析要安裝的版本的任何需求。

如要新增套件，請按照下列步驟操作：

1. 安裝 Twine。

   pip install twine
   

2. 切換至 Python 專案目錄。

3. 從專案 dist 子目錄將發布檔案上傳至存放區。執行下列指令：

   twine upload dist/*
   

   您可以使用 --repository-url 標記指定特定存放區。

   twine upload --repository-url https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/ dist/*
   

查看套件和版本

存放區模式：標準、遠端

如要使用 Google Cloud 控制台或 gcloud 查看套件和套件版本，請按照下列步驟操作：

gcloud artifacts packages list [--repository=REPOSITORY] [--location=LOCATION]

gcloud artifacts versions list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

對於遠端存放區，傳回的清單應包含所有直接和間接依附元件。

列出檔案

存放區模式：標準、遠端

您可以列出存放區中的檔案、指定套件所有版本中的檔案，或套件特定版本中的檔案。

對於下列所有指令，您可以將 --limit 標記新增至指令，藉此設定要傳回的檔案數量上限。

如要設定預設值時，列出預設專案、存放區和位置中的所有檔案：

gcloud artifacts files list

如要列出指定專案、存放區和位置中的檔案，請執行下列指令：

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

如要列出特定套件的所有版本檔案，請按照下列步驟操作：

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE

如要列出特定套件版本的檔案，請按照下列步驟操作：

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION

替換下列值：

• LOCATION：存放區的區域或多區域位置。
• PROJECT：您的 Google Cloud 專案 ID。如果您的專案 ID 包含冒號 (:)，請參閱網域範圍專案。
• REPOSITORY：圖片儲存的存放區名稱。
• PACKAGE：套件名稱。
• VERSION：套件版本。

範例

請參考以下包裝資訊：

• 專案：my-project
• 存放區：my-repo
• 存放區位置：us-west1
• 檔案包：my-app

下列指令會列出預設專案中 us-west1 位置的存放區 my-repo 中的所有檔案：

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --version=1.0

安裝套件

存放區模式：標準、遠端、虛擬

使用 pip 指令安裝套件。

如要安裝套件的最新穩定版，請執行下列指令：

pip install PACKAGE

如為標準存放區，您可以直接從存放區下載套件。

對於遠端存放區，您會下載套件及其依附元件的快取副本。如果沒有快取副本，遠端存放區會從上游來源下載套件，並在快取後再提供給您。您可以查看存放區中的套件清單，確認遠端存放區已從上游來源擷取套件。

對於虛擬存放區，Artifact Registry 會在上游存放區中搜尋要求的套件。

• 如果快取副本不存在，上游遠端存放區會下載並快取要求的套件。虛擬存放區只會提供要求的套件，不會儲存套件。
• 如果您要求的版本可在多個上游存放區中使用，Artifact Registry 會根據為虛擬存放區設定的優先順序設定，選擇要使用的上游存放區。

舉例來說，假設虛擬存放區針對上游存放區設定了下列優先順序：

• main-repo：優先順序設為 100
• secondary-repo1：優先順序設為 80。
• secondary-repo2：優先順序設為 80。
• test-repo：優先順序設為 20。

main-repo 的優先順序值最高，因此虛擬存放區一律會優先搜尋該值。

secondary-repo1 和 secondary-repo2 的優先順序都設為 80。如果 main-repo 中沒有要求的套件，Artifact Registry 會接著搜尋這些存放區。由於兩者具有相同的優先順序值，如果兩個存放區都提供該版本，Artifact Registry 可以選擇從任一存放區提供套件。

test-repo 是最低優先順序值，如果其他上游存放區都沒有，則會提供已儲存的構件。

其他資訊

根據預設，pip 會安裝套件的穩定版，並忽略預先發布版。PEP 440 定義了 Python 版本 ID 規格，供 pip 使用者剖析版本號碼，包括預先發布版本。

如要在 pip 搜尋要安裝的套件時納入預先發布版，請在指令中加入 --pre 旗標。

pip install --pre PACKAGE

如要指定必要版本或版本範圍，請加入需求指定碼。您可以直接在指令中加入版本需求，或是使用需求檔案。

舉例來說，這個指令會指定 my-package 的最低版本為開發版本 1.0.dev0。

pip install --pre my-package>=1.0.dev0

穩定版會被視為比預先發布版新，因此如果存放區中有 1.0 版本，pip 會選擇 1.0 版本，而非預先發布版。

如果您未指定存放區，pip.conf 中的 pip 設定會決定 pip 搜尋套件的順序。

• 如果您使用 index-url 設定來設定 Artifact Registry 存放區，且未設定其他套件索引，pip 只會在 Artifact Registry 存放區中搜尋套件。
• 如果您使用的是虛擬存放區，當有多個上游存放區含有要求的套件版本時，Artifact Registry 會使用上游政策中設定的優先順序來選擇套件。如果兩個含有套件的存放區優先順序相同，Artifact Registry 會從任一存放區提供套件。
• 如果您使用 extra-index-url 設定來設定 pip，或是設定多個套件索引，pip 會搜尋 pypi.org 和任何其他已設定的套件索引，然後選擇套件的最新版本。

您可以在 requirements 檔案中覆寫 index-url 或 extra-index-url 設定。您也可以在 pip 指令中使用這些設定的旗標。例如，這個指令會使用 Artifact Registry 存放區覆寫 index-url。

pip install --index-url https://us-east1-python.pkg.dev/my-project/python-repo/simple/ my-package

如要進一步瞭解如何安裝套件，請參閱 Python 套件說明文件。

刪除套件和版本

存放區模式：標準、遠端

您可以刪除套件及其所有版本，或刪除特定版本。

• 刪除套件後即無法復原。
• 對於遠端存放區，系統只會刪除套件的快取副本。上游來源不受影響。如果您刪除快取的套件，Artifact Registry 會在下次存放區收到相同套件版本的要求時，再次下載並快取該套件。

刪除套件或套件版本前，請確認您已通報或解決其中的任何重要依附元件。

如要刪除套件，請按照下列步驟操作：

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

如要刪除套件版本，請按照下列步驟操作：

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

後續步驟

• 瞭解如何管理 Java 套件
• 瞭解如何管理 Node.js 套件
• 瞭解如何管理容器映像檔
• 下載套件中的個別檔案