Ereignisverarbeitung aus Cloud Storage mit Eventarc und Cloud Functions (2. Generation) auslösen

1. Übersicht

In diesem Lab lernen Sie, wie Sie mit Cloud Storage-Bucket-Ereignissen und Eventarc die Ereignisverarbeitung auslösen. Sie verwenden Cloud Functions (2. Generation), um Daten zu analysieren und Bilder zu verarbeiten. Die Funktion verwendet die Vision API von Google und speichert das resultierende Bild wieder im Cloud Storage-Bucket.

Lerninhalte

Hier erfahren Sie, wie Sie eine Pipeline zur Bildverarbeitung erstellen.

• Storage-Buckets konfigurieren
• Cloud Functions-Funktion zum Lesen und Schreiben von Objekten in Cloud Storage erstellen
• Vision API einbinden, um Bilder von Lebensmitteln zu erkennen
• Cloud Functions-Funktion bereitstellen
• Eventarc-Trigger bereitstellen
• End-to-End-Lösung testen und validieren

Vorbereitung

• Für dieses Lab wird davon ausgegangen, dass Sie mit der Cloud Console und mit Shell-Umgebungen vertraut sind.
• Vorkenntnisse in Cloud Storage, Cloud Functions oder Vision API sind hilfreich, aber nicht erforderlich.

2. Einrichtung und Anforderungen

Cloud-Projekt einrichten

1. Melden Sie sich in der Google Cloud Console an und erstellen Sie ein neues Projekt oder verwenden Sie ein vorhandenes Projekt. Wenn Sie noch kein Gmail- oder Google Workspace-Konto haben, müssen Sie eines erstellen.

• Der Projektname ist der Anzeigename für die Projektteilnehmer. Es handelt sich um eine Zeichenfolge, die von Google APIs nicht verwendet wird. Sie können sie jederzeit aktualisieren.
• Die Projekt-ID ist für alle Google Cloud-Projekte eindeutig und unveränderlich. Sie kann nach dem Festlegen nicht mehr geändert werden. Die Cloud Console generiert automatisch einen eindeutigen String. ist Ihnen meist egal, was es ist. In den meisten Codelabs musst du dich auf die Projekt-ID beziehen, die üblicherweise als PROJECT_ID gekennzeichnet ist. Wenn Ihnen die generierte ID nicht gefällt, können Sie eine weitere zufällige ID erstellen. Alternativ können Sie einen eigenen verwenden und nachsehen, ob er verfügbar ist. Sie kann nach diesem Schritt nicht mehr geändert werden und bleibt für die Dauer des Projekts bestehen.
• Zur Information gibt es noch einen dritten Wert, die Projektnummer, die von manchen APIs verwendet wird. Weitere Informationen zu allen drei Werten finden Sie in der Dokumentation.

Achtung:Eine Projekt-ID ist global eindeutig und kann nach der Auswahl von niemandem verwendet werden. Sie sind der einzige Nutzer dieser ID. Selbst wenn ein Projekt gelöscht wurde, kann die ID nicht mehr verwendet werden

Hinweis:Wenn Sie ein Gmail-Konto verwenden, können Sie die Standardeinstellung Keine Organisation beibehalten. Wenn Sie ein Google Workspace-Konto verwenden, wählen Sie einen Standort aus, der für Ihre Organisation sinnvoll ist.

2. Als Nächstes müssen Sie in der Cloud Console die Abrechnung aktivieren, um Cloud-Ressourcen/APIs verwenden zu können. Dieses Codelab sollte ohne großen Aufwand betrieben werden. Wenn Sie Ressourcen herunterfahren möchten, um über diese Anleitung hinaus keine Kosten zu verursachen, können Sie die von Ihnen erstellten Ressourcen oder das gesamte Projekt löschen. Neue Google Cloud-Nutzer haben Anspruch auf eine kostenlose Testversion von 300$.

Cloud Shell aktivieren

