在 Python 中指定依附元件

您可以透過兩種方式,為以 Python 編寫的 Cloud Run 函式指定依附元件:使用 pip 套件管理員的 requirements.txt 檔案,或與您的函式一起封裝本機依附元件。

系統並不支援使用 Pipfile/Pipfile.lock 標準指定依附元件。您的專案不應包含這些檔案。

Functions Framework 是所有函式必備的依附元件。雖然 Cloud Run 會在函式建立時代表您安裝該函式,但我們建議您將其納入為明確的依附元件。

透過 pip 指定依附元件

Python 中的依附元件由 pip 管理,並以名為 requirements.txt 的中繼資料檔案表示。這個檔案所在的目錄必須與包含函式程式碼的 main.py 檔案相同。

部署或重新部署函式時,Cloud Run 會使用 pip 下載並安裝 requirements.txt 檔案中宣告的最新依附元件版本。requirements.txt 檔案中,一行代表一個套件,每行都包含套件名稱以及要求的版本。詳情請參閱 requirements.txt 參考資料

為避免建構作業受到依附元件版本變更的影響,建議您將依附元件套件固定為特定版本。

以下是 requirements.txt 檔案範例:

functions-framework
requests==2.20.0
numpy

封裝本機依附元件

您也可以將依附元件與函式一起封裝及部署。如果您無法透過 pip 套件管理工具使用依附元件,或是 Cloud Run 環境的網際網路存取權受限,這項做法就很實用。

舉例來說,您可以採用如下的目錄結構:

myfunction/
├── main.py
└── localpackage/
    ├── __init__.py
    └── script.py

接著,您可以使用下列 import 陳述式,照常從 localpackage 匯入程式碼。

# Code in main.py
from localpackage import script

請注意,這個方法「不會」執行任何 setup.py 檔案。含有這些檔案的套件仍可打包,但可能無法在 Cloud Run 函式上正確執行。

已複製的依附元件

複製的依附元件是指原始來源直接包含在原始碼套件中,並與您自己的程式碼一併重建的依附元件。使用 GOOGLE_VENDOR_PIP_DEPENDENCIES 建構環境變數建立複製的 pip 依附元件,並避免在部署期間安裝這些依附元件。

建立複製的依附元件

  1. 請確認開發系統已安裝 python3

  2. 在開發樹狀結構的根目錄中,宣告應用程式依附元件requirements.txt 檔案。

  3. requirements.txt 檔案中,將 functions-framework 放在個別行中,宣告 Functions Framework 為需求。

  4. 將函式的依附元件下載到本機目錄。這項操作的步驟取決於依附元件是 Python wheel (*.whl) 檔案或 tar 檔案 (*.tar.gz)。

    1. 如果依附元件是 Python 輪子 (*.whl),請使用以下 pip 指令將其下載至開發樹狀結構根目錄:

      python3 -m pip download -r requirements.txt --only-binary=:all: \
         -d DIRECTORY \
         --python-version PYTHON_RUNTIME_VERSION \
         --platform manylinux2014_x86_64 \
         --implementation cp
      

      取代:

      • DIRECTORY:要下載至其中的本機目錄名稱。
      • PYTHON_RUNTIME_VERSION:用於相容性檢查的 Python 版本。例如 Python 3.11 的 311
        這個版本必須與支援的 Python 執行階段之一相符。

      產生的目錄結構應如下所示:

      myfunction/
      ├── main.py
      └── requirements.txt
      └── DIRECTORY
         ├── dependency1.whl
         └── dependency2.whl
      
    2. 如果依附元件是 tar 檔案 (*.tar.gz):

      1. 如果依附元件是用 Python 編寫,請使用 pip 下載:

        python3 -m pip download -r requirements.txt \
           -d DIRECTORY
        
      2. 如果依附元件包含以 C 或 C++ 編寫的程式碼,您必須另外下載並編譯這些程式碼。

  5. 部署函式及其複製的依附元件:

    gcloud functions deploy FUNCTION_NAME \
      --runtime PYTHON_RUNTIME_NAME \
      --set-build-env-vars GOOGLE_VENDOR_PIP_DEPENDENCIES=DIRECTORY
    

    取代:

    • FUNCTION_NAME:您要部署的函式名稱。
    • PYTHON_RUNTIME_NAME支援的 Python 執行階段名稱,用於執行已部署的函式,例如 python311。這個版本必須與您在本機開發環境中使用的 Python 執行階段版本相同。
    • DIRECTORY:包含複製依附元件的目錄名稱。

