Aktywowanie przetwarzania zdarzeń z Cloud Storage za pomocą funkcji Eventarc i Cloud Run

1. Omówienie

W tym praktycznym ćwiczeniu dowiesz się, jak używać zdarzeń zasobnika Cloud Storage i Eventarc do uruchamiania przetwarzania zdarzeń. Do analizowania danych i przetwarzania obrazów będziesz używać funkcji Cloud Run. Funkcja użyje interfejsu Vision API Google i zapisze wynikowy obraz z powrotem w zasobniku Cloud Storage.

Czego się nauczysz

Jak utworzyć przepływ przetwarzania obrazu.

• Konfigurowanie zasobników na dane
• Tworzenie funkcji Cloud Run do odczytu i zapisu obiektów w Cloud Storage
• Wdrażanie aktywatora Eventarc
• Integracja interfejsu Vision API w celu wykrywania obrazów z jedzeniem
• Testowanie i weryfikowanie kompleksowego rozwiązania

Wymagania wstępne

• Ten moduł zakłada, że znasz środowisko konsoli Cloud i powłoki.
• Znajomość funkcji Cloud Storage, Cloud Run lub Vision API może być przydatna, ale nie jest wymagana.

2. Konfiguracja i wymagania

Konfiguracja projektu Cloud

1. 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órego nie używają interfejsy API Google. Zawsze możesz ją zaktualizować.
• Identyfikator projektu jest niepowtarzalny w ramach wszystkich projektów Google Cloud i nie można go zmienić (po ustawieniu). Konsola Cloud automatycznie generuje unikalny ciąg znaków. Zwykle nie ma znaczenia, jaki to ciąg. W większości laboratoriów z kodem trzeba podać identyfikator projektu (zwykle oznaczony jako PROJECT_ID). Jeśli nie podoba Ci się wygenerowany identyfikator, możesz wygenerować inny losowy. Możesz też spróbować użyć własnego adresu e-mail, aby sprawdzić, czy jest on dostępny. Nie można go zmienić po wykonaniu tego kroku. Pozostanie on na stałe w ramach projektu.
• Informacyjnie: istnieje jeszcze 3 wartość, numer projektu, której używają niektóre interfejsy API. Więcej informacji o wszystkich 3 wartościach znajdziesz w dokumentacji.

Uwaga: identyfikator projektu jest globalnie niepowtarzalny i po jego wybraniu nie może być używany przez nikogo innego. Jesteś jedyną osobą, która używa tego identyfikatora. Nawet jeśli projekt zostanie usunięty, nie można ponownie użyć jego identyfikatora.

Uwaga: jeśli używasz konta Gmail, możesz pozostawić domyślną lokalizację ustawioną na Brak organizacji. Jeśli korzystasz z konta Google Workspace, wybierz lokalizację odpowiednią dla Twojej organizacji.

2. Następnie musisz włączyć rozliczenia w konsoli Cloud, aby korzystać z zasobów i interfejsów API Cloud. Przejście przez ten samouczek nie będzie kosztowne, a być może nawet bezpłatne. Aby wyłączyć zasoby i uniknąć obciążenia opłatami po zakończeniu samouczka, możesz usunąć utworzone zasoby lub usunąć 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.

Aktywowanie Cloud Shell

Aktywuj Cloud Shell, klikając ikonę po prawej stronie paska wyszukiwania.

Konfiguracja środowiska

1. Utwórz zmienne środowiskowe związane z projektem i zasobami, uruchamiając podane niżej polecenia w terminalu Cloud Shell.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NAME=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export REGION=us-east1 
export UPLOAD_BUCKET_NAME=menu-item-uploads-$PROJECT_ID
export UPLOAD_BUCKET=gs://menu-item-uploads-$PROJECT_ID
export BUCKET_THUMBNAILS=gs://menu-item-thumbnails-$PROJECT_ID
export MENU_SERVICE_NAME=menu-service
export USER_EMAIL=$(gcloud config list account --format "value(core.account)")

2. Włącz interfejsy API wymagane do przeprowadzenia ćwiczenia

gcloud services enable \
    vision.googleapis.com \
    cloudfunctions.googleapis.com \
    pubsub.googleapis.com \
    cloudbuild.googleapis.com \
    logging.googleapis.com \
    eventarc.googleapis.com \
    artifactregistry.googleapis.com \
    run.googleapis.com \
    --quiet

3. Klonowanie repozytorium

git clone https://github.com/GoogleCloudPlatform/cymbal-eats.git && cd cymbal-eats/cloud-functions

