此页面由 Cloud Translation API 翻译。

使用启动后脚本

本指南介绍了如何在 Colab Enterprise 中使用启动后脚本。本指南还介绍了如何设置环境变量以用于启动后脚本。

概览

您可以使用启动后脚本在 Colab Enterprise 运行时启动过程结束后执行任务。例如，您可以使用启动后脚本来安装特定软件包或对运行时的虚拟机进行特定更改。

如需在 Colab Enterprise 中使用启动后脚本，您可以在创建运行时模板时指定启动后脚本。然后，当您基于该运行时模板创建运行时时，启动后脚本会在启动过程结束时运行。

启动后脚本位置

启动后脚本 URI 可以是以下任意一种：

Cloud Storage URI：例如 gs://BUCKET_NAME/SCRIPT_FILE_NAME。如果启动后脚本存储在 Cloud Storage 中，您必须使用已启用最终用户凭据的运行时。这是因为 Colab Enterprise 使用您的用户凭据来访问 Cloud Storage 存储桶。
HTTPS 网址：例如，https://example.com/FOLDER_NAME/SCRIPT_FILE_NAME。使用 Google Cloud 控制台创建运行时模板时，不支持使用 HTTPS 网址。

启动后脚本行为

您可以指定启动后脚本的行为。请参阅下表：

行为	说明
运行一次 (`RUN_ONCE`)	默认值。Colab Enterprise 仅在创建运行时期间运行一次启动后脚本。
每次启动都运行 (`RUN_EVERY_START`)	每次启动后，Colab Enterprise 都会运行启动后脚本。例如，如果空闲关停停止了运行时，则当运行时重新启动时，Colab Enterprise 会再次运行启动后脚本。
每次启动都下载并运行 (`DOWNLOAD_AND_RUN_EVERY_START`)	每次启动后，Colab Enterprise 都会从其来源重新下载启动后脚本，然后运行该脚本。

环境变量

您可以在运行时模板中指定环境变量，并在启动后脚本中引用这些变量。

例如，您可以使用环境变量设置配额项目。您可以使用 GOOGLE_CLOUD_QUOTA_PROJECT（ Google Cloud客户端库中使用的常见变量）将配额项目设置为特定项目 ID。

如需使用包含环境变量的启动后脚本，请参阅创建包含启动后脚本和环境变量的运行时模板。

跟踪对启动后脚本的更改并恢复启动后脚本

如需跟踪启动后脚本的更改并能够恢复特定版本的启动后脚本，请将启动后脚本存储在启用了对象版本控制功能的 Cloud Storage 存储桶中。对象版本控制会将已删除的对象保留为有版本控制的非当前对象，这些对象在明确移除之前仍可在存储桶中访问。

如需指定启动后脚本的版本，请在创建运行时模板时，将 #GENERATION_NUMBER 添加到启动后脚本的 URI 中，例如 gs://BUCKET_NAME/FOLDER_NAME/FILE_NAME.py#GENERATION_NUMBER。如需详细了解对象版本控制和代数，请参阅对象版本控制。

使用 Google Cloud 控制台创建运行时模板时，不支持为启动后脚本指定代际编号。

准备工作

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
- Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Verify that billing is enabled for your Google Cloud project.
Enable the Vertex AI, Dataform, and Compute Engine APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the APIs

所需的角色

如需获得在 Colab Enterprise 中创建运行时模板所需的权限，请让您的管理员为您授予项目的 Colab Enterprise Admin (roles/aiplatform.colabEnterpriseAdmin) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

一个或多个必需的角色可提供 dataform.repositories.list 权限。在项目中被授予 dataform.repositories.list 权限或 Code Creator (roles/dataform.codeCreator) 角色的用户可以使用 Dataform API 或 Dataform 命令行界面 (CLI) 列出该项目中代码资产的名称。使用 BigQuery Studio 的非管理员只能看到他们创建或与他们共享的代码资产。

创建使用启动后脚本的运行时模板

如需创建使用启动后脚本的运行时模板，您可以使用 Google Cloud 控制台、Google Cloud CLI 或 REST API。

控制台

如需创建使用启动后脚本的运行时模板，请执行以下操作：

在 Google Cloud 控制台中，前往 Colab Enterprise 运行时模板页面。

