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

1. Przegląd

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

Czego się nauczysz

Jak utworzyć potok przetwarzania obrazów.

Konfigurowanie zasobników na dane
Tworzenie funkcji Cloud Run do odczytywania i zapisywania obiektów w Cloud Storage
Wdrażanie aktywatora Eventarc
Integracja interfejsu Vision API w celu wykrywania obrazów jedzenia
Testowanie i weryfikacja kompleksowego rozwiązania

Wymagania wstępne

Zakładamy, że użytkownik zna konsolę Cloud i środowiska powłoki.
Znajomość usług Cloud Storage, funkcji Cloud Run lub interfejsu Vision API może być przydatna, ale nie jest wymagana.

2. Konfiguracja i wymagania

Konfigurowanie projektu w Google Cloud

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. Zawsze możesz ją zaktualizować.
Identyfikator projektu jest unikalny we wszystkich projektach Google Cloud i 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 oznaczanego 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 pozostaje on taki przez cały czas trwania projektu.
Warto wiedzieć, że istnieje też trzecia wartość, numer projektu, której używają 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. Wykonanie tego laboratorium nie będzie kosztować dużo, a może nawet nic. Aby wyłączyć zasoby i uniknąć naliczania opłat po zakończeniu tego samouczka, możesz usunąć utworzone zasoby lub projekt. Nowi użytkownicy Google Cloud mogą skorzystać z programu bezpłatnego okresu próbnego o wartości 300 USD.

Aktywowanie Cloud Shell

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

Konfiguracja środowiska

Utwórz zmienne środowiskowe związane z projektem i zasobami, uruchamiając w terminalu Cloud Shell te polecenia:

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)")

Włączanie interfejsów API wymaganych w laboratorium

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

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 Cloud Storage

Utwórz zasobniki Cloud Storage do przesyłania i miniatur w potoku przetwarzania obrazów.

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

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

Utwórz zasobnik, do którego będziesz przesyłać nowe obrazy:

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 do zasobnika pamięci, aby umożliwić użytkownikom odczyt.

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

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

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 Function, która będzie przetwarzać miniatury:

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

Przyznaj 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"

Przyznaj 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"

Przyznaj rolę run.invoker, aby zezwolić na 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"

Przyznaj rolę eventarc.eventReceiver, aby umożliwić odbieranie 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. Umożliwi to kontu usługi publikowanie zdarzeń po przesłaniu obrazów 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 pobierze obraz z Cloud Storage, zmieni jego rozmiar i prześle go z powrotem do Cloud Storage. Funkcja wywoła interfejs Vision API, aby przypisać do obrazu etykietę z opisem. Funkcja sprawdzi etykietę opisu. Jeśli etykieta określa obraz jako „Jedzenie”, do usługi menu zostanie wysłane zdarzenie, aby zaktualizować obraz i miniaturę pozycji w menu.

Aktywowanie funkcji

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

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

Utworzenie obiektu

Zdarzenia finalizacji obiektu są aktywowane, gdy zakończy się „zapis” obiektu Cloud Storage. Oznacza to, że utworzenie nowego obiektu lub zastąpienie istniejącego obiektu aktywuje to zdarzenie. Ten wyzwalacz 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 fragment danych składający się z pliku w dowolnym formacie. Obiekty są przechowywane w kontenerach zwanych zasobnikami. Wszystkie zasobniki są powiązane z projektem, a projekty można grupować w ramach organizacji. Biblioteki klienta i interfejsy API ułatwiają integrację z Cloud Storage.

W tym module użyjesz biblioteki klienta do odczytywania i zapisywania 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 w dużej mierze zależą od języka programowania. Aby użyć biblioteki klienta w aplikacji, najpierw zaimportuj zależności Cloud Storage. Na przykład w projekcie Node.js importy są dodawane w pliku package.json. Poniższy fragment kodu przedstawia informację w pliku package.json w tym module.

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",
        ...
    }
  }

Rejestrowanie wywołania zwrotnego CloudEvent

Zarejestruj wywołanie zwrotne CloudEvent w Functions Framework, które będzie wywoływane 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

Po zaimportowaniu bibliotek klienta musisz utworzyć nowego klienta usługi pamięci i zasobniki, z którymi będzie wchodzić w interakcję Twoja aplikacja.

