Cloud Functions-Funktionen mit Cloud Tasks auslösen

In dieser Anleitung erfahren Sie, wie Sie mit Cloud Tasks in einer App Engine-Anwendung eine Cloud Function auslösen und eine geplante E-Mail senden.

Lernziele

Machen Sie sich mit dem Code der einzelnen Komponenten vertraut.
Ein SendGrid-Konto erstellen
Herunterladen des Quellcodes
Stellen Sie eine Cloud Functions-Funktion bereit, um Cloud Tasks-Anfragen zu empfangen und eine E-Mail über die SendGrid API zu senden.
Erstellen Sie eine Cloud Tasks-Warteschlange.
Erstellen Sie ein Dienstkonto, um Ihre Cloud Tasks-Anfragen zu authentifizieren.
Stellen Sie den Clientcode bereit, mit dem ein Nutzer eine E-Mail senden kann.

Kosten

Cloud Tasks, Cloud Functions und App Engine haben eine kostenlose Stufe. Solange Sie die Anleitung innerhalb der kostenlosen Stufe der angegebenen Produkte ausführen, sollten keine zusätzlichen Kosten anfallen. Weitere Informationen finden Sie unter Preise.

Hinweise

Wählen Sie ein Google Cloud-Projekt aus oder erstellen Sie eines.

Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

Zur Seite "App Engine"
Initialisieren Sie eine App Engine-Anwendung in Ihrem Projekt:
1. Klicken Sie auf der Seite Willkommen bei App Engine auf Anwendung erstellen.
2. Wählen Sie eine Region für Ihre Anwendung aus. Notieren Sie diesen Standort. Er wird als LOCATION_ID-Parameter für Ihre Cloud Tasks-Anfragen verwendet. Die zwei Standorte der App Engine-Befehle europe-west und us-central werden in den Cloud Tasks-Befehlen europe-west1 und us-central1 genannt.
3. Wählen Sie Node.js als Sprache und Standard als Umgebung aus.
4. Falls das Pop-up-Fenster Abrechnung aktivieren angezeigt wird, wählen Sie Ihr Rechnungskonto aus. Wenn Sie noch kein Rechnungskonto haben, klicken Sie auf Rechnungskonto erstellen und folgen Sie den Anweisungen des Assistenten.
5. Klicken Sie auf der Seite Erste Schritte auf Nächste. Sie werden sich später darum kümmern.
Aktivieren Sie die Cloud Functions API und die Cloud Tasks API.

APIs aktivieren
Installieren und initialisieren Sie die gcloud CLI.

Code verstehen

In diesem Abschnitt werden der App-Code und dessen Funktionsweise erläutert.

Aufgabe erstellen

Die Indexseite wird mithilfe von Handlern in app.yaml bereitgestellt. Die für die Aufgabenerstellung erforderlichen Variablen werden als Umgebungsvariablen übergeben.

runtime: nodejs16

env_variables:
  QUEUE_NAME: "my-queue"
  QUEUE_LOCATION: "us-central1"
  FUNCTION_URL: "https://<region>-<project_id>.cloudfunctions.net/sendEmail"
  SERVICE_ACCOUNT_EMAIL: "<member>@<project_id>.iam.gserviceaccount.com"

# Handlers for serving the index page.
handlers:
  - url: /static
    static_dir: static
  - url: /
    static_files: index.html
    upload: index.html

Dieser Code erstellt den Endpunkt /send-email. Dieser Endpunkt verarbeitet Formularübermittlungen von der Indexseite und leitet diese Daten an den Aufgabenerstellungscode weiter.

app.post('/send-email', (req, res) => {
  // Set the task payload to the form submission.
  const {to_name, from_name, to_email, date} = req.body;
  const payload = {to_name, from_name, to_email};

  createHttpTaskWithToken(
    process.env.GOOGLE_CLOUD_PROJECT,
    QUEUE_NAME,
    QUEUE_LOCATION,
    FUNCTION_URL,
    SERVICE_ACCOUNT_EMAIL,
    payload,
    date
  );

  res.status(202).send('📫 Your postcard is in the mail! 💌');
});

Dieser Code erstellt die Aufgabe und sendet sie an die Cloud Tasks-Warteschlange. So erstellt der Code die Aufgabe:

Angabe des Zieltyps als HTTP Request.
Angabe des zu verwendenden HTTP method und des URL des Ziels.
Einstellen der Content-Type header to application/json Downstream-Anwendungen kann die strukturierte Nutzlast parsen.
E-Mail-Konto für Dienstkonto hinzufügen, damit Cloud Tasks Anmeldedaten für das Anforderungsziel bereitstellen kann, für das eine Authentifizierung erforderlich ist. Das Dienstkonto wird separat erstellt.
Prüfen, ob die Nutzereingabe für das Datum innerhalb der maximalen 30 Tage liegt, und der Anfrage als Feld scheduleTime hinzufügen.

