Aktywowanie przetwarzania zdarzeń z Cloud Storage przy użyciu Eventarc i Cloud Functions (2 generacji)

1. Omówienie

W tym module 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ć Cloud Functions (2 generacji). Funkcja użyje interfejsu Google Vision API i zapisze uzyskany obraz z powrotem w zasobniku Cloud Storage.

Czego się nauczysz

Jak utworzyć potok przetwarzania obrazu.

• Skonfiguruj zasobniki Cloud Storage
• Tworzenie funkcji w Cloud Functions do odczytu i zapisu obiektów w Cloud Storage
• Zintegruj interfejs Vision API w celu wykrywania obrazów jedzenia
• Wdrażanie funkcji w Cloud Functions
• Wdrażanie aktywatora Eventarc
• Testowanie i weryfikacja kompleksowego rozwiązania

Wymagania wstępne

• W tym module zakładamy, że znasz środowisko Cloud Console i środowiska powłoki.
• Wcześniejsze doświadczenie z Cloud Storage, Cloud Functions lub Vision API może być pomocne, ale nie jest wymagane.

2. Konfiguracja i wymagania

Konfigurowanie projektu Cloud

1. Zaloguj się w konsoli Google Cloud i utwórz nowy projekt lub wykorzystaj już istniejący. Jeśli nie masz jeszcze konta Gmail ani Google Workspace, musisz je utworzyć.

• Nazwa projektu jest wyświetlaną nazwą uczestników tego projektu. To ciąg znaków, który nie jest używany przez interfejsy API Google. W każdej chwili możesz ją zmienić.
• Identyfikator projektu jest unikalny we wszystkich projektach Google Cloud i nie można go zmienić (po jego ustawieniu nie można go zmienić). Cloud Console automatycznie wygeneruje unikalny ciąg znaków. zwykle nieważne, co ona jest. W większości ćwiczeń z programowania konieczne jest odwołanie się do identyfikatora projektu (zwykle nazywa się on PROJECT_ID). Jeśli nie podoba Ci się wygenerowany identyfikator, możesz wygenerować kolejny losowy. Możesz też spróbować własnych sił i sprawdzić, czy jest dostępna. Potem nie będzie można go zmienić. Pozostanie ono przez czas trwania projektu.
• Dostępna jest trzecia wartość, numer projektu, z którego korzystają niektóre interfejsy API. Więcej informacji o wszystkich 3 wartościach znajdziesz w dokumentacji.

Uwaga: identyfikator projektu jest globalnie unikalny i po wybraniu nie może go użyć żaden inny użytkownik. Jesteś jedynym użytkownikiem tego identyfikatora. Nawet po usunięciu projektu identyfikatora nie można użyć ponownie

Uwaga: jeśli używasz konta Gmail, jako domyślną lokalizację możesz pozostawić ustawienie Brak organizacji. Jeśli używasz konta Google Workspace, wybierz lokalizację, która będzie odpowiednia dla Twojej organizacji.

2. Następnie musisz włączyć płatności w Cloud Console, aby korzystać z zasobów Cloud/interfejsów API. Ukończenie tego ćwiczenia z programowania nie powinno kosztować zbyt wiele. Aby wyłączyć zasoby, aby nie naliczać opłat po zakończeniu tego samouczka, możesz usunąć utworzone zasoby lub cały 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

1. Utwórz projekt i zmienne środowiskowe związane z zasobami, uruchamiając poniższe 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=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 w module

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. Włącz interfejsy API wymagane w module. (krok z konkretnym modułem Qwiklabs)

gcloud services disable cloudfunctions.googleapis.com
gcloud services enable cloudfunctions.googleapis.com

4. 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

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

Użyj polecenia gsutil mb z unikatową nazwą, aby utworzyć 2 zasobniki:

1. Prześlij zasobnik, do którego najpierw zostaną przesłane obrazy
2. Zasobnik z miniaturami do przechowywania wygenerowanych miniatur

Utwórz 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/...

Tworzenie zasobnika 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/...

Zaktualizuj uprawnienia zasobnika

Zaktualizuj uprawnienia do zasobnika na dane, aby przyznać użytkownikom uprawnienia do odczytu.

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

Ostrzeżenie: zalecaną metodą jest ograniczenie dostępu do zasobników na dane. Na potrzeby tego modułu wszyscy użytkownicy będą mogli zobaczyć wszystkie obiekty. Więcej informacji o zabezpieczaniu zasobników na dane znajdziesz w artykułach na temat korzystania z uprawnień i sprawdzonych metod 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 w Cloud Functions do przetwarzania miniatur:

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ć zapisywanie 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ć 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

