快速入门：使用 gcloud CLI 部署 Cloud Run functions 函数

快速入门：使用 gcloud CLI 部署 Cloud Run functions 函数

本页介绍了如何使用 gcloud CLI 部署 HTTP Cloud Run functions 函数。

准备工作

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.
Install the Google Cloud CLI.
注意：如果您之前安装了 gcloud CLI，请确保通过运行 gcloud components update 来获得最新版本。
如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。
如需初始化 gcloud CLI，请运行以下命令：
gcloud init
Create or select 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.
• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.
Verify that billing is enabled for your Google Cloud project.
Enable the Artifact Registry, Cloud Build, Cloud Run Admin API, and Cloud Logging 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.
gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com run.googleapis.com logging.googleapis.com
Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/run.sourceDeveloper, roles/run.admin, roles/logging.viewer
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Replace the following:
• PROJECT_ID: Your project ID.
• USER_IDENTIFIER: The identifier for your user account. For example, [e-mail].
• ROLE: The IAM role that you grant to your user account.

Install the Google Cloud CLI.

注意：如果您之前安装了 gcloud CLI，请确保通过运行 gcloud components update 来获得最新版本。

如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

如需初始化 gcloud CLI，请运行以下命令：

gcloud init

Create or select 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.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry, Cloud Build, Cloud Run Admin API, and Cloud Logging 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.

gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com run.googleapis.com logging.googleapis.com

Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/run.sourceDeveloper, roles/run.admin, roles/logging.viewer

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

Replace the following:

• PROJECT_ID: Your project ID.
• USER_IDENTIFIER: The identifier for your user account. For example, [e-mail].
• ROLE: The IAM role that you grant to your user account.
1. 要为 Cloud Run 服务设置默认项目，请使用以下命令：

    gcloud config set project PROJECT_ID

   将 PROJECT_ID 替换为您为此快速入门创建的项目的名称。

2. 如果您通过网域限制组织政策来限制项目的未经身份验证的调用，则您需要按照测试专用服务中的说明访问已部署的服务。

3. 确保您已向服务身份授予 Service Account User 角色。默认情况下，服务身份是 Compute Engine 默认服务账号。

   授予角色

   如需授予服务身份资源的访问权限，请使用 gcloud iam service-accounts add-iam-policy-binding 命令，并将突出显示的变量替换为适当的值：

         gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
             --member=user:PRINCIPAL \
             --role=roles/iam.serviceAccountUser
         

   替换以下内容：

   • SERVICE_ACCOUNT_EMAIL：您用作服务身份的服务账号邮箱，例如：
     • Compute Engine 默认服务账号：[e-mail]
     • 您创建的服务账号：SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
   • PRINCIPAL：用户标识符。这通常是用于部署 Cloud Run 资源的 Google 账号邮箱。
4. 为 Cloud Build 服务账号授予以下 IAM 角色。

   点击可查看 Cloud Build 服务账号需要的角色

   除非您替换此行为，否则 Cloud Build 会自动使用 Compute Engine 默认服务账号作为默认 Cloud Build 服务账号来构建源代码和 Cloud Run 资源。为了让 Cloud Build 能够构建来源，请让管理员向项目的 Compute Engine 默认服务账号授予 Cloud Run Builder (roles/run.builder)：

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member=serviceAccount:[e-mail] \
         --role=roles/run.builder
     

   将 PROJECT_NUMBER 替换为您的 Google Cloud项目编号，将 PROJECT_ID 替换为您的 Google Cloud项目 ID。如需详细了解如何查找项目 ID 和项目编号，请参阅创建和管理项目。

   向 Compute Engine 默认服务账号授予 Cloud Run Builder 角色需要几分钟时间才能传播。

   注意：

   iam.automaticIamGrantsForDefaultServiceAccounts 组织政策限制条件可以防止将 Editor 角色自动授予默认服务账号。如果您的组织是在 2024 年 5 月 3 日之后创建的，则默认情况下会强制执行此限制条件。

   我们强烈建议您实施此限制条件，以停用自动角色授予功能。如果您停用自动角色授予功能，则必须决定向默认服务账号授予哪些角色，然后自行授予这些角色。

   如果默认服务账号已具有 Editor 角色，我们建议您将 Editor 角色替换为权限较少的角色。如需安全地修改服务账号的角色，请使用 Policy Simulator 查看更改的影响，然后授予和撤消相应的角色。