const MAX_SCHEDULE_LIMIT = 30 * 60 * 60 * 24; // Represents 30 days in seconds.

const createHttpTaskWithToken = async function (
  project = 'my-project-id', // Your GCP Project id
  queue = 'my-queue', // Name of your Queue
  location = 'us-central1', // The GCP region of your queue
  url = 'https://example.com/taskhandler', // The full url path that the request will be sent to
  email = '<member>@<project-id>.iam.gserviceaccount.com', // Cloud IAM service account
  payload = 'Hello, World!', // The task HTTP request body
  date = new Date() // Intended date to schedule task
) {
  // Imports the Google Cloud Tasks library.
  const {v2beta3} = require('@google-cloud/tasks');

  // Instantiates a client.
  const client = new v2beta3.CloudTasksClient();

  // Construct the fully qualified queue name.
  const parent = client.queuePath(project, location, queue);

  // Convert message to buffer.
  const convertedPayload = JSON.stringify(payload);
  const body = Buffer.from(convertedPayload).toString('base64');

  const task = {
    httpRequest: {
      httpMethod: 'POST',
      url,
      oidcToken: {
        serviceAccountEmail: email,
        audience: url,
      },
      headers: {
        'Content-Type': 'application/json',
      },
      body,
    },
  };

  const convertedDate = new Date(date);
  const currentDate = new Date();

  // Schedule time can not be in the past.
  if (convertedDate < currentDate) {
    console.error('Scheduled date in the past.');
  } else if (convertedDate > currentDate) {
    const date_diff_in_seconds = (convertedDate - currentDate) / 1000;
    // Restrict schedule time to the 30 day maximum.
    if (date_diff_in_seconds > MAX_SCHEDULE_LIMIT) {
      console.error('Schedule time is over 30 day maximum.');
    }
    // Construct future date in Unix time.
    const date_in_seconds =
      Math.min(date_diff_in_seconds, MAX_SCHEDULE_LIMIT) + Date.now() / 1000;
    // Add schedule time to request in Unix time using Timestamp structure.
    // https://googleapis.dev/nodejs/tasks/latest/google.protobuf.html#.Timestamp
    task.scheduleTime = {
      seconds: date_in_seconds,
    };
  }

  try {
    // Send create task request.
    const [response] = await client.createTask({parent, task});
    console.log(`Created task ${response.name}`);
    return response.name;
  } catch (error) {
    // Construct error for Stackdriver Error Reporting
    console.error(Error(error.message));
  }
};

module.exports = createHttpTaskWithToken;

E-Mail erstellen

Mit diesem Code wird die Cloud Functions-Funktion erstellt, die das Ziel für die Cloud Tasks-Anfrage ist. Es verwendet den Anfragetext, um eine E-Mail zu erstellen und über die SendGrid API zu senden.

const sendgrid = require('@sendgrid/mail');

/**
 * Responds to an HTTP request from Cloud Tasks and sends an email using data
 * from the request body.
 *
 * @param {object} req Cloud Function request context.
 * @param {object} req.body The request payload.
 * @param {string} req.body.to_email Email address of the recipient.
 * @param {string} req.body.to_name Name of the recipient.
 * @param {string} req.body.from_name Name of the sender.
 * @param {object} res Cloud Function response context.
 */
exports.sendEmail = async (req, res) => {
  // Get the SendGrid API key from the environment variable.
  const key = process.env.SENDGRID_API_KEY;
  if (!key) {
    const error = new Error(
      'SENDGRID_API_KEY was not provided as environment variable.'
    );
    error.code = 401;
    throw error;
  }
  sendgrid.setApiKey(key);

  // Get the body from the Cloud Task request.
  const {to_email, to_name, from_name} = req.body;
  if (!to_email) {
    const error = new Error('Email address not provided.');
    error.code = 400;
    throw error;
  } else if (!to_name) {
    const error = new Error('Recipient name not provided.');
    error.code = 400;
    throw error;
  } else if (!from_name) {
    const error = new Error('Sender name not provided.');
    error.code = 400;
    throw error;
  }

  // Construct the email request.
  const msg = {
    to: to_email,
    from: 'postcard@example.com',
    subject: 'A Postcard Just for You!',
    html: postcardHTML(to_name, from_name),
  };

  try {
    await sendgrid.send(msg);
    // Send OK to Cloud Task queue to delete task.
    res.status(200).send('Postcard Sent!');
  } catch (error) {
    // Any status code other than 2xx or 503 will trigger the task to retry.
    res.status(error.code).send(error.message);
  }
};