进入运行时模板
点击 新建模板。

此时会显示创建新的运行时模板对话框。
在运行时基本信息部分中，输入显示名称。
在区域菜单中，选择需要运行时模板的区域。
在环境部分的启动后脚本字段中，点击浏览，然后前往 Cloud Storage 中位于启动后脚本。如需了解详情，请参阅启动后脚本位置。
在“启动后脚本网址”下方，选择启动后脚本的行为。默认行为是运行一次。如需了解详情，请参阅启动后脚本行为。
在网络和安全部分中，确保已选择启用最终用户凭据。
完成对话框的其余部分，然后点击创建。

您的运行时模板会显示在运行时模板标签页上的列表中。

gcloud

在使用下面的命令数据之前，请先进行以下替换：

DISPLAY_NAME：运行时模板的显示名称。
PROJECT_ID：您的项目 ID。
REGION：您希望运行时模板所在的区域。
POST_STARTUP_SCRIPT_URI：启动后脚本的 URI。如需了解详情，请参阅启动后脚本位置。
POST_STARTUP_SCRIPT_BEHAVIOR：启动后脚本的行为。请参阅启动后脚本行为。

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" \
    --project=PROJECT_ID \
    --region=REGION \
    --machine-type=e2-standard-4 \
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI \
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR

Windows (PowerShell)

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" `
    --project=PROJECT_ID `
    --region=REGION `
    --machine-type=e2-standard-4 `
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI `
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR

Windows (cmd.exe)

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" ^
    --project=PROJECT_ID ^
    --region=REGION ^
    --machine-type=e2-standard-4 ^
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI ^
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR

如需详细了解用于从命令行创建运行时模板的命令，请参阅 gcloud CLI 文档。

REST

在使用任何请求数据之前，请先进行以下替换：

REGION：您希望运行时模板所在的区域。
PROJECT_ID：您的项目 ID。
DISPLAY_NAME：运行时模板的显示名称。
POST_STARTUP_SCRIPT_URI：启动后脚本的 URI。如需了解详情，请参阅启动后脚本位置。
POST_STARTUP_SCRIPT_BEHAVIOR：启动后脚本的行为。请参阅启动后脚本行为。

HTTP 方法和网址：

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates

请求 JSON 正文：

{
  "displayName": "DISPLAY_NAME",
  "machineSpec": {
    "machineType": "e2-standard-4"
  },
  softwareConfig: {
    postStartupScriptConfig: {
      postStartupScriptUrl: "POST_STARTUP_SCRIPT_URI",
      postStartupScriptBehavior: "POST_STARTUP_SCRIPT_BEHAVIOR"
    },
  },
  "networkSpec": {
    "enableInternetAccess": true
  }
}

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates" | Select-Object -Expand Content

如果成功，响应正文将包含一个 Operation 实例。

如需了解详情，请参阅 notebookRuntimeTemplates.create REST API 文档。

创建运行时

创建使用启动后脚本的运行时模板后，请基于该运行时模板创建运行时。运行时启动，并根据指定的行为运行启动后脚本。请参阅创建运行时。

创建包含启动后脚本和环境变量的运行时模板

如需创建使用启动后脚本和环境变量的运行时模板，您可以使用 Google Cloud 控制台、Google Cloud CLI 或 REST API。

控制台

如需创建使用启动后脚本和环境变量的运行时模板，请执行以下操作：

在 Google Cloud 控制台中，前往 Colab Enterprise 运行时模板页面。

进入运行时模板
点击 新建模板。

此时会显示创建新的运行时模板对话框。
在运行时基本信息部分中，输入显示名称。
在区域菜单中，选择需要运行时模板的区域。
在环境部分的启动后脚本字段中，点击浏览，然后前往 Cloud Storage 中位于启动后脚本。如需了解详情，请参阅启动后脚本位置。
在“启动后脚本网址”下方，选择启动后脚本的行为。默认行为是运行一次。如需了解详情，请参阅启动后脚本行为。
如需添加环境变量，请点击 添加环境变量，然后输入键和值对。如需添加更多环境变量，请重复此步骤。
在网络和安全部分中，确保已选择启用最终用户凭据。
完成对话框的其余部分，然后点击创建。