Aktivieren Sie Cloud Shell, indem Sie auf das Symbol rechts neben der Suchleiste klicken.

Umgebung einrichten

1. Erstellen Sie ein Projekt und ressourcenbezogene Umgebungsvariablen. Führen Sie dazu die folgenden Befehle im Cloud Shell-Terminal aus.

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. Für das Lab erforderliche APIs aktivieren

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. Aktivieren Sie die für das Lab erforderlichen APIs. (Qwiklabs-spezifischer Schritt)

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

4. Repository klonen

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

3. Cloud Storage-Buckets konfigurieren

Storage-Buckets erstellen

Erstellen Sie Cloud Storage-Buckets zum Hochladen und Miniaturansichten für die Bildverarbeitungspipeline.

Verwenden Sie den Befehl gsutil mb und einen eindeutigen Namen, um zwei Buckets zu erstellen:

1. Bucket hochladen, in den die Bilder zuerst hochgeladen werden
2. Miniaturansicht-Bucket zum Speichern generierter Miniaturansichten

Erstellen Sie einen Bucket, um neue Bilder hochzuladen:

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

Beispielausgabe:

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

Erstellen Sie einen Bucket zum Speichern generierter Miniaturansichten:

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

Beispielausgabe:

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

Bucket-Berechtigungen aktualisieren

Aktualisieren Sie die Storage-Bucket-Berechtigungen, um Nutzern Leseberechtigungen zu gewähren.

Verwenden Sie den Befehl „gsutil iam ch“, um die Berechtigung zum Lesen und Schreiben von Objekten in Ihrem Bucket zu erteilen:

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

Warnung: Es hat sich bewährt, den Zugriff auf Storage-Buckets einzuschränken. Für die Zwecke dieses Labs dürfen alle Nutzer alle Objekte ansehen. Weitere Informationen zum Sichern von Storage-Buckets finden Sie unter IAM-Berechtigung verwenden und Best Practices für Cloud Storage.

Beispielausgabe

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

4. Dienstkonten konfigurieren

Erstellen Sie ein benutzerdefiniertes Dienstkonto für die Cloud Functions-Funktion, um Miniaturansichten zu verarbeiten:

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

Gewähren Sie die Rolle artifactregistry.reader, um Lesevorgänge aus Artifact Registry zuzulassen:

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

Gewähren Sie die Rolle storage.objectCreator, damit generierte Bilder im Miniaturansicht-Bucket gespeichert werden können:

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

Gewähren Sie die Rolle run.invoker, um den Aufruf des Cloud Run-Dienstes zuzulassen:

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

Weisen Sie die Rolle eventarc.eventReceiver zu, um den Empfang von Ereignissen von Anbietern zuzulassen:

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

Gewähren Sie dem Cloud Storage-Dienstkonto die Rolle pubsub.publisher. Dadurch kann das Dienstkonto Ereignisse veröffentlichen, wenn Bilder in den Bucket hochgeladen werden.

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. Bildverarbeitungsfunktion – Übersicht

Erstellen Sie eine Funktion, um ein Bild aus Cloud Storage herunterzuladen, die Bildgröße anzupassen und das Bild wieder in Cloud Storage hochzuladen. Die Funktion ruft die Vision API auf, um dem Bild ein Beschreibungslabel zuzuweisen. Die Funktion prüft das Beschreibungslabel. Wenn das Bild auf dem Label als „Lebensmittel“ gekennzeichnet ist wird ein Ereignis an den Menüservice gesendet, um das Bild und die Miniaturansicht des Menüpunkts zu aktualisieren.

Funktion auslösen

Cloud Storage-Funktionen basieren auf Pub/Sub-Benachrichtigungen von Cloud Storage und unterstützen ähnliche Ereignistypen:

• Finalize
• Delete
• Archive
• Metadata Update

In diesem Lab stellen Sie eine Funktion bereit und lösen sie aus, wenn ein Objekt in Cloud Storage abgeschlossen wurde.

Objekt finalisieren

