本頁說明如何新增、查看及刪除 Python 套件和套件版本。
事前準備
-
如要執行 Python 存放區的指令，必須使用 Google Cloud CLI 354.0.0 以上版本。您可以使用下列指令查看版本：
gcloud version 如果目標存放區不存在，請建立新的 Python 套件存放區。
確認已安裝 Python 3。如需安裝操作說明，請參閱Google Cloud 設定 Python 的教學課程。
(選用) 設定 gcloud 指令的預設值。
如果您使用 keyring 驗證搭配 gcloud 憑證，請使用使用者帳戶或服務帳戶登入 Google Cloud CLI。
必要的角色
如要取得管理套件所需的權限，請要求管理員在存放區中授予您下列 IAM 角色：
-
查看套件或套件中的檔案：
Artifact Registry Reader (
roles/artifactregistry.reader) -
下載或安裝套件：
Artifact Registry 讀取者 (
roles/artifactregistry.reader) -
將套件新增至存放區：
Artifact Registry Writer (
roles/artifactregistry.writer) -
刪除套件：
Artifact Registry 存放區管理員 (
roles/artifactregistry.repoAdmin)
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。
新增套件
存放區模式：標準
建構 Python 專案時，發布檔案會儲存在專案的 dist 子目錄中。接著，您可以使用 Twine 將套件上傳至標準存放區。
建議您採用下列套件最佳做法：
- 請為私人套件使用不重複的名稱，以免與 pypi.org 上的套件名稱相符，尤其是當您的 pip 設定包含多個套件索引時。
- 請為套件版本號碼使用 PEP 440 中的版本 ID 規格。根據預設，pip 只會安裝穩定版本。它會使用版本 ID 規格區分穩定版和預先發布版本，並剖析要安裝的任何版本需求。
如要新增套裝組合，請按照下列步驟操作：
安裝 Twine。
pip install twine切換至 Python 專案目錄。
從專案的
dist子目錄將發布檔案上傳至存放區。執行下列指令：twine upload dist/*您可以使用
--repository-url旗標指定特定存放區。twine upload --repository-url https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/ dist/*
查看套件和版本
存放區模式：標準、遠端
如要使用 Google Cloud 控制台或 gcloud 查看套件和套件版本，請按照下列步驟操作：
主控台
在 Google Cloud 控制台中開啟「Repositories」頁面。
在存放區清單中，按一下適當的存放區。
「Packages」頁面會列出存放區中的套件。
按一下套件即可查看套件版本。
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
1.0 版中的檔案。
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：優先順序設為100secondary-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 Packaging 說明文件。
刪除套件和版本
存放區模式：標準、遠端
您可以刪除套件和所有版本，也可以刪除特定版本。
- 套件刪除後即無法復原。
- 如果是遠端存放區，系統只會刪除套件的快取副本。上游來源不受影響。如果刪除快取的套件，下次存放區收到相同套件版本的請求時，Artifact Registry 會再次下載並快取該套件。
刪除套件或套件版本前，請確認您已通報或解決其中的任何重要依附元件。
如要刪除套件，請按照下列步驟操作：
主控台
在 Google Cloud 控制台中開啟「Repositories」頁面。
在存放區清單中，按一下適當的存放區。
「Packages」頁面會列出存放區中的套件。
選取要刪除的套件。
按一下 [刪除]。
在確認對話方塊中，按一下「刪除」。
gcloud
執行下列指令：
gcloud artifacts packages delete PACKAGE \
[--repository=REPOSITORY] [--location=LOCATION] [--async]
更改下列內容：
PACKAGE是存放區中的套件名稱。REPOSITORY是存放區的名稱。如果您已設定預設存放區，可以略過此標記，以便使用預設值。-
LOCATION是存放區的地區或多地區位置。 使用這個旗標可查看特定位置的存放區。如果您已設定預設位置，則可以省略此標記，以便使用預設值。
--async 標記會讓指令立即傳回，而不會等待進行中的作業完成。
如要刪除套件版本，請按照下列步驟操作：
主控台
在 Google Cloud 控制台中開啟「Repositories」頁面。
在存放區清單中，按一下適當的存放區。
「Packages」頁面會列出存放區中的套件。
按一下套件即可查看該套件的版本。
選取要刪除的版本。
按一下 [刪除]。
在確認對話方塊中，按一下「刪除」。
gcloud
執行下列指令：
gcloud artifacts versions delete VERSION \
--package=PACKAGE \
[--repository=REPOSITORY] [--location=LOCATION] \
[--async]
更改下列內容：
VERSION是您要刪除的版本名稱。PACKAGE是存放區中的套件名稱。REPOSITORY是存放區的名稱。如果您已設定預設存放區，可以略過此標記，以便使用預設值。-
LOCATION是存放區的地區或多地區位置。 使用這個旗標可查看特定位置的存放區。如果您已設定預設位置，則可以省略此標記，以便使用預設值。
--async 標記會讓指令立即傳回，而不會等待進行中的作業完成。