3. Konfigurowanie zasobników Cloud Storage

Tworzenie zasobników na dane

utworzyć zasobniki Cloud Storage na przesyłane dane i miniatury na potrzeby potoku przetwarzania obrazów.

Aby utworzyć 2 zasobniki, użyj polecenia gsutil mb i unikalnej nazwy:

1. Zasób do przesyłania, do którego obrazy będą przesyłane w pierwszej kolejności
2. zasobnik miniatur do przechowywania wygenerowanych miniatur;

Aby utworzyć zasobnik do przesyłania nowych obrazów:

gsutil mb -p $PROJECT_ID -l $REGION $UPLOAD_BUCKET

Przykładowe dane wyjściowe:

Creating gs://menu-item-uploads-cymbal-eats-8399-3119/...

Utwórz zasobnik do przechowywania wygenerowanych miniatur:

gsutil mb -p $PROJECT_ID -l $REGION $BUCKET_THUMBNAILS

Przykładowe dane wyjściowe:

Creating gs://menu-item-thumbnails-cymbal-eats-8399-3119/...

Aktualizowanie uprawnień zasobnika

Zaktualizuj uprawnienia zasobnika Google Cloud Storage, aby zezwolić użytkownikom na odczyt.

Aby przyznać uprawnienia do odczytu i zapisu obiektów w zasobniku, użyj polecenia gsutil iam ch:

gsutil iam ch allUsers:objectViewer $UPLOAD_BUCKET
gsutil iam ch allUsers:objectViewer $BUCKET_THUMBNAILS

Ostrzeżenie: zalecamy ograniczenie dostępu do zasobników pamięci. W ramach tego ćwiczenia wszyscy użytkownicy będą mogli wyświetlać wszystkie obiekty. Więcej informacji o zabezpieczaniu zasobników znajdziesz w artykułach Używanie uprawnień i Sprawdzone metody dotyczące Cloud Storage.

Przykładowe dane wyjściowe

Updated IAM policy for project [cymbal-eats-8399-3119].
[...]

4. Skonfiguruj konta usługi

Utwórz niestandardowe konto usługi dla funkcji Cloud Functions, aby przetwarzać miniatury:

export CF_SERVICE_ACCOUNT=thumbnail-service-sa
gcloud iam service-accounts create ${CF_SERVICE_ACCOUNT}

Przypisz rolę artifactregistry.reader, aby umożliwić operacje odczytu z Artifact Registry:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/artifactregistry.reader"

Przypisz rolę storage.objectCreator, aby umożliwić przechowywanie wygenerowanych obrazów w zasobniku miniatur:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/storage.objectCreator"

Przypisz rolę run.invoker, aby umożliwić wywoływanie usługi Cloud Run:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/run.invoker"

Przypisz rolę eventarc.eventReceiver, aby umożliwić odbiór zdarzeń od dostawców:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/eventarc.eventReceiver"

Przypisz rolę pubsub.publisher do konta usługi Cloud Storage. Pozwoli to kontu usługi publikować zdarzenia, gdy obrazy zostaną przesłane do zasobnika.

GCS_SERVICE_ACCOUNT=$(gsutil kms serviceaccount -p $PROJECT_NUMBER)

gcloud projects add-iam-policy-binding $PROJECT_NUMBER \
    --member "serviceAccount:$GCS_SERVICE_ACCOUNT" \
    --role "roles/pubsub.publisher"

5. Omówienie funkcji przetwarzania obrazu

Utwórz funkcję, która pobiera obraz z Cloud Storage, zmienia jego rozmiar i przesyła go z powrotem do Cloud Storage. Funkcja wywoła interfejs Vision API, aby przypisać obrazowi etykietę opisu. Funkcja sprawdzi etykietę opisu. Jeśli etykieta wskazuje, że obraz przedstawia „Jedzenie”, do usługi menu zostanie wysłane zdarzenie, aby zaktualizować obraz i miniaturę pozycji menu.

Aktywowanie funkcji

Funkcje Cloud Storage są oparte na powiadomieniach Pub/Sub z Cloud Storage i obsługują podobne typy zdarzeń:

• finalize
• usuń
• archiwizować
• aktualizacja metadanych

W tym module wdrożesz i aktywujesz funkcję, gdy obiekt zostanie sfinalizowany w Cloud Storage.

Utworzenie obiektu

