Praca z wydarzeniami z Dysku Google

Wersja przedpremierowa: dostępna w ramach programu Google Workspace w wersji przedpremierowej, który zapewnia wcześniejszy dostęp do niektórych funkcji.

Z tego artykułu dowiesz się, jak otrzymywać zdarzenia z Dysku Google za pomocą Google Cloud Pub/Sub.

Zdarzenie na Dysku to działanie lub zmiana zasobu na Dysku, np. nowy plik w folderze. Zdarzenia możesz wykorzystywać do analizowania tego, co się wydarzyło, a potem podejmować odpowiednie działania lub reagować w sposób, który będzie przydatny dla użytkowników.

Oto kilka przykładów zastosowań zdarzeń:

• Obserwowanie zmian w pliku, folderze lub na dysku współdzielonym i reagowanie na nie, np. gdy plik zostanie zmodyfikowany lub przesłana zostanie nowa wersja.

• Monitoruj zmiany w plikach, aby zwiększyć wydajność aplikacji.

• Audytowanie działań takich jak udostępnianie, przenoszenie i usuwanie plików, aby wykrywać potencjalne wycieki danych i nieautoryzowany dostęp.

• Dostarczanie statystyk dotyczących zarządzania plikami przez użytkowników, co pomaga określać obszary, w których można ulepszyć zarządzanie treściami.

• śledzić zmiany w plikach, aby sprawdzać zgodność z wymaganiami prawnymi lub zasadami bezpieczeństwa;

• Analizuj aktywność na Dysku za pomocą innych usług Google Cloud, takich jak Eventarc, Workflows i BigQuery.

Jak działają zdarzenia

Za każdym razem, gdy coś się dzieje na Dysku, zasób interfejsu Google Drive API jest tworzony, aktualizowany lub usuwany. Dysk używa zdarzeń do przekazywania aplikacji informacji o rodzaju aktywności i zasobie interfejsu Drive API, którego dotyczy ta aktywność.

Dysk kategoryzuje zdarzenia według typu. Typy zdarzeń pomagają filtrować i otrzymywać tylko potrzebne informacje oraz umożliwiają podobne działania w ten sam sposób.

W tabeli poniżej pokazujemy, jak przykładowa aktywność na Dysku wpływa na powiązany zasób interfejsu Drive API oraz jaki typ zdarzenia otrzymuje aplikacja na Dysku:

Aktywność	Zasób Drive API	Typ zdarzenia
Użytkownik tworzy propozycję dostępu do pliku.	Utworzono zasób AccessProposal.	Nowa propozycja dostępu
Użytkownik publikuje komentarz w pliku Dokumentów, Arkuszy lub Prezentacji Google.	Utworzono zasób Comment.	Nowy komentarz
Użytkownik dodaje plik do folderu lub dysku współdzielonego.	Utworzono zasób File.	Nowy plik
Użytkownik odpowiada na komentarz.	Utworzono zasób Reply.	Nowa odpowiedź

Odbieranie zdarzeń z Dysku Google

Tradycyjnie aplikacja Dysku mogła lokalizować zdarzenia za pomocą interfejsu Drive API lub interfejsu Google Drive Activity API. Dzięki dodaniu zdarzeń Dysku w interfejsie Google Workspace Events API dostępna jest teraz trzecia metoda odbierania zdarzeń:

• Wersja zapoznawcza dla deweloperów: subskrybuj zdarzenia za pomocą interfejsu Google Workspace Events API, aby otrzymywać zdarzenia w miarę ich występowania. Więcej informacji znajdziesz w artykule Subskrybowanie zdarzeń na Dysku Google.

• Subskrybuj zdarzenia za pomocą interfejsu Drive API. Pobierz zdarzenia zmiany użytkownika za pomocą metody changes.watch lub zdarzenia zmiany pliku za pomocą metody files.watch.

• Wysyłaj zapytania o ostatnie zdarzenia, wywołując interfejs Google Drive Activity API.