Anwendung vorbereiten

SendGrid einrichten

Ein SendGrid-Konto erstellen
- Das können Sie entweder über die SendGrid-Website tun
- oder mit dem Google Cloud Launcher, der für Sie ein Konto erstellt und die Abrechnung übernimmt. Weitere Informationen finden Sie unter Ein SendGrid-Konto mit Cloud Launcher erstellen.
Erstellen Sie einen SendGrid API-Schlüssel:
1. Melden Sie sich bei Ihrem SendGrid-Konto an.
2. Öffnen Sie im linken Navigationsbereich Einstellungen und klicken Sie auf API-Schlüssel.
3. Klicken Sie auf API-Schlüssel erstellen und wählen Sie den eingeschränkten Zugriff aus. Wählen Sie unter dem Header E-Mail senden Vollständiger Zugriff aus.
4. Kopieren Sie den API-Schlüssel (er wird nur einmal angezeigt) in ein Dokument, um am Ende der Anleitung, wenn Sie die Cloud Functions-Funktionen aufrufen, darauf zurückgreifen zu können.

Quellcode herunterladen

Klonen Sie das Repository der Beispiel-App auf Ihren lokalen Computer:

git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

Wechseln Sie in das Verzeichnis, das den Beispielcode enthält:
```
cd cloud-tasks/
```

Cloud-Funktion bereitstellen

Rufen Sie das Verzeichnis function/ auf:
```
cd function/
```
Die Funktion bereitstellen:
```
gcloud functions deploy sendEmail --runtime nodejs14 --trigger-http \
  --no-allow-unauthenticated \
  --set-env-vars SENDGRID_API_KEY=SENDGRID_API_KEY \
```
Ersetzen Sie SENDGRID_API_KEY durch Ihren API-Schlüssel.

Dieser Befehl verwendet Flags:
- --trigger-http, um den Cloud Functions-Triggertyp anzugeben.
- --no-allow-unauthenticated, um anzugeben, dass der Funktionsaufruf eine Authentifizierung erfordert.
- --set-env-var, um Ihre SendGrid-Anmeldedaten festzulegen
Hinweis: Sie können Cloud Functions sowohl über die Firebase Console als auch über die Google Cloud Console verwalten. Das Schreiben und Bereitstellen über die FirebaseUI kann repliziert werden. Der Funktionscode muss jedoch mit dem Firebase-Funktionsframework übereinstimmen. Weitere Informationen zu den ersten Schritten mit Firebase-Funktionen und HTTP-Triggern
Legen Sie die Zugriffssteuerung für die Funktion so fest, dass nur authentifizierte Nutzer zugelassen werden.
1. Wählen Sie in der Cloud Functions-Benutzeroberfläche die Funktion sendEmail aus.
2. Wenn Sie keine Informationen zu Berechtigungen für sendEmail sehen, klicken Sie rechts oben auf Infofeld ansehen.
3. Klicken Sie oben auf die Schaltfläche Hauptkonten hinzufügen.
4. Legen Sie Neue Hauptkonten auf allAuthenticatedUsers fest.
5. Legen Sie die Rolle fest.
  - Funktionen der ersten Generation (1. Generation):Legen Sie die Rolle auf Cloud Function Invoker fest.
  - Funktionen der zweiten Generation (2. Generation):Legen Sie die Rolle auf Cloud Run Invoker fest.
6. Klicken Sie auf SPEICHERN.

Cloud Tasks-Warteschlange erstellen

Erstellen Sie eine Warteschlange mit dem folgenden Befehl gcloud:
```
gcloud tasks queues create my-queue --location=LOCATION
```
Ersetzen Sie LOCATION durch den gewünschten Speicherort für die Warteschlange, z. B. us-west2. Wenn Sie den Speicherort nicht angeben, wählt die gcloud CLI die Standardeinstellung aus.
Prüfen Sie, ob sie erfolgreich erstellt wurde:
```
gcloud tasks queues describe my-queue --location=LOCATION
```
Ersetzen Sie LOCATION durch den Speicherort der Warteschlange.

Dienstkonto erstellen

Die Cloud Tasks-Anfrage muss Anmeldedaten im Authorization-Header angeben, damit die Cloud-Funktion die Anfrage authentifizieren kann. Mit diesem Dienstkonto kann Cloud Tasks zu diesem Zweck ein OIDC-Token erstellen und hinzufügen.

Klicken Sie in der Benutzeroberfläche für Dienstkonten auf + DIENSTKONTO ERSTELLEN.
Fügen Sie einen Dienstkontonamen(Anzeigename) hinzu und wählen Sie Erstellen aus.
Legen Sie die Rolle fest und klicken Sie auf Weiter.
- Funktionen der ersten Generation (1. Generation):Legen Sie die Rolle auf Cloud Function Invoker fest.
- Funktionen der zweiten Generation (2. Generation):Legen Sie die Rolle auf Cloud Run Invoker fest.
Wählen Sie Fertig aus.