5. 查看 Cloud Run 价格或使用价格计算器估算费用。

编写示例函数

如需编写应用，请按照以下步骤操作：

Node.js

1. 创建名为 helloworld 的新目录，并转到此目录中：

      mkdir helloworld
      cd helloworld
   

2. 在 helloworld 目录中创建一个 package.json 文件以指定 Node.js 依赖项：

   {
     "name": "nodejs-docs-samples-functions-hello-world-get",
     "version": "0.0.1",
     "private": true,
     "license": "Apache-2.0",
     "author": "Google Inc.",
     "repository": {
       "type": "git",
       "url": "https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git"
     },
     "engines": {
       "node": ">=16.0.0"
     },
     "scripts": {
       "test": "c8 mocha -p -j 2 test/*.test.js --timeout=6000 --exit"
     },
     "dependencies": {
       "@google-cloud/functions-framework": "^3.1.0"
     },
     "devDependencies": {
       "c8": "^10.0.0",
       "gaxios": "^6.0.0",
       "mocha": "^10.0.0",
       "wait-port": "^1.0.4"
     }
   }
   

3. 使用以下 Node.js 示例在 helloworld 目录中创建一个 index.js 文件：

   const functions = require('@google-cloud/functions-framework');
   
   // Register an HTTP function with the Functions Framework that will be executed
   // when you make an HTTP request to the deployed function's endpoint.
   functions.http('helloGET', (req, res) => {
     res.send('Hello World!');
   });

Python

1. 创建名为 helloworld 的新目录，并转到此目录中：

      mkdir helloworld
      cd helloworld
   

2. 在 helloworld 目录中创建一个 requirements.txt 文件，以指定 Python 依赖项：

   functions-framework==3.9.2
   flask==3.0.3
   google-cloud-error-reporting==1.11.1
   MarkupSafe==2.1.3
   

   这会添加示例所需的软件包。

3. 使用以下 Python 示例在 helloworld 目录中创建一个 main.py 文件：

   import functions_framework
   
   @functions_framework.http
   def hello_get(request):
       """HTTP Cloud Function.
       Args:
           request (flask.Request): The request object.
           <https://flask.palletsprojects.com/en/1.1.x/api/#incoming-request-data>
       Returns:
           The response text, or any set of values that can be turned into a
           Response object using `make_response`
           <https://flask.palletsprojects.com/en/1.1.x/api/#flask.make_response>.
       Note:
           For more information on how Flask integrates with Cloud
           Functions, see the `Writing HTTP functions` page.
           <https://cloud.google.com/functions/docs/writing/http#http_frameworks>
       """
       return "Hello World!"
   
   

Go

1. 创建名为 helloworld 的新目录，并转到此目录中：

      mkdir helloworld
      cd helloworld
   

2. 创建 go.mod 文件以声明 go 模块：

   module github.com/GoogleCloudPlatform/golang-samples/functions/functionsv2/helloworld
   
   go 1.24.0
   
   require github.com/GoogleCloudPlatform/functions-framework-go v1.8.1
   
   require (
   	github.com/cloudevents/sdk-go/v2 v2.15.2 // indirect
   	github.com/google/go-cmp v0.6.0 // indirect
   	github.com/google/uuid v1.6.0 // indirect
   	github.com/json-iterator/go v1.1.12 // indirect
   	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
   	github.com/modern-go/reflect2 v1.0.2 // indirect
   	github.com/stretchr/testify v1.10.0 // indirect
   	go.uber.org/multierr v1.11.0 // indirect
   	go.uber.org/zap v1.27.0 // indirect
   	golang.org/x/time v0.9.0 // indirect
   )
   

