Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Tworzenie niestandardowych kroków Google Workspace Studio w Node.js w Cloud Run

1. Wprowadzenie

Google Workspace Studio umożliwia automatyzację procesów biznesowych w aplikacjach Google Workspace, takich jak Gmail, Google Chat, Dysk Google i Arkusze Google. Jeśli przepływy pracy mają się rozpoczynać w zewnętrznej aplikacji internetowej lub mają uruchamiać niestandardową logikę we własnym środowisku chmurowym, możesz rozszerzyć Google Workspace Studio za pomocą dodatku do Google Workspace HTTP w Node.js na Cloud Run:

Niestandardowy krok początkowy (workflowTrigger): uruchamia przepływ Google Workspace Studio, gdy wystąpi zdarzenie zewnętrzne, np. klient prześle zgłoszenie w wewnętrznym portalu internetowym, wywołując interfejs API REST triggers.fire Google Workspace Studio.
Krok działania niestandardowego (workflowAction): odbiera zmienne z wcześniejszych kroków automatyzacji, uruchamia niestandardową logikę lub wnioskowanie AI w usłudze Node.js i zwraca zmienne wyjściowe do Google Workspace Studio.

W tym ćwiczeniu utworzysz i wdrożysz w Cloud Run pełne rozszerzenie HTTP Node.js dla Google Workspace Studio, użyjesz Cloud Firestore do utrwalania aktywnych subskrypcji wyzwalaczy przepływu i przesłanych zgłoszeń w różnych wersjach kontenera oraz sklasyfikujesz pilność zgłoszenia w niestandardowym kroku działania przy użyciu Gemini 3.8 Flash (gemini-3.8-flash) na platformie agentów Gemini Enterprise z odpornym mechanizmem rezerwowym dopasowywania słów kluczowych.

Co utworzysz

Aplikacja internetowa Support Quick Portal i dodatek HTTP do Google Workspace utworzone przy użyciu Node.js, Express i Firestore w Cloud Run.
Niestandardowy krok początkowy Nowy zgłoszenie (supportTicketTrigger), który przechowuje aktywne subskrypcje automatyzacji w studio_triggers kolekcji Firestore, rejestruje przesłane zgłoszenia w support_tickets kolekcji Firestore i jest uruchamiany za każdym razem, gdy zgłoszenie zostanie przesłane w portalu internetowym, przekazując ticketTitle i ticketDescription do automatyzacji Google Workspace Studio.
Niestandardowy krok działania Detect Urgency (urgencyDetectorStep), który klasyfikuje pilność zgłoszenia za pomocą Gemini 3.8 Flash (gemini-3.8-flash) na Gemini Enterprise Agent Platform (aiplatform.googleapis.com) z automatycznym przełączaniem na dopasowywanie słów kluczowych (urgent, blocker, critical).

Czego się nauczysz

Jak skonfigurować plik manifestu wdrożenia dodatku do Google Workspace HTTP (deployment.json) z elementami workflowTrigger i workflowAction.
Jak utrwalać subskrypcje wyzwalaczy Google Workspace Studio (triggerId, notifyUri i userOAuthToken) w studio_triggers kolekcji Firestore i uruchamiać przepływy za pomocą triggers.fire interfejsu REST API.
Jak utworzyć workflowAction krok niestandardowy w Node.js za pomocą strukturalnego wyjścia Gemini 3.8 Flash (gemini-3.8-flash) na platformie Gemini Enterprise Agent Platform z słowem kluczowym jako rezerwą.

Wymagania wstępne

Konto Google Workspace z dostępem do Google Workspace Studio.
Projekt Google Cloud z włączonym rozliczeniem, utworzony w tej samej organizacji Google Workspace co Twoje konto użytkownika, aby umożliwić Ci instalowanie nieopublikowanych wdrożeń dodatków na potrzeby testowania.

2. Konfigurowanie projektu Google Cloud i Firestore

W tym kroku skonfigurujesz ekran zgody OAuth w projekcie, włączysz wymagane interfejsy Google Cloud i Google Workspace API w Cloud Shell, udostępnisz bazę danych (default) Firestore i zainicjujesz konto usługi autoryzacji dodatku.