Object-Finalize-Ereignisse werden ausgelöst, wenn ein Schreibvorgang eines Cloud Storage-Objekts erfolgreich abgeschlossen wurde. Dieses Ereignis wird also ausgelöst, wenn ein neues Objekt erstellt oder ein vorhandenes Objekt überschrieben wird. Archivierungs- und Metadatenaktualisierungsvorgänge werden von diesem Trigger ignoriert.

6. Cloud Storage einbinden

Cloud Storage ist ein Dienst zum Speichern Ihrer Objekte in Google Cloud. Ein Objekt ist ein unveränderliches Datenelement, das aus einer Datei mit einem beliebigen Format besteht. Objekte werden in Containern gespeichert, die als Buckets bezeichnet werden. Alle Buckets sind einem Projekt zugeordnet und Sie können Ihre Projekte in einer Organisation gruppieren. Clientbibliotheken und APIs ermöglichen die Einbindung in Cloud Storage

In diesem Lab verwenden Sie die Clientbibliothek, um Objekte in Cloud Storage zu lesen und zu schreiben.

Clientbibliothek installieren

Cloud-Clientbibliotheken sind in vielen gängigen Programmiersprachen verfügbar. Damit Sie die Bibliotheken verwenden können, müssen Sie die Clientbibliothek installieren.

Clientbibliothek verwenden

Die Implementierungsdetails im Großen und Ganzen hängen von der Programmiersprache ab. Wenn Sie die Clientbibliothek in Ihrer Anwendung verwenden möchten, müssen Sie zuerst Cloud Storage-Abhängigkeiten importieren. Im Node.js-Projekt werden Importe beispielsweise der Datei package.json hinzugefügt. Das folgende Snippet zeigt den Hinweis zur Datei „package.json“ dieses Labs.

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

In der Datei package.json ist google-cloud/storage als eine der Anwendungsabhängigkeiten aufgeführt.

Die Abhängigkeit google-cloud/functions-framework wird verwendet, um einen CloudEvent-Callback beim Functions Framework zu registrieren, der durch Cloud Storage-Ereignisse ausgelöst wird.

Die Abhängigkeit google-cloud/vision wird verwendet, um die Vision API aufzurufen, um Anmerkungen für die hochgeladenen Bilder abzurufen und so festzustellen, ob es sich um eine Nahrung handelt oder nicht.

CloudEvent-Callback registrieren

Registrieren Sie einen CloudEvent-Callback beim Functions Framework, der von Cloud Storage ausgelöst wird, wenn ein neues Bild in den Bucket hochgeladen wird.

index.js

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

Speicherreferenzobjekt erstellen

Nachdem die Clientbibliotheken importiert wurden, müssen Sie einen neuen Storage-Client und Buckets erstellen, mit denen Ihre Anwendung interagiert.

index.js

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

Mit dem obigen Code wird ein Speicherclient mit dem Namen „storage“ erstellt. und zwei Verweise auf Storage-Buckets, auf die durch die Variablen „bucket“ verwiesen wird und „thumbBucket“

Cloud Storage-Objekte herunterladen

index.js

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

Mit diesem grundlegenden Downloadverhalten können Sie unterbrochene Downloads fortsetzen und erweiterte Downloadstrategien wie aufgeteilte Objektdownloads und Streaming-Downloads anwenden.

Objekte in Cloud Storage hochladen

Sie können Uploadanfragen auf drei Arten an Cloud Storage senden: Einzelanfrage-, fortsetzbare oder mehrteilige XML API-Uploads. Verwenden Sie für größere Uploads oder Streaming-Uploads fortsetzbare Uploads. Bei der XML API werden Dateien in Teilen hochgeladen und zu einem einzigen Objekt zusammengesetzt. Verwenden Sie für kleinere Objekte Einzelanfrage-Uploads.

Mit dem folgenden Code wird ein Bild per Einzelanfrage in Cloud Storage hochgeladen.

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. Vision API einbinden

