Guia de início rápido: implantar uma função do Cloud Run usando a CLI gcloud

Nesta página, mostramos como implantar uma função HTTP do Cloud Run usando a CLI gcloud.

Antes de começar

  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. Install the Google Cloud CLI.

  3. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  4. To initialize the gcloud CLI, run the following command: 

    gcloud init

  5. Create or select a Google Cloud 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.

  6. Make sure that billing is enabled for your Google Cloud project.

  7. 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

  8. 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/resourcemanager.projectIamAdmin, roles/iam.serviceAccountUser, roles/serviceusage.serviceUsageAdmin 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
    • Replace PROJECT_ID with your project ID.

    • Replace USER_IDENTIFIER with the identifier for your user account. For example, user:myemail@example.com.

    • Replace ROLE with each individual role.
    9.

  9. Install the Google Cloud CLI.

  10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init

  12. Create or select a Google Cloud 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.

  13. Make sure that billing is enabled for your Google Cloud project.

  14. 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

  15. 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/resourcemanager.projectIamAdmin, roles/iam.serviceAccountUser, roles/serviceusage.serviceUsageAdmin 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
    • Replace PROJECT_ID with your project ID.

    • Replace USER_IDENTIFIER with the identifier for your user account. For example, user:myemail@example.com.

    • Replace ROLE with each individual role.
    16.
  16. Para definir o projeto padrão do serviço do Cloud Run: 
     gcloud config set project PROJECT_ID
     Substitua PROJECT_ID pelo nome do projeto que você criou para este guia de início rápido.

  17. Se você precisa seguir uma política da organização de restrição de domínio que restringe invocações não autenticadas para seu projeto, será necessário acessar o serviço implantado, conforme descrito em Como testar serviços particulares.

  18. Conceda à conta de serviço do Cloud Build o seguinte papel do IAM.

    Clique para conferir os papéis necessários para a conta de serviço do Cloud Build

    O Cloud Build usa automaticamente a conta de serviço padrão do Compute Engine como a conta de serviço padrão do Cloud Build para criar seu código-fonte e recurso do Cloud Run, a menos que você substitua esse comportamento. Para que o Cloud Build crie suas origens, peça ao administrador para conceder o papel Criador do Cloud Run (roles/run.builder) à conta de serviço padrão do Compute Engine no seu projeto:

      gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
      --role=roles/run.builder

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

    A concessão do papel de builder do Cloud Run à conta de serviço padrão do Compute Engine leva alguns minutos para se propagar.

Escrever a função de exemplo

Para escrever um aplicativo, siga estas etapas:

Node.js

  1. Crie um novo diretório com o nome helloworld e altere o diretório nele:

       mkdir helloworld
   cd helloworld

  2. Crie um arquivo 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 arquivo 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 altere o diretório nele:

       mkdir helloworld
   cd helloworld

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

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

    Isso adiciona os pacotes necessários para a amostra.

  3. Crie um arquivo main.py no diretório helloworld com o seguinte exemplo em 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!"

Go

  1. Crie um novo diretório com o nome helloworld e altere o diretório nele:

       mkdir helloworld
   cd helloworld

  2. Crie um arquivo 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 arquivo hello_http.go no diretório helloworld com o exemplo de código Go a seguir:

    
// 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 altere o diretório nele:

       mkdir helloworld
   cd helloworld

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

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

  3. Atualize o arquivo 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 arquivo pom.xml no diretório helloworld e adicione as seguintes dependências do 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 altere o diretório nele:

       mkdir helloworld
   cd helloworld

  2. Crie um arquivo chamado app.rb e cole o seguinte código nele:

    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 arquivo chamado Gemfile e copie o seguinte arquivo nele:

    source "https://rubygems.org"

gem "base64", "~> 0.2"
gem "functions_framework", "~> 1.4"

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

  5. Gere um arquivo Gemfile.lock executando:

    bundle install

PHP

  1. Crie um novo diretório com o nome helloworld e altere o diretório nele:

       mkdir helloworld
   cd helloworld

  2. Crie um arquivo chamado index.php e cole o seguinte código nele:

    
use Psr\Http\Message\ServerRequestInterface;

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

  3. Se você não estiver usando o Cloud Shell, crie um arquivo composer.json e cole o seguinte código nele:

    {
    "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 do.NET.

  2. No console, crie um novo projeto da Web vazio usando o comando dotnet.

    dotnet new web -o helloworld-csharp

  3. Altere o diretório para helloworld-csharp:

  4. Substitua o exemplo de código no arquivo 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 exemplo de código no arquivo 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);
    }
}

Implantar a função

Importante: este guia de início rápido pressupõe que você tenha papéis de proprietário ou editor no projeto que está usando para este guia. Caso contrário, consulte o papel de desenvolvedor de origem do Cloud Run para ter acesso às permissões necessárias para implantar um recurso do Cloud Run a partir da origem.

Para implantar a função do Cloud Run, siga estas etapas:

  1. Implante a função executando o seguinte comando no diretório 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 em que você quer implantar a 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 em que você quer implantar a função. Por exemplo, europe-west1.

    Go

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

    Substitua REGION pela Google Cloud região do serviço em que você quer implantar a função. Por exemplo, europe-west1.

    Java

    Execute o seguinte comando no diretório que contém o arquivo 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 em que você quer implantar a 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 em que você quer implantar a 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 em que você quer implantar a 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 em que você quer implantar a função. Por exemplo, europe-west1.

  2. Quando a implantação for concluída, a CLI do Google Cloud vai mostrar um URL em que o serviço está em execução. Abra o URL em seu navegador para ver a saída da sua função.

Limpar

Ainda que o Cloud Run não gere custos quando o serviço não estiver em uso, é possível que receba cobranças pelo armazenamento da imagem do contêiner no Artifact Registry. É possível excluir sua imagem de contêiner ou excluir seu projeto do Google Cloud para evitar cobranças. A exclusão do projeto Google Cloud interrompe o faturamento de todos os recursos usados nele.

    Delete a Google Cloud project:

    gcloud projects delete PROJECT_ID

A seguir