Otwórz konsolę Google Cloud, wybierz projekt w chmurze Google Cloud i kliknij ikonę Aktywuj Cloud Shell na górnym pasku nawigacyjnym.
Skonfiguruj ekran zgody OAuth, aby Google Workspace mógł udostępnić klienta OAuth dla Twojego dodatku:
1. Otwórz stronę marki Platformy uwierzytelniania Google.
2. W razie potrzeby kliknij Rozpocznij. (Jeśli ekran zgody jest już skonfigurowany, przejdź do kroku 3).
3. W sekcji Informacje o aplikacji wpisz Support Extension w polu Nazwa aplikacji, wybierz Adres e-mail dla użytkowników potrzebujących pomocy i kliknij Dalej.
4. W sekcji Odbiorcy wybierz Wewnętrzny i kliknij Dalej.
5. W sekcji Informacje kontaktowe wpisz swój adres e-mail i kliknij Dalej.
6. W sekcji Zakończ zaakceptuj zasady dotyczące danych użytkownika w usługach interfejsu API Google, kliknij Dalej, a potem Utwórz.

W Cloud Shell ustaw aktywny projekt w chmurze (zastąp YOUR_PROJECT_ID identyfikatorem projektu Google Cloud) i włącz wymagane interfejsy API:

gcloud config set project YOUR_PROJECT_ID
gcloud services enable \
  aiplatform.googleapis.com \
  firestore.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  appsmarket-component.googleapis.com \
  gsuiteaddons.googleapis.com \
  workspacestudio.googleapis.com

Utwórz bazę danych (default) Firestore w us-central1 (jeśli jeszcze nie istnieje) i zainicjuj konto usługi dodatków do Google Workspace:

gcloud firestore databases describe --database="(default)" >/dev/null 2>&1 || \
  gcloud firestore databases create \
    --database="(default)" \
    --location=us-central1 \
    --type=firestore-native \
    --quiet
gcloud workspace-add-ons get-authorization

3. Tworzenie aplikacji Node.js z Firestore i Gemini 1.5 Flash

W tym kroku utworzysz aplikację Node.js w ~/studio-support-addon. Aby kod był modułowy i czytelny, projekt jest podzielony na 5 plików:

firestore.js: inicjuje klienta Cloud Firestore (kolekcje studio_triggers i support_tickets) i odświeża tokeny OAuth w pamięci podręcznej.
starter.js: implementuje niestandardowe webhooki kroku początkowego Nowe zgłoszenie (/onConfigTrigger i /onManageTrigger).
action.js: wdraża wywołania zwrotne webhooków kroku działania niestandardowego Wykrywanie pilności (/onConfigUrgency i /onExecuteUrgency) za pomocą Gemini 3.8 Flash (gemini-3.8-flash) z mechanizmem rezerwowym dopasowywania słów kluczowych.
portal.js: obsługuje interfejs internetowy Szybkiego portalu pomocy (GET /) i aktywuje wyzwalacze Google Workspace Studio (POST /api/submit-ticket).
index.js: łączy wszystkie trasy Express i uruchamia serwer HTTP.

Zainicjuj projekt i `package.json`.

Utwórz katalog projektu i przejdź do niego:

mkdir -p ~/studio-support-addon && cd ~/studio-support-addon

Utwórz package.json za pomocą express, @google-cloud/firestore i @google/genai:

cat << 'EOF' > package.json
{
  "name": "studio-support-addon",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "@google-cloud/firestore": "^7.11.0",
    "@google/genai": "^1.0.0",
    "express": "^4.21.2"
  }
}
EOF

`firestore.js` – udostępniony stan Firestore i odświeżanie tokena OAuth

Utwórz firestore.js, aby zarządzać 2 kolekcjami Firestore i aktualizować tokeny OAuth użytkowników w pamięci podręcznej:

studio_triggers: przechowuje aktywne subskrypcje przepływów Google Workspace Studio (triggerId, notifyUri i userOAuthToken), dzięki czemu przetrwają ponowne uruchomienia kontenerów Cloud Run i zdarzenia skalowania do zera.
support_tickets: przechowuje rekord każdego zgłoszenia przesłanego przez portal.
refreshTokenInFirestore(req): Za każdym razem, gdy Google Workspace Studio wywołuje którykolwiek z Twoich punktów końcowych webhooka, zawiera krótkotrwały authorizationEventObject.userOAuthToken. Ten pomocnik aktualizuje aktywne dokumenty wywołujące za pomocą najnowszego tokena, dzięki czemu wywołania w tle triggers.fire pozostają autoryzowane.

cat << 'EOF' > firestore.js
import { Firestore } from '@google-cloud/firestore';

export const db = new Firestore({
  projectId: process.env.GOOGLE_CLOUD_PROJECT || undefined,
  databaseId: '(default)',
  ignoreUndefinedProperties: true,
});

export const triggersCollection = db.collection(
  process.env.FIRESTORE_TRIGGERS_COLLECTION || 'studio_triggers'
);

export const ticketsCollection = db.collection(
  process.env.FIRESTORE_TICKETS_COLLECTION || 'support_tickets'
);

// Keep cached userOAuthToken fresh across active trigger documents
export async function refreshTokenInFirestore(req) {
  const freshToken = req.body?.authorizationEventObject?.userOAuthToken;
  if (!freshToken) return;
  try {
    const snapshot = await triggersCollection.get();
    if (snapshot.empty) return;
    const batch = db.batch();
    snapshot.docs.forEach((doc) => {
      batch.set(
        doc.ref,
        { userOAuthToken: freshToken, updatedAt: new Date().toISOString() },
        { merge: true }
      );
    });
    await batch.commit();
  } catch (err) {
    console.error('Error refreshing OAuth token in Firestore:', err.message);
  }
}
EOF

`starter.js` – niestandardowy krok początkowy (`workflowTrigger`)

Utwórz starter.js, aby wdrożyć 2 punkty końcowe webhooka wymagane przez niestandardowy krok początkowy Google Workspace Studio:

onConfigTrigger (POST /onConfigTrigger): wywoływana, gdy użytkownik wybierze Nowy zgłoszenie jako element rozpoczynający przepływ w Google Workspace Studio. Zwraca działanie nawigacji pushCard opisujące element inicjujący.
onManageTrigger (POST /onManageTrigger): wywoływana, gdy użytkownik włączy (req.body.workflow.triggerCreation) lub wyłączy przepływ albo go usunie (req.body.workflow.triggerDeletion). Zapisuje lub usuwa dokument subskrypcji w kolekcji studio_triggers Firestore.

cat << 'EOF' > starter.js
import { triggersCollection, refreshTokenInFirestore } from './firestore.js';

// Custom Starter Configuration Card
export async function onConfigTrigger(req, res) {
  await refreshTokenInFirestore(req);
  res.status(200).json({
    action: {
      navigations: [
        {
          pushCard: {
            sections: [
              {
                header: 'Support Ticket Listener',
                widgets: [
                  {
                    textParagraph: {
                      text: 'This starter listens for new tickets submitted through the Support Quick Portal and stores subscriptions in Firestore.',
                    },
                  },
                ],
              },
            ],
          },
        },
      ],
    },
  });
}

// Custom Starter Subscription Lifecycle (Firestore studio_triggers collection)
export async function onManageTrigger(req, res) {
  try {
    const triggerCreation = req.body?.workflow?.triggerCreation;
    const triggerDeletion = req.body?.workflow?.triggerDeletion;
    const userOAuthToken =
      req.body?.authorizationEventObject?.userOAuthToken || null;

    if (triggerCreation?.triggerId) {
      const triggerId = String(triggerCreation.triggerId);
      const docId = encodeURIComponent(triggerId);
      await triggersCollection.doc(docId).set(
        {
          triggerId,
          notifyUri: triggerCreation.notifyUri || null,
          ...(userOAuthToken ? { userOAuthToken } : {}),
          updatedAt: new Date().toISOString(),
        },
        { merge: true }
      );
    }

    if (triggerDeletion?.triggerId) {
      const triggerId = String(triggerDeletion.triggerId);
      const docId = encodeURIComponent(triggerId);
      await triggersCollection.doc(docId).delete();
    }

    if (!triggerCreation && !triggerDeletion && userOAuthToken) {
      await refreshTokenInFirestore(req);
    }
  } catch (err) {
    console.error('Error in /onManageTrigger:', err.message);
  }
  res.status(200).json({});
}
EOF