Endpunkt und Aufgabenersteller in App Engine bereitstellen

Gehen Sie zum Verzeichnis app/:
```
cd ../app/
```

Aktualisieren Sie Variablen in app.yaml mit Ihren Werten:

env_variables:
  QUEUE_NAME: "my-queue"
  QUEUE_LOCATION: "us-central1"
  FUNCTION_URL: "https://<region>-<project_id>.cloudfunctions.net/sendEmail"
  SERVICE_ACCOUNT_EMAIL: "<member>@<project_id>.iam.gserviceaccount.com"

Verwenden Sie den folgenden Befehl, um den Speicherort Ihrer Warteschlange zu ermitteln:

gcloud tasks queues describe my-queue --location=LOCATION

Ersetzen Sie LOCATION durch den Speicherort der Warteschlange.

Verwenden Sie den folgenden Befehl, um die Funktions-URL zu ermitteln:

gcloud functions describe sendEmail

Stellen Sie die Anwendung mit dem folgenden Befehl in der App Engine-Standardumgebung bereit:
```
gcloud app deploy
```
Öffnen Sie die Anwendung, um eine Postkarte als E-Mail zu senden:
```
gcloud app browse
```

Bereinigen

Nachdem Sie die Anleitung abgeschlossen haben, können Sie die erstellten Ressourcen bereinigen, damit sie keine Kontingente mehr nutzen und keine Gebühren mehr anfallen. In den folgenden Abschnitten erfahren Sie, wie Sie diese Ressourcen löschen oder deaktivieren.

Ressourcen löschen

Sie können die Ressourcen bereinigen, die Sie in Google Cloud erstellt haben, damit diese kein Kontingent verbrauchen und Ihnen in Zukunft nicht in Rechnung gestellt werden. In den folgenden Abschnitten wird erläutert, wie Sie diese Ressourcen löschen oder deaktivieren.

Cloud Functions-Funktion löschen

Rufen Sie in der Google Cloud Console die Seite Cloud Functions auf.

Zur Seite "Cloud Functions"
Klicken Sie die Kästchen neben Ihren Funktionen an.
Klicken Sie oben auf der Seite auf Löschen und bestätigen Sie den Löschvorgang.

Cloud Tasks-Warteschlange löschen

Öffnen Sie in der Console die Seite mit den Cloud Tasks-Warteschlangen.

Weiter zur Seite mit den Cloud Tasks-Warteschlangen
Wählen Sie den Namen der Warteschlange aus, die Sie löschen möchten, und klicken Sie auf Warteschlange löschen.
Bestätigen Sie die Aktion.

Hinweis: Wenn Sie eine Warteschlange über die Google Cloud Console löschen, können Sie erst nach sieben Tagen eine Warteschlange mit dem gleichen Namen erstellen.

Projekt löschen

Am einfachsten vermeiden Sie weitere Kosten, wenn Sie das zum Ausführen der Anleitung erstellte Projekt löschen.

So löschen Sie das Projekt:

Achtung: Das Löschen von Projekten hat folgende Auswirkungen:

Alle Inhalte des Projekts werden gelöscht. Wenn Sie für die Aufgaben in diesem Dokument ein bereits bestehendes Projekt verwendet haben und dieses löschen, werden auch alle anderen im Rahmen des Projekts erstellten Daten gelöscht.
Benutzerdefinierte Projekt-IDs gehen verloren. Beim Erstellen dieses Projekts haben Sie möglicherweise eine benutzerdefinierte Projekt-ID erstellt, die Sie weiterhin verwenden möchten. Damit die URLs, die die Projekt-ID nutzen, z. B. eine appspot.com-URL, erhalten bleiben, sollten Sie ausgewählte Ressourcen innerhalb des Projekts löschen, statt das gesamte Projekt.

Wenn Sie mehrere Architekturen, Anleitungen und Kurzanleitungen durcharbeiten möchten, können Sie die Überschreitung von Projektkontingenten verhindern, indem Sie Projekte wiederverwenden.

Wechseln Sie in der Google Cloud Console zur Seite Ressourcen verwalten.
Zur Seite „Ressourcen verwalten“
Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie dann auf Löschen.
Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie auf Shut down (Beenden), um das Projekt zu löschen.

Nächste Schritte

Weitere Informationen zum Erstellen von HTTP-Zielaufgaben
Weitere Informationen zum Konfigurieren Ihrer Cloud Tasks-Warteschlange