W tabeli poniżej znajdziesz wyjaśnienie różnic między subskrybowaniem zdarzeń a wysyłaniem zapytań o nie oraz powody, dla których warto subskrybować zdarzenia:

	Subskrybowanie wydarzeń Google Workspace	Subskrybowanie zdarzeń dotyczących obserwowania interfejsu Drive API	Wysyłanie zapytań o zdarzenia interfejsu Drive Activity API
Przypadki użycia	przetwarzać zdarzenia i na nie odpowiadać w czasie rzeczywistym; Monitoruj zmiany w zasobach, aby poprawić wydajność aplikacji. Otrzymuj ustrukturyzowane dane o zdarzeniach za pomocą Pub/Sub i korzystaj z usług Google Cloud, takich jak Cloud Run.	Wykrywaj zmiany w metadanych plików i skutecznie monitoruj zmiany w określonych elementach dzięki powiadomieniom w czasie rzeczywistym. Obsługuje adres URL wywołania zwrotnego webhooka, aby uniknąć wielokrotnego odpytywania punktów końcowych interfejsu API.	Pobieranie szczegółowej historii wszystkich działań, w tym szczegółowych informacji o każdym zdarzeniu. Pobieranie dokładnych działań, które zawierają informacje ActionDetail, Actor i Target, na potrzeby konkretnych zadań, takich jak audyty.
Interfejs API	Interfejs Google Workspace Events API	Google Drive API	Google Drive Activity API
Źródło zdarzeń	Pliki, foldery i dyski współdzielone	changes.watch i files.watch	DriveActivity
Obsługiwane zdarzenia	AccessProposal Comment File Reply Listę obsługiwanych typów zdarzeń znajdziesz w artykule Typy zdarzeń do tworzenia subskrypcji w dokumentacji interfejsu Google Workspace Events API.	Channel Listę obsługiwanych typów zdarzeń znajdziesz w artykule Informacje o zdarzeniach powiadomień interfejsu Google Drive API w dokumentacji interfejsu Drive API.	Action Listę obsługiwanych pól znajdziesz w  dokumentacji referencyjnej interfejsu Drive Activity API.Action
Format zdarzenia	Wiadomość Pub/Sub sformatowana zgodnie ze specyfikacją CloudEvent. Więcej informacji znajdziesz w artykule Struktura zdarzeń Google Workspace.	Zasób Drive API (Channel)	Zasób Drive Activity API (Action)
Dane zdarzenia	Ciąg tekstowy zakodowany w formacie Base64 z danymi zasobu lub bez nich. Przykładowe ładunki znajdziesz w sekcji Dane zdarzenia.	Ładunek JSON zawierający dane zasobu. Przykładowy ładunek znajdziesz w Channel w dokumentacji.	Ładunek JSON zawierający dane zasobu. Przykładowy ładunek znajdziesz w activity.querytreści odpowiedzi w dokumentacji referencyjnej.

Pierwsze kroki z wydarzeniami na Dysku

Z tego przewodnika dowiesz się, jak utworzyć subskrypcję zdarzeń Google Workspace na zasobie Dysku i nią zarządzać. Dzięki temu Twoja aplikacja będzie mogła otrzymywać zdarzenia za pomocą Google Cloud Pub/Sub.

Tworzenie projektu Google Cloud

Aby wygenerować projekt Google Cloud, zapoznaj się z artykułem Tworzenie projektu Google Cloud.

Włącz interfejsy Google Workspace Events API, Google Cloud Pub/Sub API i Google Drive API.

Zanim zaczniesz korzystać z interfejsów Google API, musisz je włączyć w projekcie Google Cloud. W jednym projekcie Google Cloud możesz włączyć co najmniej 1 interfejs API.

Konsola Google Cloud

1. W konsoli Google Cloud otwórz projekt Google Cloud dla swojej aplikacji i włącz interfejsy Google Workspace Events API, Pub/Sub API i Drive API:

   Włączanie interfejsów API