`action.js` – krok działania niestandardowego (`workflowAction`) z Gemini 3.8 Flash

Utwórz action.js, aby wdrożyć 2 punkty końcowe webhooka wymagane przez niestandardowe działanie w Google Workspace Studio:

onConfigUrgency (POST /onConfigUrgency): zwraca kartę konfiguracji z widżetem textInput, który ustawia hostAppDataSource.workflowDataSource.includeVariables: true, umożliwiając użytkownikom wybranie zmiennej ticketDescription wygenerowanej przez krok początkowy.
onExecuteUrgency (POST /onExecuteUrgency): odczytuje dane wejściowe ticketDescription z req.body.workflow.actionInvocation.inputs, klasyfikuje ich wpływ na firmę i pilność za pomocą Gemini 3.8 Flash (gemini-3.8-flash) na platformie agentów Gemini Enterprise z danymi wyjściowymi w formacie strukturalnym (responseSchema wyliczenie ["High", "Normal"]). Jeśli wywołanie modelu się nie powiedzie, wraca do detectKeywordUrgency() (urgent, blocker, critical) i zwraca zmienną wyjściową urgencyLevel za pomocą hostAppAction.workflowAction.returnOutputVariablesAction.

cat << 'EOF' > action.js
import { GoogleGenAI, Type } from '@google/genai';
import { refreshTokenInFirestore } from './firestore.js';

// Initialize Google GenAI SDK for the Gemini Enterprise Agent Platform
const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: 'global',
});

// Fallback keyword classifier if the Gemini API call is unavailable
export function detectKeywordUrgency(description) {
  const lower = (description || '').toLowerCase();
  return lower.includes('urgent') ||
    lower.includes('blocker') ||
    lower.includes('critical')
    ? 'High'
    : 'Normal';
}

// Custom Action Step Configuration Card
export async function onConfigUrgency(req, res) {
  await refreshTokenInFirestore(req);
  res.status(200).json({
    action: {
      navigations: [
        {
          pushCard: {
            sections: [
              {
                header: 'Urgency Detector Step',
                widgets: [
                  {
                    textInput: {
                      name: 'ticketDescription',
                      label: 'Source Description',
                      hintText:
                        'Select the description variable outputted by the starter',
                      hostAppDataSource: {
                        workflowDataSource: {
                          includeVariables: true,
                        },
                      },
                    },
                  },
                ],
              },
            ],
          },
        },
      ],
    },
  });
}

// Custom Action Step Execution: Gemini 3.8 Flash with keyword fallback
export async function onExecuteUrgency(req, res) {
  await refreshTokenInFirestore(req);
  const inputs = req.body?.workflow?.actionInvocation?.inputs || {};
  const description = inputs.ticketDescription?.stringValues?.[0] || '';

  let urgencyLevel = detectKeywordUrgency(description);
  try {
    const response = await ai.models.generateContent({
      model: 'gemini-3.8-flash',
      contents: `Evaluate the business impact and time sensitivity of this support ticket description and classify its urgency:\n\n${description}`,
      config: {
        responseMimeType: 'text/x.enum',
        responseSchema: {
          type: Type.STRING,
          enum: ['High', 'Normal'],
        },
      },
    });
    const candidate = (response.text || '').trim();
    if (candidate === 'High' || candidate === 'Normal') {
      urgencyLevel = candidate;
    }
  } catch (err) {
    console.error('Gemini fallback to keyword matching:', err.message);
  }

  res.status(200).json({
    hostAppAction: {
      workflowAction: {
        returnOutputVariablesAction: {
          variables: {
            urgencyLevel: {
              stringValues: [urgencyLevel],
            },
          },
        },
      },
    },
  });
}
EOF