index.js

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

Pobieranie obiektów Cloud Storage

index.js

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

Przesyłanie obiektów do Cloud Storage

Żądania przesyłania do Cloud Storage można wysyłać na 3 sposoby: w ramach jednego żądania, z możliwością wznowienia lub za pomocą interfejsu XML API do przesyłania wieloczęściowego. W przypadku większych przesyłań lub przesyłań strumieniowych używaj przesyłania możliwego do wznowienia. W przypadku interfejsu XML API pliki są przesyłane w częściach i łączone w jeden obiekt. W przypadku mniejszych obiektów używaj przesyłania w ramach pojedynczego żądania.

Poniższy kod przesyła obraz do Cloud Storage za pomocą przesyłania w ramach jednego żądania.

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. Integrowanie 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 narzędzia do adnotacji obrazów

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

index.js

const client = new vision.ImageAnnotatorClient();

Tworzenie żądania do interfejsu Vision API

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

Aby utworzyć żądanie za pomocą zasobu images, dodaj adnotacje do obrazu. Żądanie wysyłane do tego interfejsu API ma postać obiektu z listą żądań. Każdy element na tej liście zawiera 2 informacje:

Dane obrazu zakodowane w formacie Base64.
Lista cech, które chcesz opisać w przypadku tego 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 obejmuje interfejs do przesyłania obrazu i żądanie dalszego przetwarzania w celu zapisania metadanych. Te funkcje nie są instalowane w ramach tego modułu.

Podczas wdrażania funkcji zostaną utworzone te komponenty:

Funkcje Cloud Run
Aktywator Eventarc
Temat i subskrypcja Pub/Sub

W terminalu Cloud Shell uruchom to polecenie, aby wdrożyć funkcje Cloud Run z zasobnikiem aktywującym na menu-item-uploads-$PROJECT_ID:

Aby wdrożyć funkcję Cloud Run bezpośrednio w Cloud Run, najpierw wdrożysz funkcję, a potem utworzysz dla niej aktywator.

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 wyzwalacza nie powiedzie się z powodu problemu z uprawnieniami, poczekaj na rozpowszechnienie zmian w IAM z poprzedniego kroku. Zwykle zajmuje to 1–2 minuty. Następnie spróbuj ponownie wdrożyć aplikację.

Przykładowe dane wyjściowe błędu:

...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 Cloud sprawdź usługę Cloud Run utworzoną dla funkcji:

W konsoli Cloud sprawdź aktywator Eventarc utworzony dla funkcji:

W konsoli Cloud sprawdź temat i subskrypcję Pub/Sub utworzone na potrzeby wyzwalacza Eventarc:

9. Testowanie i weryfikacja kompleksowego rozwiązania

Prześlij nowe zdjęcie do Cloud Storage i monitoruj postępy w potoku podczas analizowania obrazów. Kompleksowe rozwiązanie przetestujesz, monitorując logi funkcji chmurowych.

Przesyłanie obrazu

Zapisz ten obraz na komputerze lokalnym.
Zmień nazwę pliku 1.jpg.
Otwórz konsolę Cloud Storage.
Kliknij zasobnik menu-item-uploads-....
Kliknij PRZEŚLIJ PLIKI.
Prześlij plik 1.jpg do zasobnika pamięci.
W Cloud Console otwórz Cloud Run.
Kliknij process-thumbnails.
Kliknij kartę LOGI.

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

Przesyłanie obrazu przedstawiającego produkt nieżywnościowy

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

Zapisz ten obraz na komputerze lokalnym.
Zmień nazwę pliku 2.jpg.
Otwórz konsolę Cloud Storage.
Kliknij zasobnik menu-item-uploads-....
KLIKNIJ PRZEŚLIJ PLIKI
Prześlij plik 2.jpg do zasobnika na dane.
W Cloud Console otwórz Cloud Run.
Kliknij process-thumbnails.
Kliknij kartę LOGI.

10. Gratulacje!

Gratulacje! Moduł został ukończony.

Co dalej?

Zapoznaj się z innymi ćwiczeniami z programowania dotyczącymi Cymbal Eats:

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 w tym samouczku.