2. Sprawdź, czy włączasz interfejsy API w odpowiednim projekcie w Cloud, a potem kliknij Dalej.

3. Sprawdź, czy włączasz odpowiednie interfejsy API, a potem kliknij Włącz.

gcloud

1. W katalogu roboczym zaloguj się na konto Google:

   gcloud auth login

2. Ustaw projekt na projekt Cloud dla aplikacji:

   gcloud config set project PROJECT_ID

   Zastąp PROJECT_ID identyfikatorem projektu projektu Cloud na potrzeby aplikacji.

3. Włącz interfejsy Google Workspace Events API, Pub/Sub API i Drive API:

   gcloud services enable workspaceevents.googleapis.com \
   pubsub.googleapis.com \
   drive.googleapis.com

Konfigurowanie identyfikatora klienta

Aby wygenerować identyfikator klienta OAuth 2.0, zapoznaj się z artykułem Tworzenie danych logowania klienta OAuth.

Tworzenie tematu Pub/Sub

Zanim utworzysz subskrypcję, musisz utworzyć temat Google Cloud Pub/Sub, który będzie otrzymywać odpowiednie zdarzenia, które interesują Twoją aplikację. Aby utworzyć temat Pub/Sub, zapoznaj się z artykułem Tworzenie tematu Pub/Sub i subskrybowanie go.

Pamiętaj, aby w swoich żądaniach odwoływać się do konta usługi Dysku ([e-mail]).

Tworzenie subskrypcji Dysku

Beta: zdarzenia na Dysku są dostępne w wersji przedpremierowej dla programistów. Musisz używać wersji interfejsu API v1beta. Próby użycia standardowej v1 wersji interfejsu API zakończą się niepowodzeniem.

Zdarzenia Cloud są wysyłane, gdy zmieni się temat subskrypcji (lub dowolny inny plik w hierarchii tematu). Jeśli na przykład utworzysz subskrypcję na dysku współdzielonym, a plik znajdujący się w kilku podfolderach na tym dysku zostanie zmieniony, wygenerowane zostanie zdarzenie. Listę obsługiwanych zasobów i typów zdarzeń na Dysku znajdziesz w artykule Typy zdarzeń do tworzenia subskrypcji.

Poniższa aplikacja Node.js tworzy subskrypcję zdarzeń na Dysku w pliku lub folderze, aby nasłuchiwać zdarzeń zmiany treści. Więcej informacji znajdziesz w artykule Tworzenie subskrypcji Google Workspace.

Aby uruchomić ten przykład, upewnij się, że masz zainstalowane Node.js i npm. Musisz też sprawdzić, czy masz zainstalowane wymagane zależności, aby uruchomić ten przykład.

# Install needed dependencies
$ npm install googleapis @google-cloud/local-auth axios

Aby utworzyć subskrypcję Dysku, użyj metody subscriptions.create() interfejsu Google Workspace Events API, aby utworzyć zasób Subscription:

// app.js

const fs = require('fs').promises;
const {authenticate} = require('@google-cloud/local-auth');
const {google} = require('googleapis');
const axios = require('axios');

// Scopes for Google Drive API access.
const SCOPES = ['SCOPES'];

/**
 * Authenticates the user running the script.
 * @return {Promise<OAuth2Client>} The authorized client.
 */
async function authorize() {
  const client = await authenticate({
    scopes: SCOPES,
    keyfilePath: 'credentials.json',
  });
  if (client.credentials) {
    const content = await fs.readFile('credentials.json');
    const keys = JSON.parse(content);
    const {client_id, client_secret} = keys.installed || keys.web;
    const payload = JSON.stringify({
      type: 'authorized_user',
      client_id,
      client_secret,
      refresh_token: client.credentials.refresh_token,
    });
    await fs.writeFile('token.json', payload);
    return client;
  } else {
    throw new Exception(
        'credentials.json did not have the Oauth client secret or it was not properly formatted');
  }
  }