`portal.js` – obsługa interfejsu Quick Portal i `triggers.fire` dyspozytora

Utwórz portal.js, aby obsługiwać portal internetowy i przesyłać zgłoszenia do Google Workspace Studio:

renderPortal (GET /): wysyła zapytanie do kolekcji studio_triggers Firestore, aby wyświetlić liczbę zarejestrowanych aktywnych wyzwalaczy Google Workspace Studio, i wyświetla formularz przesyłania zgłoszenia w HTML-u.
submitTicket (POST /api/submit-ticket): iteruje po wszystkich aktywnych dokumentach wyzwalających w usłudze studio_triggers, wywołuje punkt końcowy triggers.fire Google Workspace Studio (https://workspacestudio.googleapis.com/v1/triggers/{triggerId}:fire) ze zmiennymi wyjściowymi ticketTitle i ticketDescription oraz unikalnym identyfikatorem requestId i zapisuje zgłoszenie w kolekcji support_tickets Firestore.

cat << 'EOF' > portal.js
import { triggersCollection, ticketsCollection } from './firestore.js';

// Support Quick Portal UI
export async function renderPortal(req, res) {
  let activeCount = 0;
  try {
    const snapshot = await triggersCollection.get();
    activeCount = snapshot.size;
  } catch (err) {
    console.error('Error reading studio_triggers collection:', err.message);
  }

  res.status(200).send(`<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Support Quick Portal</title>
    <style>
      body { font-family: Arial, sans-serif; padding: 24px; max-width: 540px; margin: auto; color: #202124; }
      .badge { background: #e8f0fe; color: #1967d2; padding: 8px 12px; border-radius: 6px; font-size: 14px; margin-bottom: 16px; }
      label { font-weight: bold; display: block; margin-top: 16px; }
      input, textarea { width: 100%; margin-top: 6px; padding: 10px; box-sizing: border-box; border: 1px solid #dadce0; border-radius: 4px; }
      button { background-color: #1a73e8; color: white; border: none; padding: 10px 18px; margin-top: 16px; font-weight: bold; cursor: pointer; border-radius: 4px; }
      button:hover { background-color: #1557b0; }
      #status { margin-top: 16px; font-weight: bold; }
    </style>
  </head>
  <body>
    <h2>Support Quick Portal</h2>
    <div class="badge">
      Active Google Workspace Studio triggers in Firestore (<code>studio_triggers</code>):
      <strong id="trigger-count">${activeCount}</strong>
    </div>
    <p>Submit a support ticket below to fire your Google Workspace Studio flow.</p>

    <label for="title">Ticket Title</label>
    <input type="text" id="title" placeholder="e.g. Database failure">

    <label for="description">Issue Description</label>
    <textarea id="description" rows="4" placeholder="Describe the issue..."></textarea>

    <button onclick="submitTicket()">Submit Ticket</button>
    <div id="status"></div>

    <script>
      async function submitTicket() {
        const title = document.getElementById('title').value.trim();
        const description = document.getElementById('description').value.trim();
        const statusEl = document.getElementById('status');

        if (!title || !description) {
          statusEl.style.color = '#d93025';
          statusEl.textContent = 'Please fill out both fields.';
          return;
        }

        statusEl.style.color = '#188038';
        statusEl.textContent = 'Submitting ticket...';

        try {
          const res = await fetch('/api/submit-ticket', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ title, description }),
          });
          const data = await res.json();
          if (data.ok) {
            statusEl.textContent =
              'Ticket saved to Firestore! Fired ' + data.triggersFired + ' Google Workspace Studio trigger(s).';
          } else {
            statusEl.style.color = '#d93025';
            statusEl.textContent = 'Error: ' + (data.error || 'Unknown error');
          }
        } catch (err) {
          statusEl.style.color = '#d93025';
          statusEl.textContent = 'Request failed: ' + err.message;
        }
      }
    </script>
  </body>
</html>`);
}

// Portal Form Submission -> Fire Active Google Workspace Studio Triggers
export async function submitTicket(req, res) {
  const title = req.body?.title || 'Untitled Ticket';
  const description = req.body?.description || '';
  const results = [];

  try {
    const snapshot = await triggersCollection.get();
    for (const doc of snapshot.docs) {
      const trigger = doc.data();
      if (!trigger.triggerId || !trigger.userOAuthToken) continue;

      const response = await fetch(
        `https://workspacestudio.googleapis.com/v1/triggers/${encodeURIComponent(trigger.triggerId)}:fire`,
        {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${trigger.userOAuthToken}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            name: 'triggers/' + trigger.triggerId,
            outputs: {
              ticketTitle: { stringValues: [title] },
              ticketDescription: { stringValues: [description] },
            },
            requestId:
              'req_' + Date.now() + '_' + Math.floor(Math.random() * 1000),
          }),
        }
      );
      results.push({ triggerId: trigger.triggerId, status: response.status });
    }

    await ticketsCollection.add({
      title,
      description,
      triggersFired: results.length,
      createdAt: new Date().toISOString(),
    });

    res.status(200).json({ ok: true, triggersFired: results.length, results });
  } catch (err) {
    console.error('Error in /api/submit-ticket:', err.message);
    res.status(500).json({ ok: false, error: err.message });
  }
}
EOF