Zdarzenia Finalize Object są wywoływane, gdy zakończy się „zapis” obiektu Cloud Storage. Oznacza to, że to zdarzenie jest wywoływane przez utworzenie nowego obiektu lub zastąpienie istniejącego obiektu. Ten element ignoruje operacje archiwizacji i aktualizacji metadanych.

6. Integracja Cloud Storage

Cloud Storage to usługa służąca do przechowywania obiektów w Google Cloud. Obiekt to niezmienny element danych, który składa się z pliku w dowolnym formacie. Obiekty są przechowywane w kontenerach zwanych zasobnikami. Wszystkie zasobniki są powiązane z projektem, a projekty możesz grupować w ramach organizacji. Biblioteki klienta i interfejsy API ułatwiają integrację z Cloud Storage.

W tym module użyjesz biblioteki klienta do odczytu i zapisu obiektów w Cloud Storage.

Instalowanie biblioteki klienta

Biblioteki klienta Cloud są dostępne w wielu popularnych językach programowania. Aby zacząć korzystać z bibliotek, musisz zainstalować bibliotekę klienta.

Korzystanie z biblioteki klienta

Szczegóły implementacji zależą głównie od języka programowania. Aby używać biblioteki klienta w aplikacji, najpierw musisz zaimportować zależności Cloud Storage. Na przykład w projekcie Node.js importy są dodawane w pliku package.json. Poniższy fragment kodu pokazuje powiadomienie z pliku package.json w tym laboratorium.

package.json

{
    "name": "thumbnail-service",
    "version": "0.1.0",
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0",
      "@google-cloud/storage": "^5.18.2",
      "@google-cloud/vision": "^2.4.2",
        ...
    }
  }

Plik package.json zawiera google-cloud/storage jako jedną z zależności aplikacji.

Zależność google-cloud/functions-framework służy do rejestrowania wywołania zwrotnego CloudEvent w ramach frameworku funkcji, które będzie wywoływane przez zdarzenia Cloud Storage.

Zależność google-cloud/vision będzie używana do wywoływania interfejsu Vision API w celu uzyskania adnotacji dla przesłanych obrazów, aby określić, czy jest to produkt spożywczy.

Rejestrowanie wywołania zwrotnego CloudEvent

Zarejestruj wywołanie zwrotne CloudEvent w Functions Framework, które zostanie wywołane przez Cloud Storage, gdy nowy obraz zostanie przesłany do zasobnika.

index.js