/**
 * Creates a subscription to Google Drive events.
 * @param {OAuth2Client} authClient An authorized OAuth2 client.
 */
async function createSubscription(authClient) {
  const url = 'https://workspaceevents.googleapis.com/v1beta/subscriptions';
  const data = {
    targetResource: 'TARGET_RESOURCE',
    eventTypes: ['EVENT_TYPES'],
    payload_options: {
      include_resource: {
        {
          '<var>RESOURCE_DATA</var>'
        }
      }
    },
    drive_options: {
      include_descendants: {
        {
          '<var>INCLUDE_DESCENDANTS</var>'
        }
      }
    },
    notification_endpoint: {pubsub_topic: 'TOPIC_NAME'}
  };
  try {
    const {token} = await authClient.getAccessToken();
    const response = await axios.post(
        url, data, {headers: {'Authorization': `Bearer ${token}`}});
    console.log('Subscription created:', response.data);
  } catch (error) {
    const message = error.response ? error.response.data : error.message;
    console.error('Error creating subscription:', message);
  }
}

authorize().then(createSubscription).catch(console.error);

Zastąp następujące elementy:

• SCOPES: Co najmniej 1 zakres OAuth, który obsługuje każdy typ zdarzenia w przypadku subskrypcji. Sformatowane jako tablica ciągów tekstowych. Aby podać kilka zakresów, oddziel je przecinkami. Zalecamy używanie najbardziej restrykcyjnego zakresu, który nadal umożliwia działanie aplikacji. Na przykład:'https://www.googleapis.com/auth/drive.file'.

• TARGET_RESOURCE: zasób Google Workspace, który subskrybujesz, sformatowany jako pełna nazwa zasobu. Aby na przykład zasubskrybować plik lub folder na Dysku, użyj //drive.googleapis.com/files/FileID.

• EVENT_TYPES: co najmniej 1 typ zdarzenia, na który chcesz się subskrybować w zasobie docelowym. Sformatuj jako tablicę ciągów znaków, np. 'google.workspace.drive.file.v3.contentChanged'.

• RESOURCE_DATA: wartość logiczna określająca, czy subskrypcja obejmuje dane zasobów w ładunku zdarzenia. Ta właściwość wpływa na czas trwania subskrypcji. Więcej informacji znajdziesz w sekcji Dane zdarzenia.

  • True: obejmuje wszystkie dane zasobów. Aby ograniczyć liczbę uwzględnianych pól, dodaj parametr fieldMask i określ co najmniej 1 pole zmienionego zasobu. Tylko subskrypcje zasobów Chat i Dysku obsługują uwzględnianie danych zasobów.

  • False: nie obejmuje danych o zasobach.

• INCLUDE_DESCENDANTS: pole logiczne, które jest częścią DriveOptions. Dostępne tylko wtedy, gdy targetResource jest plikiem na Dysku lub dyskiem współdzielonym, którego typ MIME jest ustawiony na application/vnd.google-apps.folder. Nie można ustawić w folderze głównym Mojego dysku ani dysków współdzielonych.

  • True: Subskrypcja obejmuje wszystkie pliki na Dysku potomne na liście zdarzeń.

  • False: subskrypcja jest tworzona dla pojedynczego pliku lub dysku współdzielonego, który jest określony jako targetResource.

• TOPIC_NAME: pełna nazwa tematu Pub/Sub utworzonego w projekcie Cloud. Ten temat Pub/Sub odbiera zdarzenia dla subskrypcji. Sformatowano jako projects/PROJECT_ID/topics/TOPIC_ID. Pole notificationEndpoint służy do określania tematu Pub/Sub, do którego subskrypcja dostarcza zdarzenia.

Testowanie subskrypcji Dysku

Aby sprawdzić, czy otrzymujesz zdarzenia z Dysku, możesz wywołać zdarzenie i pobrać wiadomości do subskrypcji Pub/Sub. Więcej informacji znajdziesz w artykule Testowanie subskrypcji Google Workspace.