`index.js` – punkt wejścia serwera Express

Utwórz index.js, aby połączyć trasy portalu i punkty końcowe webhooka Google Workspace Studio w serwer HTTP Express nasłuchujący na porcie PORT (domyślnie 8080 w Cloud Run):

cat << 'EOF' > index.js
import express from 'express';
import { onConfigTrigger, onManageTrigger } from './starter.js';
import { onConfigUrgency, onExecuteUrgency } from './action.js';
import { renderPortal, submitTicket } from './portal.js';

const app = express();
app.use(express.json());

// Support Quick Portal routes
app.get('/', renderPortal);
app.post('/api/submit-ticket', submitTicket);

// Google Workspace Studio Custom Starter Step webhooks
app.post('/onConfigTrigger', onConfigTrigger);
app.post('/onManageTrigger', onManageTrigger);

// Google Workspace Studio Custom Action Step webhooks
app.post('/onConfigUrgency', onConfigUrgency);
app.post('/onExecuteUrgency', onExecuteUrgency);

const PORT = process.env.PORT || 8080;
app.listen(PORT, () => {
  console.log(`Support Extension listening on port ${PORT}`);
});
EOF

4. Wdrażanie w Cloud Run i instalowanie dodatku

W tym kroku wdrażasz usługę Node.js w Cloud Run, przyznajesz uprawnienia IAM wywołującemu dodatki do Google Workspace oraz dostęp do środowiska wykonawczego Firestore i platformy agentów, generujesz deployment.json manifest i instalujesz wdrożenie dodatku.

Wdróż usługę support-extension w Cloud Run ze zmiennymi środowiskowymi projektu i kolekcji Firestore:

gcloud run deploy support-extension \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project),FIRESTORE_TRIGGERS_COLLECTION=studio_triggers,FIRESTORE_TICKETS_COLLECTION=support_tickets" \
  --quiet

Przyznaj uprawnienia roles/run.invoker w usłudze Cloud Run kontu usługi dodatków do Google Workspace, aby Google Workspace Studio mogło wywoływać punkty końcowe webhooka:

ADDON_SA=$(gcloud workspace-add-ons get-authorization --format="value(serviceAccountEmail)")
gcloud run services add-iam-policy-binding support-extension \
  --region=us-central1 \
  --member="serviceAccount:${ADDON_SA}" \
  --role="roles/run.invoker" \
  --quiet

Przyznaj roles/datastore.user (do odczytywania i zapisywania kolekcji Firestore studio_triggers i support_tickets) oraz roles/aiplatform.user (do wywoływania Gemini na platformie Gemini Enterprise Agent Platform) wykonawczemu kontu usługi Cloud Run:

PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe "${PROJECT_ID}" --format="value(projectNumber)")
RUNTIME_SA=$(gcloud run services describe support-extension --region=us-central1 --format="value(spec.template.spec.serviceAccountName)")
RUNTIME_SA=${RUNTIME_SA:-"${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"}

gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
  --member="serviceAccount:${RUNTIME_SA}" \
  --role="roles/datastore.user" \
  --condition=None \
  --quiet

gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
  --member="serviceAccount:${RUNTIME_SA}" \
  --role="roles/aiplatform.user" \
  --condition=None \
  --quiet

Pobierz wdrożony adres URL Cloud Run i wygeneruj plik manifestu deployment.json definiujący elementy supportTicketTrigger (workflowTrigger) i urgencyDetectorStep (workflowAction):

SERVICE_URL=$(gcloud run services describe support-extension --region=us-central1 --format="value(status.url)")

cat << EOF > deployment.json
{
  "oauthScopes": [
    "https://www.googleapis.com/auth/workspace.studio.trigger",
    "https://www.googleapis.com/auth/userinfo.email"
  ],
  "addOns": {
    "common": {
      "name": "Support Extension",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/buganizer/v1/192px.svg"
    },
    "studio": {
      "flows": {
        "workflowElements": [
          {
            "id": "supportTicketTrigger",
            "state": "ACTIVE",
            "name": "New Support Ticket",
            "description": "Fires when someone submits a ticket in the Support Quick Portal.",
            "workflowTrigger": {
              "inputs": [],
              "outputs": [
                {
                  "id": "ticketTitle",
                  "description": "Ticket Title",
                  "cardinality": "SINGLE",
                  "dataType": { "basicType": "STRING" }
                },
                {
                  "id": "ticketDescription",
                  "description": "Ticket Description",
                  "cardinality": "SINGLE",
                  "dataType": { "basicType": "STRING" }
                }
              ],
              "onConfigFunction": "${SERVICE_URL}/onConfigTrigger",
              "onManageFunction": "${SERVICE_URL}/onManageTrigger"
            }
          },
          {
            "id": "urgencyDetectorStep",
            "state": "ACTIVE",
            "name": "Detect Urgency",
            "description": "Evaluates the ticket description to detect High or Normal urgency.",
            "workflowAction": {
              "inputs": [
                {
                  "id": "ticketDescription",
                  "description": "Description to scan",
                  "cardinality": "SINGLE",
                  "dataType": { "basicType": "STRING" }
                }
              ],
              "outputs": [
                {
                  "id": "urgencyLevel",
                  "description": "Detected Urgency (High / Normal)",
                  "cardinality": "SINGLE",
                  "dataType": { "basicType": "STRING" }
                }
              ],
              "onConfigFunction": "${SERVICE_URL}/onConfigUrgency",
              "onExecuteFunction": "${SERVICE_URL}/onExecuteUrgency"
            }
          }
        ]
      }
    },
    "httpOptions": {
      "authorizationHeader": "SYSTEM_ID_TOKEN"
    }
  }
}
EOF

Utwórz (lub zastąp) i zainstaluj wdrożenie dodatku Google Workspace na swoim koncie oraz wydrukuj adres URL Szybkiego portalu pomocy:

gcloud workspace-add-ons deployments create support-extension --deployment-file=deployment.json || \
  gcloud workspace-add-ons deployments replace support-extension --deployment-file=deployment.json
gcloud workspace-add-ons deployments install support-extension
echo "Support Quick Portal URL: ${SERVICE_URL}"

5. Testowanie niestandardowych kroków w Google Workspace Studio