您的运行时模板会显示在运行时模板标签页上的列表中。

gcloud

在使用下面的命令数据之前，请先进行以下替换：

DISPLAY_NAME：运行时模板的显示名称。
PROJECT_ID：您的项目 ID。
REGION：您希望运行时模板所在的区域。
POST_STARTUP_SCRIPT_URI：启动后脚本的 URI。如需了解详情，请参阅启动后脚本位置。
POST_STARTUP_SCRIPT_BEHAVIOR：启动后脚本的行为。请参阅启动后脚本行为。
ENV_VARIABLE_NAME：要为运行时设置的环境变量的名称。
ENV_VARIABLE_VALUE：要为运行时设置的环境变量的值。

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" \
    --project=PROJECT_ID \
    --region=REGION \
    --machine-type=e2-standard-4 \
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI \
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR \
    --set-env-vars=ENV_VARIABLE_NAME=ENV_VARIABLE_VALUE

Windows (PowerShell)

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" `
    --project=PROJECT_ID `
    --region=REGION `
    --machine-type=e2-standard-4 `
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI `
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR `
    --set-env-vars=ENV_VARIABLE_NAME=ENV_VARIABLE_VALUE

Windows (cmd.exe)

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" ^
    --project=PROJECT_ID ^
    --region=REGION ^
    --machine-type=e2-standard-4 ^
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI ^
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR ^
    --set-env-vars=ENV_VARIABLE_NAME=ENV_VARIABLE_VALUE

如需详细了解用于从命令行创建运行时模板的命令，请参阅 gcloud CLI 文档。

REST

在使用任何请求数据之前，请先进行以下替换：

REGION：您希望运行时模板所在的区域。
PROJECT_ID：您的项目 ID。
DISPLAY_NAME：运行时模板的显示名称。
POST_STARTUP_SCRIPT_URI：启动后脚本的 URI。如需了解详情，请参阅启动后脚本位置。
POST_STARTUP_SCRIPT_BEHAVIOR：启动后脚本的行为。请参阅启动后脚本行为。
ENV_VARIABLE_NAME：要为运行时设置的环境变量的名称。
ENV_VARIABLE_VALUE：要为运行时设置的环境变量的值。

HTTP 方法和网址：

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates

请求 JSON 正文：

{
  "displayName": "DISPLAY_NAME",
  "machineSpec": {
    "machineType": "e2-standard-4"
  },
  softwareConfig: {
    postStartupScriptConfig: {
      postStartupScriptUrl: "POST_STARTUP_SCRIPT_URI",
      postStartupScriptBehavior: "POST_STARTUP_SCRIPT_BEHAVIOR"
    },
    "env": [
      {
        "name": "ENV_VARIABLE_NAME",
        "value": "ENV_VARIABLE_VALUE"
      }
    ]
  },
  "networkSpec": {
    "enableInternetAccess": true
  }
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates" | Select-Object -Expand Content

如果成功，响应正文将包含一个 Operation 实例。

如需了解详情，请参阅 notebookRuntimeTemplates.create REST API 文档。

创建运行时

创建使用启动后脚本的运行时模板后，请基于该运行时模板创建运行时。运行时启动，并根据指定的行为运行启动后脚本。请参阅创建运行时。

限制

在 Colab Enterprise 中使用启动后脚本时，请考虑以下限制：

如需基于包含启动后脚本的运行时模板创建运行时，您必须是该运行时模板的所有者和创建者。
不支持通过启动后脚本传递环境变量。您必须按照本指南中的说明在软件配置中指定环境变量。
如需使用 Cloud Storage 中的启动后脚本，您必须使用启用了最终用户凭据的运行时，并且您的用户凭据必须有权访问 Cloud Storage 存储桶。
如果您使用 Google Cloud 控制台创建运行时模板，则启动后脚本必须位于 Cloud Storage 中。使用 Google Cloud 控制台创建运行时模板时，不支持其他位置的启动后脚本。
使用 Google Cloud 控制台创建运行时模板时，不支持为启动后脚本指定代号。

后续步骤

创建运行时并连接到该运行时。
如需管理运行时，请参阅管理运行时。
详细了解运行时和运行时模板。