Przetwarzanie zdarzeń na Dysku za pomocą Cloud Functions

Zdarzenia na Dysku są wysyłane do tematu Pub/Sub w utworzonej przez Ciebie subskrypcji. Podczas tworzenia wyzwalacza upewnij się, że temat Pub/Sub wyzwalacza jest zgodny z tematem Pub/Sub w subskrypcji zdarzeń. Następnie możesz wdrożyć funkcję Cloud Run i wprowadzić zmiany w pliku, aby zobaczyć zmiany zdarzeń w logach.

Zanim utworzysz funkcję, zaktualizuj package.json w przypadku zależności:

{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0",
    "cloudevents": "^8.0.0"
  }
}

Następnie utwórz kod źródłowy funkcji:

const functions = require('@google-cloud/functions-framework');
const { HTTP } = require("cloudevents");

/**
 * A Cloud Function triggered by Pub/Sub messages containing Google Drive activity events.
 * This function processes different types of Drive events.
 *
 * @param {object} cloudEvent The CloudEvent object.
 * @param {object} cloudEvent.data The data payload from the event source.
 */
functions.cloudEvent('helloFromDrive', async (cloudEvent) => {
  try {
    // Verify the Pub/Sub message exists
    if (!cloudEvent.data || !cloudEvent.data.message) {
      console.warn("Event is missing the Pub/Sub message payload.");
      return;
    }

    // Extract the Pub/Sub message details
    const { message } = cloudEvent.data;
    const { attributes, data } = message;

    // The original Drive CloudEvent is reconstructed from the Pub/Sub message attributes
    const driveEvent = HTTP.toEvent({ headers: attributes });
    const { type } = driveEvent;

    // The Drive event's payload is a base64 encoded JSON string
    const payload = JSON.parse(Buffer.from(data, "base64").toString());

    console.log(`Processing Drive event type: ${type}`);

    // Use a switch statement to handle different event types
    switch (type) {
      case 'google.workspace.drive.file.v3.contentChanged':
        console.log('File Content Changed:', payload);
        break;
      case 'google.workspace.drive.accessproposal.v3.created':
        console.log('Access Proposal Created:', payload);
        break;
      default:
        console.log(`Received unhandled event type: ${type}`);
        break;
    }
  } catch (error) {
    console.error("An error occurred while processing the Drive event:", error);
  }
});

Ograniczenia

• Gdy pole logiczne includeDescendants w DriveOptions ma wartość true, subskrypcje Dysku na dyskach i folderach współdzielonych zawsze wysyłają zdarzenie, nawet jeśli plik, który je wywołał, jest zagnieżdżony wiele poziomów poniżej folderu używanego do subskrypcji Dysku.
• Nawet jeśli utworzysz subskrypcję folderu, możesz nie otrzymywać wszystkich zdarzeń w hierarchii plików, ponieważ użytkownik lub aplikacja mogą nie mieć do nich dostępu. W takim przypadku subskrypcja pozostanie aktywna, ale nie będziesz otrzymywać żadnych zdarzeń dotyczących zasobów, do których nie masz dostępu.
• Subskrypcje są obsługiwane w przypadku zdarzeń dotyczących wszystkich plików i folderów, ale nie w przypadku folderu głównego dysków współdzielonych. Subskrypcje są obsługiwane tylko w przypadku plików i folderów na dyskach współdzielonych. Zmiany wprowadzone bezpośrednio w folderze głównym dysku współdzielonego nie spowodują wywołania zdarzeń.
• Użytkownik, który autoryzuje subskrypcję, musi mieć uprawnienia do pliku odpowiadającego zdarzeniom, które subskrybuje.
• Subskrypcja otrzymuje tylko zdarzenia dotyczące zasobów, do których użytkownik ma dostęp za pomocą konta Google Workspace lub konta Google.

Powiązane artykuły

• Omówienie interfejsu Google Workspace Events API
• Tworzenie subskrypcji Google Workspace
• Subskrybowanie zdarzeń na Dysku Google