Tworzenie funkcji pobierania obrazu z Cloud Storage, zmiany rozmiaru obrazu i przesyłania go z powrotem do Cloud Storage. Ta funkcja wywoła interfejs Vision API, aby przypisać do obrazu etykietę opisu. Funkcja sprawdzi etykietę opisu. Jeśli etykieta identyfikuje obraz jako „Jedzenie” do usługi menu zostanie wysłane zdarzenie w celu zaktualizowania obrazu i miniatury pozycji menu.

Aktywowanie funkcji

Funkcje Cloud Storage opierają się na powiadomieniach Pub/Sub z Cloud Storage i obsługują podobne typy zdarzeń:

• finalizuj
• usuń
• archiwum
• aktualizacja metadanych

W tym module wdrożysz i aktywujesz funkcję po sfinalizowaniu obiektu w Cloud Storage.

Utworzenie obiektu

Zdarzenia finalizacji obiektu są aktywowane, gdy nastąpi wywołanie „zapis” obiektu Cloud Storage. Oznacza to w szczególności, że zdarzenie to wywołuje utworzenie nowego obiektu lub zastąpienie istniejącego obiektu. Ten aktywator ignoruje operacje archiwum i aktualizacji metadanych.

6. Zintegruj Cloud Storage

Cloud Storage to usługa służąca do przechowywania obiektów w Google Cloud. Obiekt to stały fragment danych składający się z pliku w dowolnym formacie. Przechowujesz obiekty w kontenerach zwanych zasobnikami. Wszystkie zasobniki są powiązane z projektem. Możesz zgrupować projekty w ramach organizacji. Biblioteki klientów i interfejsy API umożliwiają 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 w dużej mierze zależą od języka programowania. Aby korzystać z 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. Fragment kodu poniżej pokazuje powiadomienie o pliku package.json z tego modułu.

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

W pliku package.json jako jedna z zależności aplikacji znajduje się google-cloud/storage.

Zależność google-cloud/functions-framework jest używana do zarejestrowania wywołania zwrotnego CloudEvent za pomocą platformy Functions, które będzie aktywowane przez zdarzenia Cloud Storage.

Zależność google-cloud/vision zostanie użyta do wywołania interfejsu Vision API w celu pobrania adnotacji do przesłanych obrazów w celu określenia, czy jest to produkt spożywczy.

Rejestrowanie wywołania zwrotnego CloudEvent

Zarejestruj wywołanie zwrotne CloudEvent za pomocą platformy funkcji, które będzie aktywowane przez Cloud Storage po przesłaniu do zasobnika nowego obrazu.

index.js

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

Tworzenie obiektu referencyjnego pamięci masowej

Po zaimportowaniu bibliotek klienta musisz utworzyć nowego klienta pamięci masowej i zasobniki, z którymi aplikacja będzie współpracować.

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 pamięci masowej o nazwie „storage” i dwa odwołania do zasobników na dane, do których będą się odwoływać zmienne „zasobnik” i „thumbBucket”

Pobierz obiekty Cloud Storage

index.js

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

Za pomocą tej podstawowej metody pobierania możesz wznawiać przerwane pobieranie oraz korzystać z bardziej zaawansowanych strategii pobierania, takich jak pobieranie obiektów na wycinki i strumieniowe pobieranie plików.

Przesyłanie obiektów do Cloud Storage

Żądania przesyłania do Cloud Storage możesz wysyłać na 3 sposoby: pojedyncze żądanie, wznawianie lub wieloczęściowe przesyłanie przy użyciu interfejsu XML API. W przypadku przesyłania większych plików lub przesyłania strumieniowego użyj funkcji wznawiania. Pliki XML API są przesyłane w części i montowane jako pojedynczy obiekt. W przypadku mniejszych obiektów używaj przesyłania z pojedynczym żądaniem.

Poniższy kod umożliwia przesyłanie obrazu do chmury w ramach pojedynczego żądania.

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. Zintegruj interfejs Vision API

Cloud Vision umożliwia programistom łatwą integrację w aplikacjach funkcji wykrywania treści wizualnych, takich jak dodawanie etykiet do obrazów, wykrywanie twarzy i punktów orientacyjnych, optyczne rozpoznawanie znaków (OCR) oraz oznaczanie 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 komentowania obrazu

Aby uzyskać dostęp do interfejsów API Google przy użyciu oficjalnych pakietów SDK klienta, musisz utworzyć obiekt usługi na podstawie dokumentu wykrywania interfejsu API, który opisuje pakiet SDK. Musisz pobrać go z usługi wykrywania Vision API przy użyciu swoich danych logowania.

index.js

const client = new vision.ImageAnnotatorClient();

Domyślnie klient będzie uwierzytelniać się przy użyciu 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 pliku graficznego, wysyłając jego zawartość jako ciąg zakodowany w formacie base64 w treści żądania.

Aby utworzyć żądanie przy użyciu zasobu obrazów w celu dodania adnotacji do obrazu. Żądanie do tego interfejsu API ma postać obiektu z listą żądań. Każda pozycja z tej listy zawiera dwa elementy:

• Dane obrazów zakodowane w base64
• Listę 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 w Cloud Functions

Ta usługa zmiany rozmiaru obrazów 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 użytkownika do przesłania obrazu oraz żądanie pobrania wynikowych metadanych. Te funkcje nie są instalowane w ramach tego modułu.

Podczas wdrażania funkcji zostaną utworzone te komponenty:

• Funkcja w Cloud Functions
• Usługa Cloud Run
• Aktywator Eventarc
• Temat i subskrypcja Pub/Sub

W terminalu Cloud Shell uruchom poniższe polecenie, aby wdrożyć funkcję w Cloud Functions z zasobnikiem aktywatora w: menu-item-uploads-$PROJECT_ID:

gcloud functions deploy process-thumbnails \
  --gen2 \
  --runtime=nodejs16 \
  --source=thumbnail \
  --region=$REGION \
  --project=$PROJECT_ID \
  --entry-point=process-thumbnails \
  --trigger-bucket=$UPLOAD_BUCKET \
  --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

Jeśli wdrożenie nie uda się z powodu problemu z uprawnieniami dotyczącego przesyłanego zasobnika na dane, poczekaj na propagację zmian uprawnień z poprzedniego kroku. Zwykle zajmuje to 1–2 minuty. Po tym czasie ponowienie próby wdrożenia jest możliwe.

Przykładowe dane wyjściowe

Deploying function (may take a while - up to 2 minutes)...done.
[...] 

W konsoli Cloud sprawdź utworzoną funkcję w Cloud Functions:

W konsoli Cloud sprawdź usługę Cloud Run, która została utworzona dla tej funkcji:

W konsoli Cloud sprawdź aktywator Eventarc utworzony dla funkcji:

W konsoli Cloud przejrzyj pola Topic (Temat) i Subscription (Subskrypcja) dotyczące Pub/Sub, które zostały utworzone dla aktywatora Eventarc:

9. Testowanie i weryfikacja kompleksowego rozwiązania

Prześlij nowe zdjęcie do Cloud Storage i monitoruj postęp potoku podczas analizy obrazów. Przetestuj kompleksowe rozwiązanie, monitorując logi Cloud Functions.

Przesyłanie odpowiedniego obrazu

Uwaga: zdjęcie wykonane przez Toma Dillona na stronie Unsplash jest bezpłatne na licencji Unsplash

1. Zapisz ten obraz na komputerze lokalnym
2. Zmień nazwę pliku 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 na dane
7. W konsoli Cloud otwórz Cloud Functions.
8. Kliknij process-thumbails.
9. Kliknij kartę LOGS.

Uwaga: funkcja uruchomiła się i załadowała obraz do zasobnika miniatur. Na podstawie etykiet Vision API dla przesłanego obrazu stan pozycji menu zostanie ustawiony na „Gotowe”. Oznacza to, że interfejs Vision API oznaczył obraz etykietą „Jedzenie”. Ponieważ nie wdrożyliśmy usługi menu, żądanie aktualizacji pozycji menu się nie powiodło.

10. Przejdź do zasobnika menu-item-thumbnails-$PROJECT_ID Cloud Storage.
11. Sprawdź, czy miniatura została utworzona w zasobniku miniatur

Przesyłanie zdjęcia, które nie jest jedzeniem

Aby sprawdzić, czy funkcja działa prawidłowo, prześlij obraz niezawierający obiektu, który zostałby sklasyfikowany jako „Jedzenie”. elementu.

Uwaga: zdjęcie wykonane przez Insung Yoon z albumu Unsplash jest bezpłatne na licencji Unsplash

1. Zapisz ten obraz na komputerze lokalnym
2. Zmień nazwę pliku 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 na dane
7. W konsoli Cloud otwórz Cloud Functions.
8. Kliknij process-thumbails.
9. Kliknij kartę LOGS.

Uwaga: funkcja uruchomiła się 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 do obrazu jako „Jedzenie”.

Usługa menu nie została wdrożona w tym module, dlatego żądanie aktualizacji pozycji menu się nie udało.

10. Gratulacje!

Gratulacje! Moduł ukończony.

Co dalej:

Poznaj inne ćwiczenia z programowania Cymbal Eats:

• Aktywowanie przepływów pracy w Cloud za pomocą Eventarc
• Łączenie z Private Cloud SQL z poziomu Cloud Run
• Łączenie z w pełni zarządzanymi bazami danych z Cloud Run
• Bezpieczna aplikacja bezserwerowa z serwerem proxy identyfikującym tożsamość (IAP)
• Aktywowanie zadań Cloud Run za pomocą usługi Cloud Scheduler
• Bezpieczne wdrażanie w Cloud Run
• Zabezpieczanie ruchu przychodzącego w Cloud Run
• Łączenie z prywatnym 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.

Usuwam projekt

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