如要進一步瞭解如何使用 Buildpack,請參閱「使用 Buildpack 建構函式」。

使用私人依附元件

您可以使用 Artifact Registry 或其他存放區中的私人依附元件。

來自 Artifact Registry 的私人依附元件

Artifact Registry Python 存放區可為 Python 函式代管私人依附元件。部署至 Cloud Run 時,建構程序會自動為 Cloud Build 服務帳戶產生 Artifact Registry 憑證。您只需要在 requirements.txt 中加入 Artifact Registry 網址,而不需要產生其他憑證。例如:

--index-url REPOSITORY_URL
sampleapp
Flask==0.10.1
google-cloud-storage

如果您的建構作業需要多個存放區,請使用 Artifact Registry 虛擬存放區,安全地控管 pip 搜尋存放區的順序。

來自其他存放區的私人依附元件

依附元件安裝在 Cloud Build 環境中,該環境無法提供 SSH 金鑰的存取權。如果套件託管在需要 SSH 型驗證的存放區內,則必須與專案的程式碼一起複製及上傳,如前一節所述。

在部署應用程式前,您可以搭配 -t DIRECTORY 標記使用 pip install 指令,將私人依附元件複製到本機目錄中,步驟如下:

  1. 將您的依附元件複製到本機目錄:

    pip install -t DIRECTORY DEPENDENCY
  2. DIRECTORY 目錄中新增一個空白的 __init__.py 檔案,將其轉換成模組。

  3. 從此模組匯入以使用您的依附元件:

    import DIRECTORY.DEPENDENCY

預先安裝的套件

在部署期間,系統會自動一併安裝以下 Python 套件和您的函式。如果您要在函式程式碼中使用下列任一套件,建議您在 requirements.txt 檔案中加入下列版本:

Python 3.8 以上版本

blinker==1.8.2
click==8.1.8
cloudevents==1.11.0
deprecation==2.1.0
Flask==3.0.3
functions-framework==3.8.2
gunicorn==23.0.0
importlib_metadata==8.5.0
itsdangerous==2.2.0
Jinja2==3.1.6
MarkupSafe==2.1.5
packaging==25.0
watchdog==4.0.2
Werkzeug==3.0.6
zipp==3.20.2

Python 3.7

aiohttp==3.8.1
aiosignal==1.2.0
async-timeout==4.0.2
attrs==21.4.0
cachetools==4.2.4
certifi==2021.10.8
chardet==4.0.0
charset-normalizer==2.0.10
click==8.0.3
Flask==2.0.2
frozenlist==1.2.0
google-api-core==2.3.2
google-api-python-client==2.34.0
google-auth==2.3.3
google-auth-httplib2==0.1.0
google-cloud-core==2.2.1
google-cloud-trace==1.5.1
googleapis-common-protos==1.54.0
grpcio==1.43.0
grpcio-status==1.43.0
httplib2==0.20.2
idna==3.3
itsdangerous==2.0.1
Jinja2==3.1.6
MarkupSafe==2.0.1
multidict==5.2.0
opencensus==0.8.0
opencensus-context==0.1.2
packaging==21.3
proto-plus==1.19.8
protobuf==3.19.1
pyasn1==0.4.8
pyasn1-modules==0.2.8
pyparsing==3.0.6
pytz==2021.3
PyYAML==6.0
requests==2.27.1
rsa==4.8
setuptools==60.3.1
six==1.16.0
uritemplate==4.1.1
urllib3==1.26.7
Werkzeug==2.0.2
wrapt==1.13.3
yarl==1.7.2

* `pip` (latest version)
* `setuptools` (latest version)
* `wheel` (determined by product requirements)

此外,Python 執行階段在執行環境中還包含多個系統套件