Ereignisverarbeitung aus Cloud Storage mit Eventarc- und Cloud Run-Funktionen auslösen

1. Übersicht

In diesem Lab erfahren Sie, wie Sie Cloud Storage-Bucket-Ereignisse und Eventarc verwenden, um die Ereignisverarbeitung auszulösen. Sie verwenden Cloud Run-Funktionen, 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

So erstellen Sie eine Pipeline für die Bildverarbeitung.

• Storage-Buckets konfigurieren
• Cloud Run-Funktion zum Lesen und Schreiben von Objekten in Cloud Storage erstellen
• Eventarc-Trigger bereitstellen
• Vision API zur Erkennung von Lebensmittelbildern einbinden
• 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 Run Functions oder der 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 Teilnehmer dieses Projekts. Es handelt sich um einen String, der nicht von Google APIs verwendet wird. Sie können sie jederzeit aktualisieren.
• Die Projekt-ID ist für alle Google Cloud-Projekte eindeutig und unveränderlich (kann nach dem Festlegen nicht mehr geändert werden). In der Cloud Console wird automatisch ein eindeutiger String generiert. Normalerweise ist es nicht wichtig, wie dieser String aussieht. In den meisten Codelabs müssen Sie auf Ihre Projekt-ID verweisen (in der Regel als PROJECT_ID angegeben). Wenn Ihnen die generierte ID nicht gefällt, können Sie eine andere zufällige ID generieren. Alternativ können Sie es mit einem eigenen Namen versuchen und sehen, 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: Es gibt einen dritten Wert, die Projektnummer, die von einigen APIs verwendet wird. Weitere Informationen zu diesen drei Werten

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

Hinweis:Wenn Sie ein Gmail-Konto verwenden, können Sie den Standardspeicherort auf Keine Organisation belassen. 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 die Abrechnung in der Cloud Console aktivieren, um Cloud-Ressourcen/-APIs zu verwenden. Die Durchführung dieses Codelabs kostet wenig oder gar nichts. Wenn Sie Ressourcen herunterfahren möchten, um Kosten zu vermeiden, die über diese Anleitung hinausgehen, können Sie die erstellten Ressourcen oder das Projekt löschen. Neue Google Cloud-Nutzer können am kostenlosen Testzeitraum mit einem Guthaben von 300$ teilnehmen.

Cloud Shell aktivieren

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

Umgebung einrichten

1. Erstellen Sie Projekt- und ressourcenbezogene Umgebungsvariablen, indem Sie die folgenden Befehle im Cloud Shell-Terminal ausführen.

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. 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. Repository klonen

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

3. Cloud Storage-Buckets konfigurieren

Storage-Buckets erstellen

Cloud Storage-Buckets für Uploads und Miniaturansichten für Ihre Pipeline zur Bildverarbeitung erstellen

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

1. Bucket zum Hochladen, in den Bilder zuerst hochgeladen werden
2. Bucket für Miniaturansichten zum Speichern der generierten Miniaturansichten

Bucket zum Hochladen neuer Bilder erstellen:

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

Beispielausgabe:

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

Erstellen Sie einen Bucket, um die generierten Miniaturansichten zu speichern:

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 Berechtigungen des Storage-Buckets, 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 wird empfohlen, den Zugriff auf Speicher-Buckets einzuschränken. Für dieses Lab dürfen alle Nutzer alle Objekte ansehen. Weitere Informationen zum Sichern von Speicher-Buckets finden Sie unter IAM-Berechtigungen 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 Cloud Functions zum Verarbeiten von Thumbnails:

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

Weisen Sie die Rolle artifactregistry.reader zu, 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"

Weisen Sie die Rolle storage.objectCreator zu, 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"

Weisen Sie die Rolle run.invoker zu, um den Aufruf des Cloud Run-Dienstes zu ermöglichen:

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, damit Ereignisse von Anbietern empfangen werden können:

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

Weisen Sie dem Cloud Storage-Dienstkonto die Rolle pubsub.publisher zu. 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. Funktionsübersicht zur Bildverarbeitung

Erstellen Sie eine Funktion zum Herunterladen eines Bildes aus Cloud Storage, zum Ändern der Größe des Bildes und zum erneuten Hochladen des Bildes in Cloud Storage. Die Funktion ruft die Vision API auf, um dem Bild ein Beschreibungslabel zuzuweisen. Die Funktion prüft das Label „Beschreibung“. Wenn das Label das Bild als „Lebensmittel“ identifiziert, wird ein Ereignis an den Menüdienst gesendet, um das Bild und das Thumbnail 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 wird.

Objekt finalisieren

„Object Finalize“-Ereignisse werden ausgelöst, wenn der 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. Archive- und Metadata-Update-Vorgä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 erleichtern die Integration mit 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. Bevor Sie die Bibliotheken verwenden können, müssen Sie die Clientbibliothek installieren.

Clientbibliothek verwenden

Die Implementierungsdetails hängen weitgehend 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 beispielsweise Importe in der Datei „package.json“ hinzugefügt. Das Snippet unten zeigt den Hinweis in der 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 google-cloud/vision-Abhängigkeit wird verwendet, um die Vision API aufzurufen und Anmerkungen für die hochgeladenen Bilder abzurufen, um festzustellen, ob es sich um ein Lebensmittel handelt.

CloudEvent-Callback registrieren

Registrieren Sie einen CloudEvent-Callback mit dem 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 Speicherclient und die Buckets erstellen, mit denen Ihre Anwendung interagieren soll.

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 Storage-Client namens „storage“ und zwei Verweise auf Storage-Buckets erstellt, auf die mit den Variablen „bucket“ und „thumbBucket“ verwiesen wird.

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 Segmentierte Objektdownloads und Streamingdownloads verwenden.

