Wie man eine externe API aus Workspace Studio aufruft

Ein Workflow in Google Workspace Studio benötigt möglicherweise Daten von außerhalb von Gmail, Drive oder Chat: beispielsweise einen Bestellstatus, eine Zahl aus einer Datenbank oder eine Antwort eines internen Tools. Um diese Daten abzurufen oder Informationen an einen anderen Dienst zu senden, können Sie den entsprechenden Schritt hinzufügen. Senden Sie einen WebhookDies sendet eine HTTP-Anfrage an die Adresse einer von Ihnen angegebenen API.

Sie müssen den Gemini-Funktionsaufruf für diese Anfrage nicht konfigurieren. In Workspace Studio führt der Flow den Webhook-Schritt aus und empfängt die Antwort. Anschließend können Sie diese Antwort bei Bedarf an einen anderen Schritt weiterleiten, um sie zusammenzufassen, Daten zu extrahieren oder das Ergebnis zu kommunizieren.

Was Sie vor der Verbindung mit einer API benötigen

Im ersten Schritt muss überprüft werden, ob Ihre Organisation Webhooks verwenden kann. Die Funktion befindet sich in begrenzte Vorschau und ist standardmäßig deaktiviert. Ein Administrator muss sich anmelden. Anwendungen > Google Workspace > Workspace Studio > Webhook-Einstellungen und es für die entsprechende Organisationseinheit aktivieren.

In einigen Editionen kann der Administrator die Verbindungen auch auf eine einzige beschränken. Liste der zulässigen Domains und URLsWenn der Schritt in Studio angezeigt wird, aber keine Kommunikation mit Ihrer API möglich ist, überprüfen Sie, ob die Zieladresse autorisiert ist. Standardmäßig müssen Benutzer Aktionen, die Webhooks verwenden, den Schritt vor der Ausführung prüfen und bestätigen.

Vom externen Dienst benötigen Sie die URL, die unterstützten HTTP-Methoden und das erwartete Datenformat. Prüfen Sie außerdem die Authentifizierungsmethode: Eine öffentliche, schreibgeschützte API hat andere Anforderungen als eine private API, die Token oder spezielle Header erfordert.

Schritt für Schritt zum Aufruf einer API aus Workspace Studio

Eingeben studio.workspace.google.com Erstellen Sie einen Workflow mit dem gewünschten Auslöser. Sie können ihn beispielsweise starten, sobald eine E-Mail eingeht, die bestimmte Bedingungen erfüllt. Gehen Sie dann wie folgt vor:

1. Drücken Schritt hinzufügen und auswählen Senden Sie einen Webhook.
2. Geben Sie die Vollständige URL der API, einschließlich des Präfixes https://Die Adresse muss korrigiert werden: Dieses Feld unterstützt keine Flow-Variablen.
3. Wählen Sie die HTTP-Methode. ERHALTEN Es dient zur Abfrage von Daten; POSTSie können sie senden oder einen Datensatz erstellen. Sie sind auch verfügbar PUT, PATCH und DELETE.
4. Falls die API einen Body erfordert, schreiben Sie ihn in das Inhaltsfeld oder NutzlastGoogle empfiehlt die Verwendung von JSON, wenn der empfangende Dienst dies erwartet.
5. Stelle ein TestausführungÜberprüfen Sie das Ergebnis und aktivieren Sie den Ablauf, sobald Sie sich vergewissert haben, dass er funktioniert.

Denken Sie daran, dass der Test führe die Aktion ausWenn Sie einen POST-Request zum Erstellen eines Datensatzes oder einen DELETE-Request zum Löschen eines Datensatzes konfigurieren, verwenden Sie zunächst eine Testumgebung oder Testdaten, die Sie problemlos ändern können.

Beispiel: Senden einer Benachrichtigung an ein externes Tool

Stellen Sie sich vor, Ihr Team verfügt über eine API, die Warnmeldungen erstellt in https://api.ejemplo.com/v1/avisosDiese Adresse lautet: illustrativSie müssen es durch das Ihres Dienstes ersetzen. Wenn dessen Dokumentation angibt, dass er POST-Anfragen mit einem JSON-Body akzeptiert, können Sie den Schritt mit folgendem Inhalt konfigurieren: {"tipo":"nuevo_correo","origen":"Workspace Studio"}.

Sie können auch ein/e einfügen Durchflussvariable Im Nachrichtentext können Sie beispielsweise den Betreff der auslösenden E-Mail einfügen. Verwenden Sie dazu den Variablenselektor von Studio und überprüfen Sie das Ergebnis: Enthält der eingefügte Text Anführungszeichen oder andere Sonderzeichen, kann dies zu fehlerhaftem JSON führen. Variablen können zwar im Inhalt verwendet werden, aber nicht im URL-Feld.

