Облачные функции Google на C#

1. Введение

Google Cloud Run Functions — это бессерверная вычислительная платформа, управляемая событиями. Cloud Run Functions позволяет писать код, не беспокоясь о выделении ресурсов или масштабировании для обработки меняющихся требований.

Существует два типа функций Cloud Run:

• HTTP-функции отвечают на HTTP-запросы.
• Функции обработки событий запускаются при возникновении таких событий, как публикация сообщения в Cloud Pub/Sub или загрузка файла в Cloud Storage .

В этом практическом занятии вы научитесь создавать собственные функции Cloud Run на языке C#. В частности, вы будете развертывать функции C#, обрабатывающие HTTP-запросы и события CloudEvent из различных источников Google Cloud.

Что вы узнаете

• Функциональная платформа для .NET.
• Как написать HTTP-функцию.
• Как написать функцию, запускаемую по событию, которая реагирует на события в облачном хранилище.
• Как написать функцию, запускаемую по событию, которая реагирует на события Cloud Pub/Sub.
• Как написать функцию, запускаемую по событию, которая реагирует на любой тип события.

2. Настройка и требования

Настройка среды для самостоятельного обучения

1. Войдите в консоль Google Cloud и создайте новый проект или используйте существующий. Если у вас еще нет учетной записи Gmail или Google Workspace, вам необходимо ее создать .

• Название проекта — это отображаемое имя участников данного проекта. Это строка символов, не используемая API Google. Вы можете изменить её в любое время.
• Идентификатор проекта должен быть уникальным для всех проектов Google Cloud и неизменяемым (его нельзя изменить после установки). Консоль Cloud автоматически генерирует уникальную строку; обычно вам неважно, какая она. В большинстве практических заданий вам потребуется указать идентификатор проекта (обычно он обозначается как PROJECT_ID ). Если сгенерированный идентификатор вас не устраивает, вы можете сгенерировать другой случайный идентификатор. В качестве альтернативы вы можете попробовать свой собственный и посмотреть, доступен ли он. После этого шага его нельзя изменить, и он останется неизменным на протяжении всего проекта.
• К вашему сведению, существует третье значение — номер проекта , который используется некоторыми API. Подробнее обо всех трех значениях можно узнать в документации .

Внимание: Идентификатор проекта должен быть уникальным во всем мире и не может быть использован кем-либо еще после того, как вы его выберете. Вы являетесь единственным пользователем этого идентификатора. Даже если проект будет удален, идентификатор больше никогда не будет использован.

Примечание: Если вы используете учетную запись Gmail, вы можете оставить значение по умолчанию « Без организации» . Если вы используете учетную запись Google Workspace, выберите местоположение, подходящее для вашей организации.

2. Далее вам потребуется включить оплату в консоли Cloud для использования ресурсов/API Cloud. Выполнение этого практического задания не должно стоить дорого, если вообще что-либо. Чтобы отключить ресурсы и избежать дополнительных расходов после завершения этого урока, вы можете удалить созданные ресурсы или удалить весь проект. Новые пользователи Google Cloud имеют право на бесплатную пробную версию стоимостью 300 долларов США .

Запустить Cloud Shell

Хотя Google Cloud можно управлять удаленно с ноутбука, в этом практическом занятии вы будете использовать Google Cloud Shell — среду командной строки, работающую в облаке.

В консоли Google Cloud нажмите на значок Cloud Shell на панели инструментов в правом верхнем углу:

Подготовка и подключение к среде займут всего несколько минут. После завершения вы должны увидеть что-то подобное:

Эта виртуальная машина содержит все необходимые инструменты разработки. Она предоставляет постоянный домашний каталог объемом 5 ГБ и работает в облаке Google, что значительно повышает производительность сети и аутентификацию. Вся работа в этом практическом задании может выполняться в браузере. Вам не нужно ничего устанавливать.

3. Прежде чем начать

Внутри Cloud Shell выполните следующую команду, чтобы включить необходимые службы:

gcloud services enable \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  cloudfunctions.googleapis.com \
  eventarc.googleapis.com \
  run.googleapis.com

Далее укажите свой регион.

REGION=<YOUR_REGION>

В рамках этого практического занятия вы создадите учетную запись службы с необходимыми разрешениями EventArc и ролью вызывающего пользователя Cloud Run, чтобы получать события из Cloud Storage и вызывать функцию Cloud Run.

Сначала создайте учетную запись службы.

PROJECT_ID=$(gcloud config get-value core/project)
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"

Далее предоставьте учетной записи службы, связанной с вашим триггером Eventarc, роль Eventarc Event Receiver (roles/eventarc.eventReceiver) в проекте, чтобы триггер мог получать события от поставщиков событий.

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

Затем предоставьте учетной записи службы роль вызывающего пользователя Cloud Run, чтобы она могла вызывать функцию.

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

4. Функциональная платформа для .NET

Functions Framework for .NET — это платформа с открытым исходным кодом FaaS (Function as a Service) для написания переносимых функций .NET, разработанная командой Google Cloud Functions.

Фреймворк Functions позволяет писать легковесные функции, работающие в самых разных средах, включая:

• Функции Google Cloud Run
• Ваша локальная машина разработки
• Cloud Run и Cloud Run на GKE
• Среды, основанные на Knative

В этом практическом занятии вы будете использовать Functions Framework для .NET и его шаблоны для создания и развертывания облачных функций на C#.

Внутри Cloud Shell выполните следующую команду для установки шаблонов Cloud Functions для dotnet :

dotnet new install Google.Cloud.Functions.Templates

Эта команда устанавливает 3 шаблона для dotnet . Каждый шаблон доступен на C#, F# и VB (но в этой лабораторной работе вы будете использовать только C#). Вы можете убедиться в установке шаблонов, выполнив команду:

dotnet new list

Templates                                                 Short Name            
-----------------------------------------------------------------------
Google Cloud Functions CloudEvent Function                gcf-event
Google Cloud Functions CloudEvent Function (Untyped)      gcf-untyped-event
Google Cloud Functions HttpFunction                       gcf-http

5. Функция HTTP

Вам предстоит создать и развернуть HTTP-функцию, обрабатывающую HTTP-запросы.

Создайте HTTP-функцию, используя шаблон gcf-http :

mkdir HelloHttp
cd HelloHttp
dotnet new gcf-http

Это создаст проект и файл Function.cs , обрабатывающие HTTP-запросы.

В файле .csproj измените целевую платформу на net8.0 :

<TargetFramework>net8.0</TargetFramework>

Чтобы развернуть функцию Cloud Run непосредственно в Cloud Run, выполните следующую команду:

gcloud beta run deploy hello-http-function \
    --source . \
    --function HelloHttp.Function \
    --base-image dotnet8 \
    --region $REGION \
    --allow-unauthenticated

Если вы предпочитаете развертывание в качестве Cloud Functions 2-го поколения, используйте следующую команду:

gcloud functions deploy hello-http-function \
    --allow-unauthenticated \
    --entry-point HelloHttp.Function \
    --gen2 \
    --region $REGION \
    --runtime dotnet8 \
    --trigger-http

После развертывания вашей функции вы можете вызвать ее с помощью следующей команды curl:

SERVICE_URL=$(gcloud run services describe hello-http-function --platform managed --region $REGION --format 'value(status.url)')

curl $SERVICE_URL

6. Функция CloudEvent - GCS

Вам предстоит создать и развернуть функцию CloudEvent, которая будет реагировать на события Google Cloud Storage (GCS).

Сначала создайте сегмент облачного хранилища. Именно из этого сегмента вы будете получать события в дальнейшем:

BUCKET_NAME="cloud-functions-bucket-${PROJECT_ID}"
gsutil mb -l us-central1 gs://${BUCKET_NAME}

Создайте функцию CloudEvent, используя шаблон gcf-event :

cd ..
mkdir HelloGcs
cd HelloGcs
dotnet new gcf-event