3. 使用以下 Go 代码示例在 helloworld 目录中创建一个 hello_http.go 文件：

   
   // Package helloworld provides a set of Cloud Functions samples.
   package helloworld
   
   import (
   	"fmt"
   	"net/http"
   
   	"github.com/GoogleCloudPlatform/functions-framework-go/functions"
   )
   
   func init() {
   	functions.HTTP("HelloGet", helloGet)
   }
   
   // helloGet is an HTTP Cloud Function.
   func helloGet(w http.ResponseWriter, r *http.Request) {
   	fmt.Fprint(w, "Hello, World!")
   }
   

Java

1. 创建名为 helloworld 的新目录，并转到此目录中：

      mkdir helloworld
      cd helloworld
   

2. 创建以下项目结构以包含源目录和源文件：

   mkdir -p ~/helloworld/src/main/java/functions
   touch ~/helloworld/src/main/java/functions/HelloWorld.java
   

3. 使用以下 Java 代码示例更新 HelloWorld.java 文件：

   
   package functions;
   
   import com.google.cloud.functions.HttpFunction;
   import com.google.cloud.functions.HttpRequest;
   import com.google.cloud.functions.HttpResponse;
   import java.io.BufferedWriter;
   import java.io.IOException;
   
   public class HelloWorld implements HttpFunction {
     // Simple function to return "Hello World"
     @Override
     public void service(HttpRequest request, HttpResponse response)
         throws IOException {
       BufferedWriter writer = response.getWriter();
       writer.write("Hello World!");
     }
   }

