Início rápido: implemente uma função do Cloud Run com a CLI gcloud

Início rápido: implemente uma função do Cloud Run com a CLI gcloud

Esta página mostra como implementar uma função HTTP do Cloud Run através da CLI gcloud.

Antes de começar

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.
Nota: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.
Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro, tem de iniciar sessão na CLI gcloud com a sua identidade federada.
Para inicializar a CLI gcloud, execute o seguinte comando:
gcloud init
Create or select a Google Cloud project.
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:
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.

Nota: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.

Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro, tem de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select a Google Cloud project.

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:

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. Para definir o projeto predefinido para o seu serviço do Cloud Run:

    gcloud config set project PROJECT_ID

   Substitua PROJECT_ID pelo nome do projeto que criou para este início rápido.

2. Se estiver ao abrigo de uma política da organização de restrição de domínio que restringe as invocações não autenticadas para o seu projeto, tem de aceder ao serviço implementado conforme descrito em Testar serviços privados.

3. Certifique-se de que tem a função Utilizador da conta de serviço concedida na identidade de serviço. Por predefinição, a identidade do serviço é a conta de serviço predefinida do Compute Engine.

   Conceda as funções

   Para conceder acesso ao recurso de identidade do serviço, use o comando gcloud iam service-accounts add-iam-policy-binding, substituindo as variáveis realçadas pelos valores adequados:

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

   Substitua o seguinte:

   • SERVICE_ACCOUNT_EMAIL: o endereço de email da conta de serviço que está a usar como identidade de serviço, como:
     • A conta de serviço predefinida do Compute Engine: [e-mail]
     • Uma conta de serviço que criou: SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
   • PRINCIPAL: o identificador do utilizador. Normalmente, este é o endereço de email de uma Conta Google.
4. Conceda à conta de serviço do Cloud Build a seguinte função do IAM.

   Clique para ver as funções necessárias para a conta de serviço do Cloud Build

   O Cloud Build usa automaticamente a conta de serviço predefinida do Compute Engine como a conta de serviço predefinida do Cloud Build para compilar o seu código-fonte e o recurso do Cloud Run, a menos que substitua este comportamento. Para que o Cloud Build compile as suas origens, peça ao administrador para conceder a função Cloud Run Builder (roles/run.builder) à conta de serviço predefinida do Compute Engine no seu projeto:

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

   Substitua PROJECT_NUMBER pelo seu Google Cloud número do projeto e PROJECT_ID pelo seu Google Cloud ID do projeto. Para ver instruções detalhadas sobre como encontrar o ID e o número do projeto, consulte o artigo Criar e gerir projetos.

   A concessão da função de criador do Cloud Run à conta de serviço predefinida do Compute Engine demora alguns minutos a propagar.

   Nota:

   A iam.automaticIamGrantsForDefaultServiceAccounts restrição da política da organização impede que a função de editor seja concedida automaticamente às contas de serviço predefinidas. Se tiver criado a sua organização após 3 de maio de 2024, esta restrição é aplicada por predefinição.

   Recomendamos vivamente que aplique esta restrição para desativar a concessão automática de funções. Se desativar a concessão automática de funções, tem de decidir que funções conceder às contas de serviço predefinidas e, em seguida, conceder estas funções manualmente.

   Se a conta de serviço predefinida já tiver a função de editor, recomendamos que substitua a função de editor por funções menos permissivas.Para modificar as funções da conta de serviço em segurança, use o Simulador de políticas para ver o impacto da alteração e, em seguida, conceda e revogue as funções adequadas.

Escreva a função de exemplo

Para escrever uma candidatura, siga estes passos:

Node.js

1. Crie um novo diretório com o nome helloworld e mude o diretório para este:

      mkdir helloworld
      cd helloworld
   

2. Crie um ficheiro package.json no diretório helloworld para especificar as dependências do 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. Crie um ficheiro index.js no diretório helloworld com o seguinte exemplo de Node.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. Crie um novo diretório com o nome helloworld e mude o diretório para este:

      mkdir helloworld
      cd helloworld
   

2. Crie um ficheiro requirements.txt no diretório helloworld para especificar as dependências do Python:

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

   Isto adiciona os pacotes necessários para a amostra.

3. Crie um ficheiro main.py no diretório helloworld com o seguinte exemplo de Python:

   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!"
   
   

Ir

1. Crie um novo diretório com o nome helloworld e mude o diretório para este:

      mkdir helloworld
      cd helloworld
   

