Esta página foi traduzida pela API Cloud Translation.

Introdução às funções do Cloud Run orientadas a eventos

1. Introdução

Visão geral

As funções do Cloud Run são uma nova maneira de implantar cargas de trabalho usando os paradigmas de eventos e a assinatura de função conhecidos do GCF. Em vez de usar nosso processo de build e configurações de implantação, as funções do Cloud Run oferecem controle direto sobre o serviço criado no Cloud Run.

Com as funções do Cloud Run, fornecemos a experiência do usuário simples da implantação de origem do Cloud Run, proporcionando aos desenvolvedores controle total sobre suas cargas de trabalho usando configurações do Cloud Run.

Nesta seção, você vai aprender a implantar uma função orientada a eventos no Node. Você vai implantar uma função que é acionada sempre que um objeto é finalizado em um bucket do Google Cloud Storage.

Este codelab usa exemplos de nodejs nos exemplos abaixo. No entanto, você pode usar os exemplos de código do Cloud Functions (2ª geração) na linguagem de sua preferência:

O que você vai aprender

Como implantar uma função do Cloud Run orientada por eventos que é acionada sempre que um objeto é enviado para um bucket do GCS
Como criar uma conta de serviço com papéis adequados para receber um evento do Cloud Storage e invocar a função do Cloud Run

2. Configurar variáveis de ambiente e ativar APIs

Atualizar a CLI gcloud

Este codelab requer uma versão recente da CLI gcloud instalada. Para atualizar a CLI, execute

gcloud components update

Ativar APIs

Antes de começar a usar este codelab, você precisa ativar várias APIs. Este codelab exige o uso das seguintes APIs. Para ativar essas APIs, execute o seguinte comando:

gcloud services enable run.googleapis.com \
    cloudbuild.googleapis.com \
    storage.googleapis.com \
    artifactregistry.googleapis.com

Configurar as variáveis de ambiente.

Você pode definir variáveis de ambiente que serão usadas neste codelab.

PROJECT_ID=<YOUR_PROJECT_ID>
REGION=<YOUR_REGION, e.g. us-central1>

gcloud config set project $PROJECT_ID
SERVICE_NAME=crf-event-codelab
BUCKET_NAME=$PROJECT_ID-$SERVICE_NAME
TRIGGER_NAME=$SERVICE_NAME-trigger

3. Criar um bucket do Storage e uma conta de serviço

Criar um bucket de armazenamento

Para criar um bucket do Cloud Storage, execute o seguinte comando:

gsutil mb -l us-central1 gs://$BUCKET_NAME

Criar uma conta de serviço

Neste exemplo, você vai criar uma conta de serviço com as permissões necessárias do Eventarc e o papel de invocador do Cloud Run para receber um evento do Cloud Storage e invocar a função do Cloud Run.

Primeiro, crie a conta de serviço.

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

SERVICE_ACCOUNT="cloud-run-functions"
SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com

gcloud iam service-accounts create $SERVICE_ACCOUNT \
  --display-name="Cloud Run functions Eventarc service account"

Em seguida, conceda o papel Receptor de eventos do Eventarc (roles/eventarc.eventReceiver) no projeto à conta de serviço associada ao gatilho do Eventarc para que ele possa receber eventos de provedores de eventos.

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role=roles/eventarc.eventReceiver

Em seguida, conceda à conta de serviço o papel de invocação do Cloud Run para que ela possa invocar a função.

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role=roles/run.invoker

4. Criar e implantar a função

Primeiro, crie um diretório para o código-fonte e entre nele.

mkdir ../$SERVICE_NAME && cd $_

Em seguida, crie um arquivo package.json com o seguinte conteúdo:

{
    "dependencies": {
        "@google-cloud/functions-framework": "^3.0.0"
    }
}

Em seguida, crie um arquivo index.js com o seguinte conteúdo:

const functions = require("@google-cloud/functions-framework");

// Register a CloudEvent callback with the Functions Framework that will
// be triggered by Cloud Storage.
functions.cloudEvent("helloGCS", (cloudEvent) => {
    console.log(`Event ID: ${cloudEvent.id}`);
    console.log(`Event Type: ${cloudEvent.type}`);

    const file = cloudEvent.data;
    console.log(`Bucket: ${file.bucket}`);
    console.log(`File: ${file.name}`);
    console.log(`Metageneration: ${file.metageneration}`);
    console.log(`Created: ${file.timeCreated}`);
    console.log(`Updated: ${file.updated}`);
});

