在 Artifact Registry 中儲存 Python 套件

本快速入門導覽課程說明如何設定私人的 Artifact Registry Python 存放區、上傳套件，然後安裝套件。

事前準備

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Artifact Registry API.

    Enable the API

  5. Make sure that you have the following role or roles on the project: Artifact Registry Administrator

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      前往 IAM
    2. 選取專案。
    3. 按一下「授予存取權」。

    4. 在「New principals」(新增主體) 欄位中，輸入您的使用者 ID。 這通常是 Google 帳戶的電子郵件地址。

    5. 在「Select a role」(選取角色) 清單中，選取角色。
    6. 如要授予其他角色，請按一下 「新增其他角色」，然後新增每個其他角色。
    7. 按一下 [Save]。

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  7. Verify that billing is enabled for your Google Cloud project.

  8. Enable the Artifact Registry API.

    Enable the API

  9. Make sure that you have the following role or roles on the project: Artifact Registry Administrator

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      前往 IAM
    2. 選取專案。
    3. 按一下「授予存取權」。

    4. 在「New principals」(新增主體) 欄位中，輸入您的使用者 ID。 這通常是 Google 帳戶的電子郵件地址。

    5. 在「Select a role」(選取角色) 清單中，選取角色。
    6. 如要授予其他角色，請按一下 「新增其他角色」，然後新增每個其他角色。
    7. 按一下 [Save]。

    10. 啟動 Cloud Shell

    在本快速入門導覽課程中，您將使用 Cloud Shell，這是用來管理Google Cloud上託管資源的殼層環境。

    Cloud Shell 已預先安裝 Google Cloud CLI 和 Python。gcloud CLI 是 Google Cloud的主要指令列介面。

    啟動 Cloud Shell：

    1. 前往 Google Cloud 控制台。

      Google Cloud console

    2. 在 Google Cloud 控制台工具列中，按一下「啟用 Cloud Shell」：

    此時 Cloud Shell 工作階段會在主控台底部的頁框中開啟，您可以使用這個殼層來執行 gcloud 指令。

    安裝必要套件

    Twine 是用來發布 Python 套件的工具。您將使用 Twine 將套件上傳至 Artifact Registry。

    在本快速入門導覽課程中，您將使用 Cloud Shell 隨附的 Python 安裝套件。這個預設安裝作業包含 Artifact Registry 金鑰環後端，可處理 Artifact Registry 的驗證作業。如果您建立虛擬環境或在 Cloud Shell 以外設定 Python，則必須安裝用於驗證的 keyring 後端。詳情請參閱「使用金鑰環進行驗證」。

    如要安裝 Twine，請執行下列指令：

    pip install twine

    您現在可以設定 Artifact Registry。

    建立存放區

    為套件建立存放區。

    1. 執行下列指令，以便在 us-central1 位置中的 quickstart-python-repo 當前專案內建立新的 Python 套件存放區。

      gcloud artifacts repositories create quickstart-python-repo \
    --repository-format=python \
    --location=us-central1 \
    --description="Python package repository"

    2. 執行下列指令來確認存放區已建立完成：

      gcloud artifacts repositories list

    3. 如要簡化 gcloud 指令，請將預設存放區設為 quickstart-python-repo，預設位置設為 us-central1。 設定值後，您不需要在需要存放區或位置的 gcloud 指令中指定這些值。

      如要設定存放區，請執行下列指令：

      gcloud config set artifacts/repository quickstart-python-repo

      如要設定位置，請執行下列指令：

      gcloud config set artifacts/location us-central1

      如要進一步瞭解這些指令，請參閱 gcloud config set 說明文件。

    設定驗證機制

    Artifact Registry 金鑰環後端會使用應用程式預設憑證 (ADC) 尋找憑證。這項策略會在您的環境中尋找憑證。

    在本快速入門導覽課程中，您將：

    • 產生 ADC 的使用者憑證。在實際工作環境中，您應使用服務帳戶，並透過 GOOGLE_APPLICATION_CREDENTIALS 環境變數提供憑證。
    • 在 pip 和 twine 指令中加入 Artifact Registry 存放區網址，這樣就不必使用存放區網址設定 pip 和 Twine。

    如要產生 ADC 的憑證，請執行下列指令：

    gcloud auth application-default login

    如要進一步瞭解驗證方法，以及如何將存放區新增至 pip 和 Twine 設定，請參閱「為 Python 套件存放區設定驗證機制」。

    取得範例套件

    建構 Python 專案時，發布檔案會儲存在 Python 專案的 dist 子目錄中。為簡化本快速入門導覽課程，您將下載預先建構的套件檔案。

    1. 建立名為 python-quickstart 的 Python 專案資料夾。

      mkdir python-quickstart

    2. 建立名為 dist 的子目錄，然後切換至該目錄。

      mkdir python-quickstart/dist
cd python-quickstart/dist

    3. 下載 Python Packaging 使用者指南教學課程「封裝 Python 專案」中使用的 Python 套件範例。

      pip download sampleproject

      這項指令會下載 sampleproject 套件及其依附元件 peppercorn。

    將套件上傳至存放區

    使用 Twine 將套件上傳至存放區。

    1. 從 dist 目錄變更為上層 python-quickstart 目錄。

      cd ..

    2. 從 dist 目錄將套件上傳至存放區。

      python3 -m twine upload --repository-url https://us-central1-python.pkg.dev/PROJECT_ID/quickstart-python-repo/ dist/*

      使用 python3 -m 執行指令時，Python 會找出 twine 並執行指令。如果 twine 指令位於系統路徑中，您可以執行該指令，不必使用 python3 -m。

    Twine 會將 sampleproject 和 peppercorn 上傳至存放區。

    查看存放區中的套件

    如要確認套件已新增，請列出 quickstart-python-repo 存放區中的套件。

    執行下列指令：

    gcloud artifacts packages list --repository=quickstart-python-repo

    如要查看套件的版本，請執行下列指令：

    gcloud artifacts versions list --package=PACKAGE

    其中的 PACKAGE 為套件 ID。

    安裝套件

    執行下列指令來安裝套件：

    pip install --index-url https://us-central1-python.pkg.dev/PROJECT_ID/quickstart-python-repo/simple/ sampleproject

    疑難排解

    根據預設，pip 和 Twine 等工具不會傳回詳細的錯誤訊息。如果發生錯誤，請使用 --verbose 標記重新執行指令，取得更詳細的輸出內容。詳情請參閱「Python 套件疑難排解」。

    清除所用資源

    如要避免系統向您的 Google Cloud 帳戶收取本頁所用資源的費用，請按照下列步驟操作。

    移除存放區之前，請先確認要保留的套件均已存放於其他位置。

    如要刪除存放區，請按照下列指示操作：

    1. 如要刪除 quickstart-python-repo 存放區，請執行下列指令：

      gcloud artifacts repositories delete quickstart-python-repo

    2. 如要移除您為使用中的 gcloud 設定建立的預設存放區和位置設定，請執行下列指令：

      gcloud config unset artifacts/repository
gcloud config unset artifacts/location

    後續步驟