1. Wprowadzenie
Funkcje Cloud Run to bezserwerowa platforma obliczeniowa oparta na zdarzeniach. Funkcje Cloud Run umożliwiają pisanie kodu bez martwienia się o udostępnianie zasobów czy skalowanie w celu obsługi zmieniających się wymagań.
Istnieją 2 rodzaje funkcji Cloud Run:
- Funkcje HTTP odpowiadają na żądania HTTP.
- Funkcje zdarzeń są aktywowane przez zdarzenia, takie jak opublikowanie wiadomości w Cloud Pub/Sub lub przesłanie pliku do Cloud Storage.
W tym samouczku dowiesz się, jak tworzyć własne funkcje Cloud Run w języku C#. Dokładniej rzecz ujmując, wdrożysz funkcje w C# reagujące na HTTP i CloudEvents z różnych źródeł Google Cloud.
Czego się nauczysz
- Platforma funkcji dla .NET.
- Jak napisać funkcję HTTP.
- Jak napisać funkcję wywoływaną przez zdarzenia, która reaguje na zdarzenia Cloud Storage.
- Jak napisać funkcję wyzwalaną przez zdarzenia, która reaguje na zdarzenia Cloud Pub/Sub.
- Jak napisać funkcję wywoływaną przez zdarzenie, która reaguje na dowolny typ zdarzenia.
2. Konfiguracja i wymagania
Samodzielne konfigurowanie środowiska
- Zaloguj się w konsoli Google Cloud i utwórz nowy projekt lub użyj istniejącego. Jeśli nie masz jeszcze konta Gmail ani Google Workspace, musisz je utworzyć.
- Nazwa projektu to wyświetlana nazwa uczestników tego projektu. Jest to ciąg znaków, który nie jest używany przez interfejsy API Google. Możesz ją zaktualizować w dowolnym momencie.
- Identyfikator projektu musi być unikalny we wszystkich projektach Google Cloud i jest niezmienny (nie można go zmienić po ustawieniu). Konsola Cloud automatycznie generuje unikalny ciąg znaków. Zwykle nie musisz się nim przejmować. W większości ćwiczeń z programowania musisz odwoływać się do identyfikatora projektu (zwykle jest on oznaczony jako
PROJECT_ID). Jeśli wygenerowany identyfikator Ci się nie podoba, możesz wygenerować inny losowy identyfikator. Możesz też spróbować własnej nazwy i sprawdzić, czy jest dostępna. Po tym kroku nie można go zmienić i będzie obowiązywać przez cały czas trwania projektu. - Warto wiedzieć, że istnieje też trzecia wartość, czyli numer projektu, z której korzystają niektóre interfejsy API. Więcej informacji o tych 3 wartościach znajdziesz w dokumentacji.
- Następnie musisz włączyć płatności w konsoli Cloud, aby korzystać z zasobów i interfejsów API Google Cloud. Ukończenie tego laboratorium nie powinno wiązać się z dużymi kosztami, a nawet z żadnymi. Aby wyłączyć zasoby i uniknąć naliczania opłat po zakończeniu tego samouczka, możesz usunąć utworzone zasoby lub cały projekt. Nowi użytkownicy Google Cloud mogą skorzystać z bezpłatnego okresu próbnego, w którym mają do dyspozycji środki w wysokości 300 USD.
Uruchamianie Cloud Shell
Z Google Cloud można korzystać zdalnie na laptopie, ale w tym module praktycznym będziesz używać Google Cloud Shell, czyli środowiska wiersza poleceń działającego w chmurze.
W konsoli Google Cloud kliknij ikonę Cloud Shell na pasku narzędzi w prawym górnym rogu:
Uzyskanie dostępu do środowiska i połączenie się z nim powinno zająć tylko kilka chwil. Po zakończeniu powinno wyświetlić się coś takiego:
Ta maszyna wirtualna zawiera wszystkie potrzebne narzędzia dla programistów. Zawiera również stały katalog domowy o pojemności 5 GB i działa w Google Cloud, co znacznie zwiększa wydajność sieci i usprawnia proces uwierzytelniania. Wszystkie zadania w tym laboratorium możesz wykonać w przeglądarce. Nie musisz niczego instalować.
3. Zanim zaczniesz
W Cloud Shell uruchom to polecenie, aby włączyć wymagane usługi:
gcloud services enable \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ cloudfunctions.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com
Następnie ustaw region.
REGION=<YOUR_REGION>
W tym samouczku utworzysz konto usługi z wymaganymi uprawnieniami EventArc i rolą wywołującego Cloud Run, aby otrzymywać zdarzenia z Cloud Storage i wywoływać funkcję Cloud Run.
Najpierw utwórz konto usługi.
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"
Następnie przyznaj w projekcie rolę Odbiorca zdarzeń Eventarc (roles/eventarc.eventReceiver) kontu usługi powiązanemu z aktywatorem Eventarc, aby aktywator mógł odbierać zdarzenia od dostawców zdarzeń.
gcloud projects add-iam-policy-binding $PROJECT_ID \ --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \ --role=roles/eventarc.eventReceiver
Następnie przypisz do konta usługi rolę wywołującego Cloud Run, aby mogło wywoływać funkcję.
gcloud projects add-iam-policy-binding $PROJECT_ID \ --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \ --role=roles/run.invoker
4. Platforma funkcji dla .NET
Functions Framework for .NET to platforma FaaS (funkcje jako usługa) typu open source, która umożliwia pisanie przenośnych funkcji .NET. Została stworzona przez zespół Google Cloud Functions.
Functions Framework umożliwia pisanie lekkich funkcji, które działają w wielu różnych środowiskach, w tym:
- Funkcje Google Cloud Run
- lokalny komputer używany do programowania
- Cloud Run i Cloud Run w GKE
- Środowiska oparte na Knative
W tym module dowiesz się, jak za pomocą Functions Framework for .NET i jego szablonów tworzyć i wdrażać funkcje Cloud Functions w języku C#.
W Cloud Shell uruchom to polecenie, aby zainstalować szablony Cloud Functions dla dotnet:
dotnet new install Google.Cloud.Functions.Templates
Spowoduje to zainstalowanie 3 szablonów dla dotnet. Każdy szablon jest dostępny w językach C#, F# i VB (ale w tym module użyjesz tylko języka C#). Aby sprawdzić, czy szablony są zainstalowane, uruchom to polecenie:
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. Funkcja HTTP
Utworzysz i wdrożysz funkcję HTTP, która będzie odpowiadać na żądania HTTP.
Utwórz funkcję HTTP za pomocą szablonu gcf-http:
mkdir HelloHttp cd HelloHttp dotnet new gcf-http
Spowoduje to utworzenie projektu i pliku Function.cs odpowiadającego na żądania HTTP.
Zmień platformę docelową na net8.0 w pliku .csproj:
<TargetFramework>net8.0</TargetFramework>
Aby wdrożyć funkcję Cloud Run bezpośrednio w Cloud Run, uruchom to polecenie:
gcloud beta run deploy hello-http-function \
--source . \
--function HelloHttp.Function \
--base-image dotnet8 \
--region $REGION \
--allow-unauthenticated
Jeśli wolisz wdrożyć funkcję jako Cloud Functions 2 generacji, użyj tego polecenia:
gcloud functions deploy hello-http-function \
--allow-unauthenticated \
--entry-point HelloHttp.Function \
--gen2 \
--region $REGION \
--runtime dotnet8 \
--trigger-http
Po wdrożeniu funkcji możesz ją wywołać za pomocą tego polecenia curl:
SERVICE_URL=$(gcloud run services describe hello-http-function --platform managed --region $REGION --format 'value(status.url)') curl $SERVICE_URL
6. Funkcja CloudEvent – GCS
Utworzysz i wdrożysz funkcję CloudEvent, która będzie reagować na zdarzenia Google Cloud Storage (GCS).
Najpierw utwórz zasobnik Cloud Storage. To jest zasobnik, z którego będziesz później nasłuchiwać zdarzeń:
BUCKET_NAME="cloud-functions-bucket-${PROJECT_ID}"
gsutil mb -l us-central1 gs://${BUCKET_NAME}
Utwórz funkcję CloudEvent za pomocą szablonu gcf-event:
cd .. mkdir HelloGcs cd HelloGcs dotnet new gcf-event
Spowoduje to utworzenie projektu i pliku Function.cs odpowiadającego na żądania CloudEvent. Analizuje też dane z usługi CloudEvent i przekształca je w dane StorageObjectData.
Zmień platformę docelową na net8.0 w pliku .csproj:
<TargetFramework>net8.0</TargetFramework>
Aby wdrożyć funkcję Cloud Run bezpośrednio w Cloud Run, najpierw wdróż funkcję, a potem utwórz dla niej wyzwalacz.
gcloud beta run deploy hello-gcs-function \
--source . \
--function HelloGcs.Function \
--region $REGION \
--base-image dotnet8 \
--no-allow-unauthenticated
Teraz utwórz aktywator funkcji Cloud Run.
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
Jeśli wolisz wdrożyć funkcję jako Cloud Functions 2 generacji, możesz użyć tego polecenia, aby wdrożyć funkcję za pomocą flag trigger-event i 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
Po kilku minutach funkcja powinna być widoczna w konsoli Google Cloud:
Uruchom funkcję, przesyłając plik do zasobnika na dane:
echo "Hello from Storage" > random.txt
gsutil cp random.txt gs://${BUCKET_NAME}
Sprawdź, czy funkcja została wywołana, czytając logi:
W przypadku funkcji Cloud Run możesz uruchomić to polecenie:
gcloud logging read "resource.labels.service_name=hello-gcs-function AND textPayload: Name" --format=json
W przypadku funkcji 2 generacji możesz uruchomić to polecenie:
gcloud functions logs read hello-gcs-function \
--gen2 \
--region us-central1
7. Funkcja CloudEvent – Pub/Sub
Utworzysz i wdrożysz funkcję CloudEvent, która będzie reagować na zdarzenia Cloud Pub/Sub.
Najpierw utwórz temat Cloud Pub/Sub, który będzie emitować zdarzenia:
TOPIC_NAME=cloud-functions-topic
gcloud pubsub topics create ${TOPIC_NAME}
Utwórz funkcję CloudEvent za pomocą szablonu gcf-event:
cd .. mkdir HelloPubSub cd HelloPubSub dotnet new gcf-event
Spowoduje to utworzenie projektu i pliku Function.cs odpowiadającego na żądania CloudEvent. Domyślnie analizuje też dane z usługi CloudEvent i przekształca je w dane StorageObjectData.
Zmień platformę docelową na net8.0 w pliku .csproj:
<TargetFramework>net8.0</TargetFramework>
Zmień StorageObjectData na MessagePublishedData, aby analizować wiadomości Pub/Sub. Zmień Google.Events.Protobuf.Cloud.Storage.V1 na Google.Events.Protobuf.Cloud.PubSub.V1.
Funkcja powinna wyglądać tak:
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;
}
}
Aby wdrożyć funkcję Cloud Run bezpośrednio w Cloud Run, najpierw wdróż funkcję, a potem utwórz dla niej wyzwalacz.
gcloud beta run deploy hello-pubsub-function \
--source . \
--function HelloPubSub.Function \
--region $REGION \
--base-image dotnet8 \
--no-allow-unauthenticated \
--service-account=$SERVICE_ACCOUNT_ADDRESS
Teraz utwórz wyzwalacz funkcji 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
Jeśli wolisz wdrożyć funkcję jako Cloud Functions 2 generacji, możesz użyć tego polecenia, aby wdrożyć funkcję za pomocą flagi trigger-topic:
gcloud functions deploy hello-pubsub-function \
--allow-unauthenticated \
--entry-point HelloPubSub.Function \
--gen2 \
--region us-central1 \
--runtime dotnet8 \
--trigger-topic ${TOPIC_NAME}
Po kilku minutach funkcja powinna być widoczna w konsoli Google Cloud:
Aktywuj funkcję, publikując wiadomość w temacie:
gcloud pubsub topics publish ${TOPIC_NAME} --message="World"
Sprawdź, czy funkcja została wywołana, czytając logi.
W przypadku funkcji Cloud Run możesz uruchomić to polecenie:
gcloud logging read "resource.labels.service_name=hello-pubsub-function AND textPayload: World" --format=json
W przypadku funkcji 2 generacji możesz uruchomić to polecenie:
gcloud functions logs read hello-pubsub-function \
--gen2 \
--region us-central1
8. Funkcja CloudEvent – bez typu
Jeśli eksperymentujesz z CloudEvents i nie masz jeszcze modelu danych ładunku, który chcesz zastosować, lub chcesz, aby Twoja funkcja mogła obsługiwać dowolne zdarzenie CloudEvent, możesz użyć funkcji CloudEvent bez typu.
Utwórz funkcję CloudEvent za pomocą szablonu gcf-untyped-event:
cd .. mkdir HelloUntyped cd HelloUntyped dotnet new gcf-untyped-event
Spowoduje to utworzenie projektu i pliku Function.cs, który odpowiada na żądania CloudEvent bez próby przeanalizowania danych CloudEvent.
Zmień platformę docelową na net8.0 w pliku .csproj:
<TargetFramework>net8.0</TargetFramework>
Aby wdrożyć funkcję Cloud Run bezpośrednio w Cloud Run, najpierw wdróż funkcję, a potem utwórz dla niej wyzwalacz.
gcloud beta run deploy hello-untyped-function \
--source . \
--function HelloUntyped.Function \
--region $REGION \
--base-image dotnet8 \
--no-allow-unauthenticated
Teraz utwórz aktywator funkcji Cloud Run.
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
Jeśli wolisz wdrożyć funkcję jako Cloud Functions 2 generacji, możesz użyć tego polecenia, aby wdrożyć funkcję za pomocą flag trigger-event i 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}
Funkcja zostanie uruchomiona, gdy plik zostanie przesłany do zasobnika na dane.
Po kilku minutach funkcja powinna być widoczna w konsoli Google Cloud:
Uruchom funkcję, przesyłając plik do zasobnika na dane:
echo "Hello from Storage" > random.txt
gsutil cp random.txt gs://${BUCKET_NAME}
Sprawdź, czy funkcja została wywołana, czytając logi.
W przypadku funkcji Cloud Run możesz uruchomić to polecenie:
gcloud logging read "resource.labels.service_name=hello-gcs-function AND textPayload: Name" --format=json
W przypadku funkcji 2 generacji możesz uruchomić to polecenie:
gcloud functions logs read hello-untyped-function \
--gen2 \
--region us-central1
9. Gratulacje!
Gratulujemy ukończenia ćwiczenia.
Omówione zagadnienia
- Platforma funkcji dla .NET.
- Jak napisać funkcję HTTP w Cloud Functions.
- Jak napisać funkcję CloudEvent, która reaguje na zdarzenia Cloud Storage.
- Jak napisać funkcję CloudEvent odpowiadającą na zdarzenia Cloud Pub/Sub.
- Jak napisać funkcję CloudEvent, która reaguje na dowolny typ zdarzenia.