Это создаёт проект и файл Function.cs , обрабатывающие запросы CloudEvent . Также он преобразует данные CloudEvent в StorageObjectData .

В файле .csproj измените целевую платформу на net8.0 :

<TargetFramework>net8.0</TargetFramework>

Чтобы развернуть функцию Cloud Run непосредственно в Cloud Run, сначала необходимо развернуть функцию, а затем создать для нее триггер.

gcloud beta run deploy hello-gcs-function \
      --source . \
      --function HelloGcs.Function \
      --region $REGION \
      --base-image dotnet8 \
      --no-allow-unauthenticated

Теперь создайте триггер для функции запуска облака.

BUCKET_REGION=$REGION

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

Если вы предпочитаете развертывать функцию как Cloud Functions 2-го поколения, вы можете использовать следующую команду для развертывания функции с флагами trigger-event и trigger-resource :

gcloud functions deploy hello-gcs-function \
    --allow-unauthenticated \
    --entry-point HelloGcs.Function \
    --gen2 \
    --region $REGION \
    --runtime dotnet8 \
    --trigger-event google.storage.object.finalize \
    --trigger-resource ${BUCKET_NAME} \
    --service-account=$SERVICE_ACCOUNT_ADDRESS

Через пару минут функция должна отобразиться в Cloud Console:

Для запуска функции загрузите файл в хранилище:

echo "Hello from Storage" > random.txt
gsutil cp random.txt gs://${BUCKET_NAME}

Убедитесь, что функция была запущена, прочитав логи:

Для запуска функции Cloud Run можно выполнить следующую команду:

gcloud logging read "resource.labels.service_name=hello-gcs-function AND textPayload: Name" --format=json

Для функции второго поколения можно выполнить следующую команду:

gcloud functions logs read hello-gcs-function \
    --gen2 \
    --region us-central1

7. Функция CloudEvent - публикация/подписка

Вам предстоит создать и развернуть функцию CloudEvent, которая будет реагировать на события Cloud Pub/Sub.

Сначала создайте тему Cloud Pub/Sub, которая будет генерировать события:

TOPIC_NAME=cloud-functions-topic
gcloud pubsub topics create ${TOPIC_NAME}

Создайте функцию CloudEvent, используя шаблон gcf-event :

cd ..
mkdir HelloPubSub
cd HelloPubSub
dotnet new gcf-event

Это создаёт проект и файл Function.cs , обрабатывающие запросы CloudEvent . По умолчанию данные CloudEvent также преобразуются в StorageObjectData .

В файле .csproj измените целевую платформу на net8.0 :

<TargetFramework>net8.0</TargetFramework>

Измените StorageObjectData на MessagePublishedData для анализа сообщений Pub/Sub. Измените Google.Events.Protobuf.Cloud.Storage.V1 на Google.Events.Protobuf.Cloud.PubSub.V1 .

В итоге ваша функция должна выглядеть следующим образом:

using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Events.Protobuf.Cloud.PubSub.V1;
using System;
using System.Threading;
using System.Threading.Tasks;

namespace HelloPubSub;

public class Function : ICloudEventFunction<MessagePublishedData>
{
    public Task HandleAsync(CloudEvent cloudEvent, MessagePublishedData data, CancellationToken cancellationToken)
    {
        var nameFromMessage = data.Message?.TextData;
        var name = string.IsNullOrEmpty(nameFromMessage) ? "world" : nameFromMessage;
        Console.WriteLine($"Hello {name}");
        return Task.CompletedTask;
    }
}

Чтобы развернуть функцию Cloud Run непосредственно в Cloud Run, сначала необходимо развернуть функцию, а затем создать для нее триггер.

gcloud beta run deploy hello-pubsub-function \
      --source . \
      --function HelloPubSub.Function \
      --region $REGION \
      --base-image dotnet8 \
      --no-allow-unauthenticated \
      --service-account=$SERVICE_ACCOUNT_ADDRESS

Теперь создайте триггер для функции Cloud Run.