Mit Cloud Vision können Entwickler leicht Funktionen zur visuellen Erkennung in Anwendungen einbinden. Dazu zählen die Erkennung von Bildlabels, Gesichtern und Sehenswürdigkeiten, die optische Zeichenerkennung (Optical Character Recognition, OCR) sowie die Kennzeichnung expliziter Inhalte.

Clientbibliothek installieren

Cloud-Clientbibliotheken sind in vielen gängigen Programmiersprachen verfügbar. Damit Sie die Bibliotheken verwenden können, müssen Sie die Clientbibliothek installieren.

Image-Annotator-Client erstellen

Um mithilfe der offiziellen Client-SDKs auf Google APIs zuzugreifen, erstellen Sie ein Dienstobjekt, das auf dem Discovery-Dokument der API basiert, in dem die API für das SDK beschrieben wird. Sie müssen sie mithilfe Ihrer Anmeldedaten aus dem Discovery-Dienst der Vision API abrufen.

index.js

const client = new vision.ImageAnnotatorClient();

Standardmäßig authentifiziert sich der Client mit der Dienstkontodatei, die in der Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS angegeben ist.

Vision API-Anfrage erstellen

Die Vision API kann eine Elementerkennung in einer Bilddatei durchführen. Dazu sendet sie den Inhalt der Bilddatei als Base64-codierten String in den Text Ihrer Anfrage.

Zum Erstellen einer Anfrage mit der Image-Ressource zum Annotieren Ihres Images. Die Anfrage an diese API erfolgt in Form eines Objekts mit einer Anfrageliste. Jedes Element der Liste enthält zwei Informationen:

• Die Bilddaten mit Base64-Codierung
• Eine Liste der Elemente, die Sie zu diesem Bild annotieren möchten

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. Cloud Functions-Funktion bereitstellen

Dieser Dienst zur Größenanpassung von Bildern ist Teil des größeren Cymbal Eats-Systems. In diesem Abschnitt stellen Sie nur die Komponenten bereit, die für die Bildverarbeitungsfunktion relevant sind. Die vollständige Installation umfasst eine Benutzeroberfläche zum Hochladen des Images und eine nachgelagerte Anfrage zum Speichern der resultierenden Metadaten. Diese Funktionen werden im Rahmen dieses Labs nicht installiert.

Die folgenden Komponenten werden während der Funktionsbereitstellung erstellt:

• Cloud Functions-Funktion
• Cloud Run-Dienst
• Eventarc-Trigger
• Pub/Sub-Thema und -Abo

Führen Sie im Cloud Shell-Terminal den folgenden Befehl aus, um die Cloud Functions-Funktion mit einem Trigger-Bucket im menu-item-uploads-$PROJECT_ID bereitzustellen:

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

Wenn die Bereitstellung aufgrund eines Berechtigungsproblems mit dem Storage-Bucket zum Hochladen fehlschlägt, warten Sie, bis die IAM-Änderungen aus dem vorherigen Schritt übernommen wurden. Das dauert in der Regel 1–2 Minuten und wiederholt dann die Bereitstellung.

Beispielausgabe

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

Sehen Sie sich in der Cloud Console die erstellte Cloud Functions-Funktion an:

Sehen Sie sich in der Cloud Console den Cloud Run-Dienst an, der für die Funktion erstellt wurde:

Prüfen Sie in der Cloud Console den Eventarc-Trigger, der für die Funktion erstellt wurde:

Sehen Sie sich in der Cloud Console das Pub/Sub-Thema und das Abo an, die für den Eventarc-Trigger erstellt wurden:

9. End-to-End-Lösung testen und validieren

Laden Sie ein neues Foto in Cloud Storage hoch und überwachen Sie den Fortschritt der Pipeline, während die Bilder analysiert werden. Sie testen die End-to-End-Lösung, indem Sie Cloud Functions-Logs überwachen.

Geeignetes Bild hochladen