2. Crie um ficheiro go.mod para declarar o módulo Go:

   module github.com/GoogleCloudPlatform/golang-samples/functions/functionsv2/helloworld
   
   go 1.23.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. Crie um ficheiro hello_http.go no diretório helloworld com o seguinte exemplo de código 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. Crie um novo diretório com o nome helloworld e mude o diretório para este:

      mkdir helloworld
      cd helloworld
   

2. Crie a seguinte estrutura de projeto para conter o diretório de origem e o ficheiro de origem:

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

3. Atualize o ficheiro HelloWorld.java com o seguinte exemplo de código 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. Crie um ficheiro pom.xml no diretório helloworld e adicione as seguintes dependências 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. Crie um novo diretório com o nome helloworld e mude o diretório para este:

      mkdir helloworld
      cd helloworld
   

2. Crie um ficheiro com o nome app.rb e cole o seguinte código no mesmo:

   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. Crie um ficheiro com o nome Gemfile e copie o seguinte para o mesmo:

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

4. Se não tiver o Bundler 2.0 ou superior instalado, instale o Bundler.

5. Gere um ficheiro Gemfile.lock executando o seguinte comando:

   bundle install
   

PHP

1. Crie um novo diretório com o nome helloworld e mude o diretório para este:

      mkdir helloworld
      cd helloworld
   

2. Crie um ficheiro com o nome index.php e cole o seguinte código no mesmo:

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

3. Se não estiver a usar o Cloud Shell, crie um ficheiro composer.json e cole o seguinte código no mesmo:

   {
       "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. Instale o SDK.NET.

2. Na consola, crie um novo projeto Web vazio com o comando dotnet.

   dotnet new web -o helloworld-csharp
   

3. Alterar diretório para helloworld-csharp:

4. Substitua o código de exemplo no ficheiro do projeto helloworld-csharp.csproj pelo seguinte:

   <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. Substitua o código de exemplo no ficheiro Program.cs pelo seguinte:

   
   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);
       }
   }

Implemente a função

Importante: este início rápido pressupõe que tem funções de proprietário ou editor no projeto que está a usar para o início rápido. Caso contrário, consulte a função de programador de origem do Cloud Run para ver as autorizações necessárias para implementar um recurso do Cloud Run a partir da origem.

Para implementar a função do Cloud Run, siga estes passos:

1. Implemente a função executando o seguinte comando no diretório que contém o exemplo de código:

   Node.js

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

   Substitua REGION pela Google Cloud região do serviço onde quer implementar a sua função. Por exemplo, europe-west1.

   Python

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

   Substitua REGION pela Google Cloud região do serviço onde quer implementar a sua função. Por exemplo, europe-west1.

   Ir

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

   Substitua REGION pela Google Cloud região do serviço onde quer implementar a sua função. Por exemplo, europe-west1.

   Java

   Execute o seguinte comando no diretório que contém o ficheiro pom.xml:

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

   Substitua REGION pela Google Cloud região do serviço onde quer implementar a sua função. Por exemplo, europe-west1.

   Ruby

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

   Substitua REGION pela Google Cloud região do serviço onde quer implementar a sua função. Por exemplo, europe-west1.

   PHP

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

   Substitua REGION pela Google Cloud região do serviço onde quer implementar a sua função. Por exemplo, europe-west1.

   .NET

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

   Substitua REGION pela Google Cloud região do serviço onde quer implementar a sua função. Por exemplo, europe-west1.

2. Quando a implementação estiver concluída, a CLI Google Cloud apresenta um URL onde o serviço está em execução. Abra o URL no navegador para ver o resultado da sua função.

   Êxito: implementou uma função HTTP do Cloud Run através da CLI gcloud.

Limpar

Embora o Cloud Run não cobre quando o serviço não está em utilização, ainda pode ser-lhe cobrado o armazenamento da imagem do contentor no Artifact Registry. Pode eliminar a imagem do contentor ou eliminar o Google Cloud projeto para evitar incorrer em custos. A eliminação do seu Google Cloud projeto interrompe a faturação de todos os recursos usados nesse projeto.

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

O que se segue?

• Para implementar uma função de exemplo no Cloud Run através da Google Cloud consola, consulte o Início rápido: implemente uma função no Cloud Run através da Google Cloud consola.

• Para implementar funções e criar acionadores através da Google Cloud consola e da CLI gcloud, consulte o artigo Implementar funções.

• Para ver e eliminar funções existentes, consulte o artigo Gerir revisões de serviços.

• Para criar contentores de funções na sua própria cadeia de ferramentas e implementá-los no Cloud Run, consulte o artigo Crie funções.

• Para criar acionadores com o Eventarc, consulte o artigo Crie acionadores com o Eventarc.