Objekte in Cloud Storage hochladen

Sie können Uploadanfragen auf drei Arten an Cloud Storage senden: als Einzelanfrage, als fortsetzbaren Upload oder als mehrteiligen XML API-Upload. Verwenden Sie für größere Uploads oder Streaming-Uploads fortsetzbare Uploads. Bei der XML API werden Dateien in Teilen hochgeladen und als einzelnes Objekt zusammengestellt. Verwenden Sie für kleinere Objekte Uploads mit einer einzelnen Anfrage.

Mit dem folgenden Code wird ein Bild mit einem Single-Request-Upload in Cloud Storage hochgeladen.

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. Vision API einbinden

Mit Cloud Vision können Entwickler auf einfache Weise Features zur visuellen Erkennung in Anwendungen einbinden. Hierzu zählen die Erkennung von Bildlabels, Gesichtern und Sehenswürdigkeiten, die optische Zeichenerkennung (Optical Character Recognition, OCR) sowie die Kennzeichnung anstößiger Inhalte mit Tags.

Clientbibliothek installieren

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

Image Annotator-Client erstellen

Für den Zugriff auf Google APIs mithilfe der offiziellen Client-SDKs erstellen Sie ein Dienstobjekt, das auf dem Discovery-Dokument der API basiert. Dieses Dokument enthält eine API-Beschreibung für das SDK. Sie müssen es unter Angabe Ihrer Anmeldedaten vom Discovery-Dienst der Vision API abrufen.

index.js

const client = new vision.ImageAnnotatorClient();

Standardmäßig wird der Client mit der Dienstkontodatei authentifiziert, die durch die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS angegeben wird.

Vision API-Anfrage erstellen

Die Vision API kann eine Elementerkennung für eine Bilddatei machen, indem sie den Inhalt der Bilddatei als Base64-codierten String an den Textkörper Ihrer Anfrage sendet.

So erstellen Sie eine Anfrage mit der Images-Ressource, um Ihr Bild zu annotieren: Eine Anfrage an diese API erfolgt in Form eines Objekts mit einer Liste von Anfragen. 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 Run-Funktionen bereitstellen

Dieser Dienst zum Anpassen der Bildgröße ist Teil des größeren Cymbal Eats-Systems. In diesem Abschnitt stellen Sie nur die Komponenten bereit, die mit der Bildverarbeitungsfunktion zusammenhängen. Die vollständige Installation umfasst eine Benutzeroberfläche zum Hochladen des Bildes und eine Downstream-Anfrage zum Speichern der resultierenden Metadaten. Diese Funktionen werden im Rahmen dieses Labs nicht installiert.

Während der Funktionsbereitstellung werden die folgenden Komponenten erstellt:

• Cloud Run-Funktionen
• Eventarc-Trigger
• Pub/Sub-Thema und ‑Abo

Führen Sie im Cloud Shell-Terminal den folgenden Befehl aus, um Cloud Run-Funktionen mit einem Trigger-Bucket für menu-item-uploads-$PROJECT_ID bereitzustellen:

Wenn Sie eine Cloud Run Functions-Funktion direkt in Cloud Run bereitstellen möchten, stellen Sie zuerst die Funktion bereit und erstellen dann einen Trigger dafür.

Stellen Sie die Cloud Run-Funktionen bereit:

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

Beispielausgabe:

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

Erstellen Sie den Trigger:

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"

Beispielausgabe:

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.

Wenn die Bereitstellung des Triggers aufgrund eines Berechtigungsproblems fehlschlägt, warten Sie, bis die IAM-Änderungen aus dem vorherigen Schritt wirksam werden. Das dauert in der Regel 1 bis 2 Minuten. Versuchen Sie dann noch einmal, die Bereitstellung durchzuführen.

Beispiel für Fehlerausgabe:

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

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 beobachten Sie den Fortschritt der Pipeline, während die Bilder analysiert werden. Sie testen die End-to-End-Lösung, indem Sie die Logs der Cloud-Funktionen überwachen.

Bild hochladen

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

1. Speichern Sie dieses Bild auf Ihrem lokalen Computer.
2. Benennen Sie die Datei 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. Laden Sie 1.jpg in den Storage-Bucket hoch.
7. Rufen Sie in der Cloud Console Cloud Run auf.
8. Klicken Sie auf process-thumbnails.
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üpunkts auf „Bereit“ gesetzt. Das bedeutet, dass die Vision API das Bild als „Food“ annotiert hat.

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

10. Wechseln Sie zum menu-item-thumbnails-$PROJECT_ID .
11. Prüfen, ob das Miniaturbild im Bucket „thumbnails“ erstellt wurde

Nicht lebensmittelbezogenes Bild hochladen

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

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

1. Speichern Sie dieses Bild auf Ihrem lokalen Computer.
2. Benennen Sie die Datei 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. Laden Sie 2.jpg in den Storage-Bucket hoch.
7. Rufen Sie in der Cloud Console Cloud Run auf.
8. Klicken Sie auf process-thumbnails.
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üpunkts auf „Fehler“ gesetzt. Das bedeutet, dass die Vision API das Bild nicht als „Food“ 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 zu Cymbal Eats:

• Cloud Workflows mit Eventarc auslösen
• Verbindung von Cloud Run zu privatem Cloud SQL herstellen
• Verbindung zu vollständig verwalteten Datenbanken über Cloud Run herstellen
• Serverlose Anwendung mit Identity-Aware Proxy (IAP) sichern
• Cloud Run-Jobs mit Cloud Scheduler auslösen
• Sichere Bereitstellung in Cloud Run
• Cloud Run-Ingress-Traffic sichern
• Verbindung zu privaten AlloyDB-Instanzen von 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.