Otwórz Google Workspace Studio (jeśli karta przeglądarki była już otwarta, odśwież ją) i kliknij Nowa automatyzacja.
Kliknij Wybierz szablon > Rozszerzenie pomocy > Nowe zgłoszenie.
Rozwiązywanie problemówOAuth client not found: jeśli po kliknięciu kroku początkowego lub działania pojawi się ikona OAuth client not found -- Is the OAuth consent screen configured?, sprawdź, czy konfiguracja elementów marki platformy Google Auth została ukończona i czy w kroku 2 włączono opcję appsmarket-component.googleapis.com. Po włączeniu pakietu Google Workspace Marketplace SDK automatyczne utworzenie klienta OAuth może potrwać minutę. Odśwież kartę Google Workspace Studio i spróbuj ponownie.
Kliknij Dodaj krok (+) > Rozszerzenie pomocy > Wykryj pilność. W polu Opis źródła kliknij + Zmienne i wybierz Opis zgłoszenia.
Kliknij Dodaj krok (+) i dodaj krok Chat > Powiadom mnie na czacie, który zawiera zmienne Tytuł zgłoszenia, Poziom pilności i Opis zgłoszenia w wiadomości.
W prawym górnym rogu włącz przepływ. Google Workspace Studio natychmiast wywołuje punkt końcowy /onManageTrigger w Cloud Run, który zapisuje aktywną subskrypcję wyzwalacza w kolekcji studio_triggers w Firestore.
Ważne – jeśli automatyzacja nie jest uruchamiana: niestandardowy moduł uruchamiający otrzymuje zdarzenia tylko wtedy, gdy Google Workspace Studio wywołuje /onManageTrigger po włączeniu automatyzacji (Włącz). Jeśli przesłanie zgłoszenia w portalu nie uruchamia przepływu (lub jeśli w portalu wyświetlają się 0aktywne wyzwalacze), sprawdź, czy przełącznik przepływu w prawym górnym rogu Google Workspace Studio jest ustawiony w pozycji Włączony. Możesz też przełączyć go na Wyłączony, a następnie z powrotem na Włączony. Potem odśwież portal pomocy, aby sprawdzić, czy w kolekcji studio_triggers Firestore jest przechowywany co najmniej 1aktywny wyzwalacz.
Otwórz w nowej karcie adres URL portalu szybkiego wsparcia (https://support-extension-...run.app), sprawdź, czy w portalu wyświetla się 1aktywny wyzwalacz w Firestore, i prześlij 2 zgłoszenia, aby przetestować klasyfikację Gemini 3.8 Flash (gemini-3.8-flash):
- Zgłoszenie o dużym wpływie (Tytuł zgłoszenia: London office lockout, Opis problemu: All 500 employees in the London office are locked out of their workstations 20 minutes before the board presentation.): nawet bez zakodowanych na stałe słów kluczowych, takich jak urgent czy blocker, gemini-3.8-flash klasyfikuje to zgłoszenie jako pilne – High.
- Zgłoszenie rutynowe (Tytuł zgłoszenia: Conference room adapters, Opis problemu: Could we order two extra HDMI adapters for the third-floor conference room next month?): gemini-3.8-flash klasyfikuje to zgłoszenie jako Normal pilne.
Sprawdź w Google Chat i na karcie Aktywność w Google Workspace Studio, czy automatyzacja została uruchomiona w przypadku obu zgłoszeń z Urgency Level: High i Urgency Level: Normal.

6. Czyszczenie danych

Aby uniknąć obciążenia konta Google Cloud bieżącymi opłatami, usuń wdrożone zasoby w Cloud Shell:

gcloud workspace-add-ons deployments uninstall support-extension
gcloud workspace-add-ons deployments delete support-extension --quiet
gcloud run services delete support-extension --region=us-central1 --quiet
gcloud firestore databases delete --database="(default)" --quiet

7. Gratulacje!

Udało Ci się utworzyć, wdrożyć i przetestować rozszerzenie HTTP Node.js dla Google Workspace Studio przy użyciu Firestore, Cloud Run i Gemini 3.8 Flash na Gemini Enterprise Agent Platform.

Omówione zagadnienia

Konfigurowanie pliku manifestu dodatku HTTP do Google Workspace Studio (deployment.json) z elementami workflowTrigger i workflowAction.
Utrwalanie subskrypcji Google Workspace Studio workflowTrigger w kolekcji studio_triggers Firestore i rejestrowanie zgłoszeń w portalu support_tickets, aby wyzwalacze przetrwały skalowanie i ponowne wdrażanie Cloud Run.
Tworzenie kroku workflowAction, który klasyfikuje zgłoszenia pomocy za pomocą Gemini 3.8 Flash (gemini-3.8-flash) w formacie strukturalnym na Gemini Enterprise Agent Platform z odpornym na błędy dopasowywaniem słów kluczowych.