4. 在 helloworld 目录中创建一个 pom.xml 文件，并添加以下 Java 依赖项：

   <?xml version="1.0" encoding="UTF-8"?>
   
   <!--
     Copyright 2020 Google LLC
   
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
     You may obtain a copy of the License at
   
     http://www.apache.org/licenses/LICENSE-2.0
   
     Unless required by applicable law or agreed to in writing, software
     distributed under the License is distributed on an "AS IS" BASIS,
     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     See the License for the specific language governing permissions and
     limitations under the License.
   -->
   
   <project xmlns="http://maven.apache.org/POM/4.0.0"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
   
     <groupId>com.example.functions</groupId>
     <artifactId>functions-hello-world</artifactId>
     <version>1.0.0-SNAPSHOT</version>
   
     <parent>
       <groupId>com.google.cloud.samples</groupId>
       <artifactId>shared-configuration</artifactId>
       <version>1.2.0</version>
     </parent>
   
     <dependencyManagement>
       <dependencies>
         <dependency>
           <artifactId>libraries-bom</artifactId>
           <groupId>com.google.cloud</groupId>
           <scope>import</scope>
           <type>pom</type>
           <version>26.32.0</version>
         </dependency>
       </dependencies>
     </dependencyManagement>
   
     <properties>
       <maven.compiler.target>11</maven.compiler.target>
       <maven.compiler.source>11</maven.compiler.source>
     </properties>
   
     <dependencies>
       <!-- Required for Function primitives -->
       <dependency>
         <groupId>com.google.cloud.functions</groupId>
         <artifactId>functions-framework-api</artifactId>
         <version>1.1.0</version>
         <scope>provided</scope>
       </dependency>
   
       <!-- The following dependencies are only required for testing -->
       <dependency>
         <groupId>com.google.truth</groupId>
         <artifactId>truth</artifactId>
         <version>1.4.0</version>
         <scope>test</scope>
       </dependency>
       <dependency>
         <groupId>com.google.guava</groupId>
         <artifactId>guava-testlib</artifactId>
         <scope>test</scope>
       </dependency>
       <dependency>
         <groupId>org.mockito</groupId>
         <artifactId>mockito-core</artifactId>
         <version>5.10.0</version>
         <scope>test</scope>
       </dependency>
     </dependencies>
   
     <build>
       <plugins>
         <plugin>
           <!--
             Google Cloud Functions Framework Maven plugin
   
             This plugin allows you to run Cloud Functions Java code
             locally. Use the following terminal command to run a
             given function locally:
   
             mvn function:run -Drun.functionTarget=your.package.yourFunction
           -->
           <groupId>com.google.cloud.functions</groupId>
           <artifactId>function-maven-plugin</artifactId>
           <version>0.11.0</version>
           <configuration>
             <functionTarget>functions.HelloWorld</functionTarget>
           </configuration>
         </plugin>
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-surefire-plugin</artifactId>
           <!-- version 3.0.0-M4 does not load JUnit5 correctly -->
           <!-- see https://issues.apache.org/jira/browse/SUREFIRE-1750 -->
           <version>3.2.5</version>
           <configuration>
             <includes>
               <include>**/*Test.java</include>
             </includes>
             <skipTests>${skipTests}</skipTests>
             <reportNameSuffix>sponge_log</reportNameSuffix>
             <trimStackTrace>false</trimStackTrace>
           </configuration>
         </plugin>
       </plugins>
     </build>
   </project>
   

Ruby

1. 创建名为 helloworld 的新目录，并转到此目录中：

      mkdir helloworld
      cd helloworld
   

2. 创建名为 app.rb 的文件，并将以下代码粘贴到其中：

   require "functions_framework"
   
   FunctionsFramework.http "hello_get" do |_request|
     # The request parameter is a Rack::Request object.
     # See https://www.rubydoc.info/gems/rack/Rack/Request
   
     # Return the response body as a string.
     # You can also return a Rack::Response object, a Rack response array, or
     # a hash which will be JSON-encoded into a response.
     "Hello World!"
   end

3. 创建名为 Gemfile 的文件，并将以下内容复制到其中：

   source "https://rubygems.org"
   
   gem "base64", "~> 0.2"
   gem "functions_framework", "~> 1.4"

4. 如果您未安装 Bundler 2.0 或更高版本，请安装 Bundler。

5. 通过运行以下命令生成 Gemfile.lock 文件：

   bundle install
   

PHP

1. 创建名为 helloworld 的新目录，并转到此目录中：

      mkdir helloworld
      cd helloworld
   

2. 创建名为 index.php 的文件，并将以下代码粘贴到其中：

   
   use Psr\Http\Message\ServerRequestInterface;
   
   function helloGet(ServerRequestInterface $request): string
   {
       return 'Hello, World!' . PHP_EOL;
   }
   

3. 如果您未使用 Cloud Shell，请创建一个 composer.json 文件，并将以下代码粘贴到其中：

   {
       "require": {
           "google/cloud-functions-framework": "^1.0"
       },
       "scripts": {
           "start": [
              "Composer\\Config::disableProcessTimeout",
              "FUNCTION_TARGET=helloGet php -S localhost:${PORT:-8080} vendor/google/cloud-functions-framework/router.php"
           ]
       }
   }
   

.NET

1. 安装 .NET SDK。

2. 在 Console 中，使用 dotnet 命令新建一个空 Web 项目。

   dotnet new web -o helloworld-csharp
   

3. 转到 helloworld-csharp 目录：

4. 将项目文件 helloworld-csharp.csproj 中的示例代码替换为以下代码：

   <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
       <OutputType>Exe</OutputType>
       <TargetFramework>net8.0</TargetFramework>
     </PropertyGroup>
   
     <ItemGroup>
       <PackageReference Include="Google.Cloud.Functions.Hosting" Version="3.0.1" />
     </ItemGroup>
   </Project>

5. 将 Program.cs 文件中的示例代码替换为以下代码：

   
   using Google.Cloud.Functions.Framework;
   using Microsoft.AspNetCore.Http;
   using System.Threading.Tasks;
   
   namespace HelloWorld;
   
   public class Function : IHttpFunction
   {
       public async Task HandleAsync(HttpContext context)
       {
           await context.Response.WriteAsync("Hello World!", context.RequestAborted);
       }
   }

部署该函数

重要提示：本快速入门假定您在快速入门中使用的项目中拥有所有者或编辑者角色。否则，请参阅 Cloud Run Source Developer 角色，了解从源代码部署 Cloud Run 资源所需的权限。

如需部署 Cloud Run 函数，请按以下步骤操作：

1. 在包含示例代码的目录中运行以下命令，以部署函数：

   Node.js

   gcloud run deploy nodejs-http-function \
         --source . \
         --function helloGET \
         --base-image nodejs22 \
         --region REGION \
         --allow-unauthenticated
   

   将 REGION 替换为您要在其中部署函数的服务的 Google Cloud区域。例如 europe-west1。

   Python

   gcloud run deploy python-http-function \
         --source . \
         --function hello_get \
         --base-image python313 \
         --region REGION \
         --allow-unauthenticated
   

   将 REGION 替换为您要在其中部署函数的服务的 Google Cloud区域。例如 europe-west1。

   Go

   gcloud run deploy go-http-function \
          --source . \
          --function HelloGet \
          --base-image go125 \
          --region REGION \
          --allow-unauthenticated
   

   将 REGION 替换为您要在其中部署函数的服务的 Google Cloud区域。例如 europe-west1。

   Java

   在包含 pom.xml 文件的目录中运行以下命令：

   gcloud run deploy java-http-function \
          --source . \
          --function functions.HelloWorld \
          --base-image java21 \
          --region REGION \
          --allow-unauthenticated
   

   将 REGION 替换为您要在其中部署函数的服务的 Google Cloud区域。例如 europe-west1。

   Ruby

   gcloud run deploy ruby-http-function \
          --source . \
          --function hello_get \
          --base-image ruby34 \
          --region REGION \
          --allow-unauthenticated
   

   将 REGION 替换为您要在其中部署函数的服务的 Google Cloud区域。例如 europe-west1。

   PHP

   gcloud run deploy php-http-function \
          --source . \
          --function helloGet \
          --base-image php84 \
          --region REGION \
          --allow-unauthenticated
   

   将 REGION 替换为您要在其中部署函数的服务的 Google Cloud区域。例如 europe-west1。

   .NET

   gcloud run deploy csharp-http-function \
         --source . \
         --function HelloWorld.Function \
         --base-image dotnet8 \
         --region REGION \
         --allow-unauthenticated
   

   将 REGION 替换为您要在其中部署函数的服务的 Google Cloud区域。例如 europe-west1。

2. 部署完成后，Google Cloud CLI 会显示一个运行服务的网址。在浏览器中打开该网址，查看函数的输出。

   成功： 您已使用 gcloud CLI 部署 HTTP Cloud Run functions 函数。

清理

为避免您的 Google Cloud 账号产生额外费用，请删除您在本快速入门中部署的所有资源。

删除仓库

当部署的服务未在使用时，Cloud Run 不会向您收取费用。不过，您可能仍需要支付将容器映像存储在 Artifact Registry 中而产生的相关费用。如需删除 Artifact Registry 仓库，请按照 Artifact Registry 文档中删除仓库的步骤操作。

删除服务

Cloud Run 服务在收到请求之前不会产生费用。如需删除 Cloud Run 服务，请按照以下步骤之一操作：

控制台

要删除服务，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 Cloud Run：

   转到 Cloud Run

2. 在服务列表中找到要删除的服务，然后点击该服务对应的复选框以将其选中。

3. 点击删除。这将删除服务的所有修订版本。

gcloud

如需删除服务，请运行以下命令：

gcloud run services delete SERVICE --region REGION

替换以下内容：

• SERVICE：服务的名称。
• REGION：服务的 Google Cloud 区域。

删除测试项目

删除 Google Cloud 项目后，系统即会停止对该项目中的所有资源计费。如需释放项目中的所有 Google Cloud 资源，请按照以下步骤操作：

注意：删除项目会产生以下影响：
• 项目中的所有内容都会被删除。如果您将现有项目用于本文档中的任务，则删除该项目后，还将删除您已在该项目中完成的任何其他工作。
• 自定义项目 ID 丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。要保留使用该项目 ID 的网址（例如 appspot.com 网址），请删除项目内的所选资源，而不是删除整个项目。

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

后续步骤

• 如需使用 Google Cloud 控制台将示例函数部署到 Cloud Run，请参阅快速入门：使用 Google Cloud 控制台将函数部署到 Cloud Run。

• 如需使用 Google Cloud 控制台和 Google Cloud CLI 部署函数和创建触发器，请参阅部署函数。

• 如需查看和删除现有函数，请参阅管理服务修订版本。

• 如需在您自己的工具链中构建函数容器并将其部署到 Cloud Run，请参阅构建函数。

• 如需使用 Eventarc 创建触发器，请参阅使用 Eventarc 创建触发器。