Hinweis:Das Foto von Tom Dillon auf Unsplash darf mit der Unsplash-Lizenz kostenlos verwendet werden.

1. Speichern Sie dieses Image auf Ihrem lokalen Computer.
2. Benennen Sie die Datei in 1.jpg um.
3. Öffnen Sie die Cloud Storage-Konsole.
4. Klicken Sie auf den Bucket menu-item-uploads-....
5. Klicken Sie auf DATEIEN HOCHLADEN.
6. 1.jpg in den Storage-Bucket hochladen
7. Rufen Sie in der Cloud Console Cloud Functions auf.
8. Klicken Sie auf process-thumbails.
9. Klicken Sie auf den Tab LOGS.

Hinweis:Die Funktion wurde erfolgreich ausgeführt und das Bild wurde in den Bucket für Miniaturansichten geladen. Basierend auf den Vision API-Labels für das hochgeladene Bild wird der Status des Menüelements auf „Bereit“ gesetzt. Das bedeutet, dass die Vision API das Bild als „Lebensmittel“ annotiert hat. Da wir den Menüdienst nicht bereitgestellt haben, ist die Anfrage zum Aktualisieren des Menüelements fehlgeschlagen.

10. Rufen Sie den Cloud Storage-Bucket menu-item-thumbnails-$PROJECT_ID auf.
11. Prüfen, ob die Miniaturansicht im Bucket für Miniaturansichten erstellt wurde

Nicht-Food-Bild hochladen

Um zu überprüfen, ob die Funktion richtig funktioniert, laden Sie ein Bild hoch, das kein Objekt enthält, das als „Lebensmittel“ klassifiziert würde ein.

Hinweis: Das Foto von Insung Yoon auf Unsplash darf mit der Unsplash-Lizenz kostenlos verwendet werden.

1. Speichern Sie dieses Image auf Ihrem lokalen Computer.
2. Benennen Sie die Datei in 2.jpg um.
3. Öffnen Sie die Cloud Storage-Konsole.
4. Klicken Sie auf den Bucket menu-item-uploads-....
5. Klicken Sie auf DATEIEN HOCHLADEN.
6. 2.jpg in den Storage-Bucket hochladen
7. Rufen Sie in der Cloud Console Cloud Functions auf.
8. Klicken Sie auf process-thumbails.
9. Klicken Sie auf den Tab LOGS.

Hinweis:Die Funktion wurde erfolgreich ausgeführt und das Bild wurde in den Bucket für Miniaturansichten hochgeladen. Basierend auf den Vision API-Labels für das hochgeladene Bild wird der Status des Menüelements auf „Fehlgeschlagen“ gesetzt. Das bedeutet, dass die Vision API das Bild nicht als „Lebensmittel“ annotiert hat.

Da der Menüdienst in diesem Lab nicht bereitgestellt wurde, ist die Anfrage zum Aktualisieren des Menüelements fehlgeschlagen.

10. Glückwunsch!

Sie haben das Lab abgeschlossen.

Nächste Schritte:

Weitere Codelabs von Cymbal Eats:

• Cloud Workflows mit Eventarc auslösen
• Verbindung zu Private CloudSQL über Cloud Run herstellen
• Verbindung zu vollständig verwalteten Datenbanken über Cloud Run herstellen
• Sichere serverlose Anwendung mit Identity-Aware Proxy (IAP)
• Cloud Run-Jobs mit Cloud Scheduler auslösen
• Sichere Bereitstellung in Cloud Run
• Eingehenden Cloud Run-Traffic sichern
• Verbindung zu privater AlloyDB über GKE Autopilot herstellen

Bereinigen

Damit Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen nicht in Rechnung gestellt werden, können Sie entweder das Projekt löschen, das die Ressourcen enthält, oder das Projekt beibehalten und die einzelnen Ressourcen löschen.

Projekt löschen

Am einfachsten vermeiden Sie weitere Kosten durch Löschen des für die Anleitung erstellten Projekts.