Agora você pode implantar a função do Cloud Run executando o seguinte comando:

gcloud beta run deploy $SERVICE_NAME \
 --source . \
      --function helloGCS \
      --region $REGION \
      --no-allow-unauthenticated

Observações:

A flag –source é usada para informar ao Cloud Run que a função precisa ser criada em um serviço baseado em contêiner executável.
A flag –function (new) é usada para definir o ponto de entrada do novo serviço como a assinatura de função que você quer invocar.
(opcional) –no-allow-unauthenticated para impedir que a função seja invocável publicamente

Para conferir o novo serviço crf-nodejs-event, execute o seguinte comando:

gcloud beta run services describe $SERVICE_NAME

5. Criar o evento

Podemos criar um acionador do Eventarc para enviar mensagens para nossa função toda vez que um objeto for finalizado no Google Cloud Storage:

BUCKET_REGION=$REGION

gcloud eventarc triggers create $TRIGGER_NAME \
     --location=$REGION \
     --destination-run-service=crf-nodejs-event \
  --destination-run-region=$BUCKET_REGION \
     --event-filters="type=google.cloud.storage.object.v1.finalized" \
     --event-filters="bucket=$BUCKET_NAME" \
     --service-account=$SERVICE_ACCOUNT_ADDRESS

Observações:

gcs-function-trigger é o nome do acionador
crf-nodejs-event é o nome do serviço do Cloud Run em que a função é implantada.
para a flag –event-filters, não use o prefixo gs:// no nome do bucket.

Confira um tutorial detalhado sobre como configurar o serviço de gatilho do Cloud Storage usando o Eventarc na documentação do Cloud Run: https://cloud.google.com/run/docs/tutorials/eventarc

6. Testar a função

Quando a implantação for concluída, o URL do serviço vai aparecer. Para invocar a função, é necessário enviar uma solicitação autenticada com seu token de identidade ou o token de identidade de um principal que tenha o papel de Invocador do Cloud Run, conforme mostrado abaixo:

# get the Service URL
SERVICE_URL="$(gcloud run services describe crf-nodejs-event --region us-central1 --format 'value(status.url)')"

# invoke the service
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

Com a função implantada e um gatilho criado, agora podemos invocar a função.

Crie um arquivo e faça upload dele para o bucket do Cloud Storage. Para isso, use a interface da Web do Console do Google Cloud ou a ferramenta CLI gsutil.

echo "hello world" > test.txt
gsutil cp test gs://$BUCKET_NAME

Quando o arquivo for enviado, um evento será gerado e a função vai mostrar algumas informações básicas sobre o objeto, por exemplo, o nome do arquivo. Essa saída pode ser encontrada nas entradas de registro da função no console do Cloud. Como alternativa, você pode consultar essa saída usando a CLI gcloud:

gcloud logging read "resource.labels.service_name=crf-nodejs-event AND textPayload: File" --format=json

e você vai ver a saída a seguir

"textPayload": "File: test.txt"

7. Parabéns!

Parabéns por concluir o codelab.

Recomendamos a análise da documentação das Funções do Cloud Run.

O que vimos

Como implantar uma função do Cloud Run orientada por eventos que é acionada sempre que um objeto é enviado para um bucket do GCS
Como criar uma conta de serviço com papéis adequados para receber um evento do Cloud Storage e invocar a função do Cloud Run

8. Limpar

Para evitar cobranças acidentais (por exemplo, se esse serviço do Cloud Run for invocado acidentalmente mais vezes do que sua alocação mensal de invocação do Cloud Run no nível sem custo financeiro), exclua o serviço do Cloud Run ou o projeto criado na etapa 2.

Para excluir os serviços do Cloud Run, acesse o Console do Cloud Run em https://console.cloud.google.com/run/ e exclua o serviço crf-event-codelab que você criou neste codelab.

Se você quiser excluir o projeto inteiro, acesse https://console.cloud.google.com/cloud-resource-manager, selecione o projeto criado na etapa 2 e escolha "Excluir". Se você excluir o projeto, vai precisar mudar os projetos no Cloud SDK. Para conferir a lista de todos os projetos disponíveis, execute gcloud projects list.