gcloud eventarc triggers create my-pubsub-trigger \
    --location=$REGION \
    --service-account=$SERVICE_ACCOUNT_ADDRESS \
    --destination-run-service=hello-pubsub-function \
    --destination-run-region=$REGION \
    --destination-run-path="/" \
    --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
    --transport-topic=projects/$PROJECT_ID/topics/$TOPIC_NAME

Если вы предпочитаете развертывать функцию как Cloud Functions 2-го поколения, вы можете использовать следующую команду для развертывания функции с флагом trigger-topic :

gcloud functions deploy hello-pubsub-function \
    --allow-unauthenticated \
    --entry-point HelloPubSub.Function \
    --gen2 \
    --region us-central1 \
    --runtime dotnet8 \
    --trigger-topic ${TOPIC_NAME}

Через пару минут функция должна отобразиться в Cloud Console:

Для запуска функции опубликуйте сообщение в указанную тему:

gcloud pubsub topics publish ${TOPIC_NAME} --message="World"

Убедитесь, что функция была запущена, прочитав логи.

Для запуска функции Cloud Run можно выполнить следующую команду:

gcloud logging read "resource.labels.service_name=hello-pubsub-function AND textPayload: World" --format=json

Для функции второго поколения можно выполнить следующую команду:

gcloud functions logs read hello-pubsub-function \
    --gen2 \
    --region us-central1

8. Функция CloudEvent — нетипизированная

Если вы экспериментируете с CloudEvents и у вас еще нет модели данных полезной нагрузки, которую вы хотели бы использовать, или вы хотите, чтобы ваша функция могла обрабатывать любые события CloudEvent, вы можете использовать нетипизированную функцию CloudEvent.

Создайте функцию CloudEvent, используя шаблон gcf-untyped-event :

cd ..
mkdir HelloUntyped
cd HelloUntyped
dotnet new gcf-untyped-event

Это создаёт проект и файл Function.cs , отвечающие на запросы CloudEvent без каких-либо попыток анализа данных CloudEvent .

В файле .csproj измените целевую платформу на net8.0 :

<TargetFramework>net8.0</TargetFramework>

Чтобы развернуть функцию Cloud Run непосредственно в Cloud Run, сначала необходимо развернуть функцию, а затем создать для нее триггер.

gcloud beta run deploy hello-untyped-function \
      --source . \
      --function HelloUntyped.Function \
      --region $REGION \
      --base-image dotnet8 \
      --no-allow-unauthenticated

Теперь создайте триггер для функции запуска облака.

BUCKET_REGION=$REGION

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

Если вы предпочитаете развертывать функцию как Cloud Functions 2-го поколения, вы можете использовать следующую команду для развертывания функции с флагами trigger-event и trigger-resource :

gcloud functions deploy hello-untyped-function \
    --allow-unauthenticated \
    --entry-point HelloUntyped.Function \
    --gen2 \
    --region us-central1 \
    --runtime dotnet8 \
    --trigger-event google.storage.object.finalize \
    --trigger-resource ${BUCKET_NAME}

Эта функция будет срабатывать при загрузке файла в хранилище.

Через пару минут функция должна отобразиться в Cloud Console:

Для запуска функции загрузите файл в хранилище:

echo "Hello from Storage" > random.txt
gsutil cp random.txt gs://${BUCKET_NAME}

Убедитесь, что функция была запущена, прочитав логи.

Для запуска функции Cloud Run можно выполнить следующую команду:

gcloud logging read "resource.labels.service_name=hello-gcs-function AND textPayload: Name" --format=json

Для функции второго поколения можно выполнить следующую команду:

gcloud functions logs read hello-untyped-function \
    --gen2 \
    --region us-central1

9. Поздравляем!

Поздравляем с завершением практического занятия!

Что мы рассмотрели

• Функциональная платформа для .NET.
• Как написать HTTP-функцию для облачных вычислений.
• Как написать функцию CloudEvent, реагирующую на события Cloud Storage.
• Как написать функцию CloudEvent, реагирующую на события Cloud Pub/Sub.
• Как написать функцию CloudEvent, реагирующую на события любого типа.