Wenn Sie Daten abrufen müssen, wählen Sie GET und geben Sie eine feste URL ein, die bereits die erforderlichen Parameter enthält. Workspace Studio ignoriert jeglichen Inhalt, den Sie im Body einer GET-Anfrage angegeben haben.

Was tun mit der API-Antwort?

Der Webhook-Schritt verlässt die Serviceantwort als Text in einer Variable, die für nachfolgende Schritte verfügbar ist. Sie können sie verwenden, um eine Benachrichtigung zu senden, eine Zusammenfassung zu schreiben oder einen KI-Schritt aufzufordern, bestimmte Daten zu extrahieren.

Wenn die API beispielsweise den Status einer Bestellung zurückgibt, kann der nächste Schritt diesen Status an das Team weitergeben. Wählen Sie die Variable, die die Antwort enthält, explizit aus: Nachfolgende Schritte erhalten nicht automatisch alle Informationen, die zuvor im Ablauf verarbeitet wurden. Es empfiehlt sich, den zurückgegebenen Inhalt zu testen, bevor Sie Anweisungen schreiben, die davon abhängen.

Wenn die API eine Authentifizierung oder komplexere Logik erfordert

Die dokumentierte Basiskonfiguration für Senden Sie einen Webhook Es umfasst die URL, die Methode und optional einen Anfragetext. Falls Ihre Integration ein OAuth-Token benötigt, eine URL mit variablen Parametern erstellen, bestimmte Header hinzufügen oder eine Antwort transformieren muss, bevor sie fortfährt, prüfen Sie, ob dieser Schritt diese Anforderungen abdeckt.

Wenn das nicht ausreicht, besteht eine Möglichkeit darin, ein/eine/einen zu entwickeln Benutzerdefinierter Schritt für Workspace Studio über ein Plugin. In einer Google Apps Script-Implementierung wird der Dienst UrlFetchApp Es ermöglicht das Senden von Anfragen an externe APIs und das Verarbeiten von JSON-Antworten. Diese Lösung erfordert Entwicklungsaufwand und eine entsprechende Berechtigungskonfiguration; für einfache Anfragen, die der native Schritt bereits verarbeiten kann, ist sie nicht notwendig.

Vermeiden Sie es, private Schlüssel in sichtbare Felder des Datenflusses einzufügen oder in eine geteilte URL einzubetten. Prüfen Sie vor dem Senden von Daten aus Gmail, Chat oder Kalender, welche Informationen der externe Dienst erhält und ob er zur Verarbeitung dieser Daten berechtigt ist.

Wie man Fehler in einem Webhook findet

Wenn die Verbindung fehlschlägt, öffnen Sie den Tab Aktivität Im Ablauf können Sie die vollständige Fehlermeldung und die Antwort des Zielservers einsehen. Diese Informationen helfen, zwischen einem Konfigurationsproblem in Studio und einer von der API abgelehnten Anfrage zu unterscheiden.

• Der Schritt wird nicht angezeigt: Klären Sie mit Ihrem Administrator ab, ob Webhooks für Ihre Organisationseinheit aktiviert sind.
• Die URL ist blockiert: Prüfen Sie die Liste der zulässigen Adressen, falls Ihre Edition diese Einschränkung verwendet.
• Fehler 400: Prüfen Sie das Format des Nachrichtentextes und die von der API benötigten Felder.
• Fehler 401 oder 403: Prüfen Sie die vom Dienst geforderten Berechtigungen und Authentifizierungsmethoden.
• Fehler 429: Prüfen Sie, ob Sie das Anfragelimit für die Ziel-API überschritten haben.
• Fehler 500: Prüfen Sie den Status und die Aufzeichnungen des Dienstes, der die Anfrage erhalten hat.

Beachten Sie außerdem die allgemeinen Einschränkungen von Workspace Studio: Es unterstützt derzeit bis zu 25 Flows pro Benutzer y 20 Schritte pro AblaufDarüber hinaus gibt es ein kombiniertes Ausführungslimit, das alle 24 Stunden zurückgesetzt wird. Wenn mehrere Abläufe nicht mehr ausgeführt werden, überprüfen Sie deren Aktivität, bevor Sie den Fehler der API zuschreiben.

Bei den meisten einfachen HTTP-Verbindungen ist der Prozess unkompliziert: Webhook aktivieren, feste URL und korrekte Methode konfigurieren, Anfrage testen und die Antwort in den folgenden Schritten verwenden. Erfordert die Integration eine erweiterte Authentifizierung oder die Transformation von Daten per Code, empfiehlt sich die Vorbereitung eines benutzerdefinierten Schritts.