functions.cloudEvent('process-thumbnails', async (cloudEvent) => {
    console.log(`Event ID: ${cloudEvent.id}`);
    console.log(`Event Type: ${cloudEvent.type}`);
    ...

Tworzenie obiektu odwołania do pamięci masowej

Po zaimportowaniu bibliotek klienta musisz utworzyć nowego klienta usługi Storage i zbiorniki, z którymi będzie współpracować aplikacja.

index.js

const storage = new Storage();
const bucket = storage.bucket(file.bucket);
const thumbBucket = storage.bucket(process.env.BUCKET_THUMBNAILS);

Powyższy kod tworzy klienta usługi Google Cloud Storage o nazwie „storage” i 2 odwołania do zasobników tej usługi, do których będą odwoływać się zmienne „bucket” i „thumbBucket”.

Pobieranie obiektów Cloud Storage

index.js

await bucket.file(file.name).download({
            destination: originalFile
        });

Dzięki temu podstawowemu zachowaniu pobierania możesz wznowić przerwane pobieranie i stosować bardziej zaawansowane strategie pobierania, takie jak pobieranie obiektów w kawałkach i pobieranie strumieniowe.

Przesyłanie obiektów do Cloud Storage

Prośby o przesyłanie do Cloud Storage możesz wysyłać na 3 sposoby: jako pojedyncze żądanie, jako przesyłanie wieloczęściowe z możliwością wznowienia lub jako przesyłanie wieloczęściowe za pomocą interfejsu XML API. W przypadku przesyłania większych plików lub przesyłania strumieniowego użyj przesyłania możliwego do wznowienia. W przypadku interfejsu XML pliki są przesyłane w częściach i zbierane w jeden obiekt. W przypadku mniejszych obiektów użyj przesyłania za pomocą pojedynczego żądania.

Poniższy kod przesyła obraz do Cloud Storage za pomocą pojedynczego żądania.

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. Integracja interfejsu Vision API

Cloud Vision umożliwia deweloperom łatwą integrację w aplikacjach funkcji związanych z wykrywaniem treści wizualnych, takich jak oznaczanie obrazów etykietami, rozpoznawanie twarzy i punktów orientacyjnych, optyczne rozpoznawanie znaków (OCR) oraz tagowanie treści dla dorosłych.

Instalowanie biblioteki klienta

Biblioteki klienta Cloud są dostępne w wielu popularnych językach programowania. Aby zacząć korzystać z bibliotek, musisz zainstalować bibliotekę klienta.

Tworzenie klienta Image Annotator

Aby uzyskać dostęp do interfejsów API Google za pomocą oficjalnych pakietów SDK klienta, utwórz obiekt usługi na podstawie dokumentu informacyjnego interfejsu API, który opisuje interfejs API dla pakietu SDK. Musisz go pobrać z usługi wyszukiwania interfejsu Vision API, używając swoich danych logowania.

index.js

const client = new vision.ImageAnnotatorClient();

Domyślnie klient uwierzytelnia się za pomocą pliku konta usługi określonego przez zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS.

Tworzenie żądania do interfejsu Vision API

Interfejs Vision API może wykrywać cechy obrazu, wysyłając zawartość pliku obrazu jako ciąg znaków z kodowaniem base64 w ciele żądania.

Aby utworzyć żądanie dodania adnotacji do obrazu za pomocą zasobu images. Żądanie wysłane do tego interfejsu API ma postać obiektu z listą żądań. Każdy element z tej listy zawiera 2 elementy informacji:

• Dane obrazu zakodowane w formacie Base64
• Lista funkcji, które chcesz dodać do obrazu.

index.js

        const client = new vision.ImageAnnotatorClient();
        const visionRequest = {
            image: { source: { imageUri: `gs://${file.bucket}/${file.name}` } },
            features: [
                { type: 'LABEL_DETECTION' },
            ]
        };
        const visionPromise = client.annotateImage(visionRequest);

8. Wdrażanie funkcji Cloud Run

Ta usługa zmiany rozmiaru obrazu jest częścią większego systemu Cymbal Eats. W tej sekcji wdrożysz tylko komponenty związane z funkcją przetwarzania obrazu. Pełna instalacja zawiera interfejs użytkownika do przesyłania obrazu i żądanie przesyłania do przechowywania metadanych. Te funkcje nie są instalowane w ramach tego laboratorium.

Podczas wdrażania funkcji zostaną utworzone te komponenty:

• Funkcje Cloud Run
• Aktywator Eventarc
• Temat i subskrypcja Pub/Sub

Aby wdrożyć funkcje Cloud Run z zasobnikiem aktywatorów w menu-item-uploads-$PROJECT_ID, uruchom w terminalu Cloud Shell to polecenie:

Aby wdrożyć funkcję Cloud Run bezpośrednio w Cloud Run, musisz najpierw wdrożyć funkcję, a następnie utworzyć dla niej odpowiedni uchwyt.

Wdróż funkcje Cloud Run:

gcloud beta run deploy process-thumbnails \
      --source=thumbnail \
      --function process-thumbnails \
      --region $REGION \
      --base-image google-22-full/nodejs20 \
      --no-allow-unauthenticated \
      --project=$PROJECT_ID \
--service-account="${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
--set-env-vars=BUCKET_THUMBNAILS=$BUCKET_THUMBNAILS,MENU_SERVICE_URL=$MENU_SERVICE_URL \
  --max-instances=1 \
  --quiet

Przykładowe dane wyjściowe:

Done.                                                                                                                                                                                    
Service [process-thumbnails] revision [process-thumbnails-00001-abc] has been deployed and is serving 100 percent of traffic.
Service URL: https://process-thumbnails-000000000.us-east1.run.app

Utwórz aktywator:

gcloud eventarc triggers create process-thumbnails-trigger \
     --location=$REGION \
     --destination-run-service=process-thumbnails \
    --destination-run-region=$REGION \
     --event-filters="type=google.cloud.storage.object.v1.finalized" \
     --event-filters="bucket=$UPLOAD_BUCKET_NAME" \
     --service-account="${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com"

Przykładowe dane wyjściowe:

Creating trigger [process-thumbnails-trigger] in project [qwiklabs-gcp-02-53f8532696e1], location [us-east1]...done.                                                                     
WARNING: It may take up to 2 minutes for the new trigger to become active.

Jeśli wdrożenie reguły nie powiedzie się z powodu problemu z uprawnieniami, poczekaj, aż zmiany w uprawnieniach dostępu z poprzedniego kroku zostaną rozpowszechnione. Zwykle zajmuje to 1–2 minuty. Następnie spróbuj ponownie wdrożyć aplikację.

Przykładowy błąd:

...If you recently started to use Eventarc, it may take a few minutes before all necessary permissions are propagated to the Service Agent...
[...] 

W konsoli Google Cloud sprawdź usługę Cloud Run utworzoną dla funkcji:

W konsoli Cloud sprawdź Eventarc, który został utworzony dla funkcji:

W konsoli Google Cloud sprawdź temat i subskrypcję Pub/Sub utworzone dla aktywatora Eventarc:

9. Testowanie i weryfikowanie kompleksowego rozwiązania

Prześlij nowe zdjęcie do Cloud Storage i obserwuj postępy przetwarzania podczas analizowania obrazów. Aby przetestować kompleksowe rozwiązanie, monitoruj logi funkcji w chmurze.

Przesyłanie obrazu

Uwaga: zdjęcie autorstwa Toma Dillona z Unsplash można używać bezpłatnie na podstawie licencji Unsplash.

1. Zapisz ten obraz na komputerze lokalnym.
2. Zmień nazwę pliku na 1.jpg.
3. Otwórz konsolę Cloud Storage.
4. Kliknij zasobnik menu-item-uploads-....
5. Kliknij Prześlij pliki.
6. Prześlij plik 1.jpg do zasobnika pamięci
7. W Cloud Console otwórz Cloud Run.
8. Kliknij process-thumbails.
9. Kliknij kartę LOGS (Logi).

Uwaga: funkcja została uruchomiona i załadowała obraz do zasobnika miniatur. Na podstawie etykiet Vision API dla przesłanego obrazu stan elementu menu zostanie ustawiony na „Gotowy”. Oznacza to, że interfejs Vision API dodał adnotację „Jedzenie”.

Ponieważ usługa menu nie została wdrożona w tym laboratorium, żądanie aktualizacji elementu menu zakończyło się niepowodzeniem.

10. Otwórz zasobnik menu-item-thumbnails-$PROJECT_ID w Cloud Storage.
11. Sprawdź, czy miniatura została utworzona w zasobniku miniatur.

Przesyłanie obrazu niebędącego produktem spożywczym

Aby sprawdzić, czy funkcja działa prawidłowo, prześlij obraz, który nie zawiera obiektu, który można by zaklasyfikować jako „Jedzenie”.

Uwaga: zdjęcie autorstwa Insung Yoon z Unsplash można bezpłatnie używać na podstawie licencji Unsplash.

1. Zapisz ten obraz na komputerze lokalnym.
2. Zmień nazwę pliku na 2.jpg.
3. Otwórz konsolę Cloud Storage.
4. Kliknij zasobnik menu-item-uploads-....
5. Kliknij PRZEŚLIJ pliki.
6. Prześlij plik 2.jpg do zasobnika pamięci
7. W Cloud Console otwórz Cloud Run.
8. Kliknij process-thumbails.
9. Kliknij kartę LOGS (Logi).

Uwaga: funkcja została uruchomiona i przesłała obraz do zasobnika miniatur. Na podstawie etykiet Vision API dla przesłanego obrazu stan pozycji menu zostanie ustawiony na „Niepowodzenie”. Oznacza to, że interfejs Vision API nie dodał adnotacji „Jedzenie”.

Ponieważ usługa menu nie została wdrożona w tym laboratorium, żądanie aktualizacji elementu menu zakończyło się niepowodzeniem.

10. Gratulacje!

Gratulacje! Masz ukończony ten moduł.

Co dalej:

Inne ćwiczenia dotyczące Cymbal Eats:

• Aktywowanie przepływów pracy w Cloud za pomocą Eventarc
• Łączenie z Private CloudSQL z Cloud Run
• Łączenie się z w pełni zarządzanymi bazami danych z Cloud Run
• Bezpieczeństwo aplikacji bezserwerowej dzięki serwerowi proxy identyfikującemu tożsamość (IAP)
• Aktywowanie zadań Cloud Run za pomocą usługi Cloud Scheduler
• Bezpieczne wdrażanie w Cloud Run
• Bezpieczeństwo ruchu przychodzącego Cloud Run
• Łączenie z prywatną usługą AlloyDB z Autopilota w GKE

Czyszczenie danych

Aby uniknąć obciążenia konta Google Cloud opłatami za zasoby zużyte w tym samouczku, możesz usunąć projekt zawierający te zasoby lub zachować projekt i usunąć poszczególne zasoby.

Usuwanie projektu

Najprostszym sposobem na uniknięcie płatności jest usunięcie projektu utworzonego na potrzeby tego samouczka.