Praca z wydarzeniami z Dysku Google

Na tej stronie dowiesz się, jak odbierać zdarzenia z Dysku Google z Google Cloud Pub/Sub.

Zdarzenie na Dysku reprezentuje aktywność lub zmianę w zasobie Dysku, np. nowy plik w folderze. Możesz używać zdarzeń, aby dowiedzieć się, co się stało, i podjąć odpowiednie działania lub zareagować w sposób, który będzie przydatny dla użytkowników.

Oto kilka przykładów wykorzystania zdarzeń:

• obserwować zmiany w pliku, folderze lub na dysku współdzielonym i reagować na nie, np. gdy plik zostanie zmodyfikowany lub zostanie przesłana nowa wersja;

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

• Sprawdzaj działania takie jak udostępnianie, przenoszenie i usuwanie plików, aby wykrywać potencjalne wycieki danych i nieautoryzowany dostęp.

• Dostarczają informacji o tym, jak użytkownicy zarządzają swoimi plikami, co pomaga zidentyfikować obszary, w których można ulepszyć zarządzanie treściami.

• śledzenie zmian w plikach w celu sprawdzenia zgodności z wymogami prawnymi lub zasadami bezpieczeństwa;

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

Jak działają wydarzenia

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

Dysk kategoryzuje zdarzenia według typu. Typy zdarzeń pomagają filtrować i otrzymywać tylko te informacje, których potrzebujesz, oraz umożliwiają obsługę podobnych działań w ten sam sposób.

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

Odbieranie zdarzeń z Dysku Google

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

• Subskrybuj zdarzenia za pomocą interfejsu Google Workspace Events API, aby otrzymywać informacje o zdarzeniach, gdy tylko wystąpią. Więcej informacji znajdziesz w artykule Subskrybowanie zdarzeń na Dysku Google.

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

• Wyszukaj ostatnie zdarzenia, wywołując interfejs Google Drive Activity API.

W poniższej tabeli wyjaśniono różnice między subskrybowaniem zdarzeń a wysyłaniem zapytań o nie oraz powody, dla których warto korzystać z tych metod:

Pierwsze kroki ze zdarzeniami na Dysku

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

Tworzenie projektu Google Cloud

Aby dowiedzieć się, jak wygenerować projekt Google Cloud, przeczytaj artykuł Tworzenie projektu Google Cloud.

Włączanie interfejsów Google Workspace Events API, Google Cloud Pub/Sub API i Google Drive API

Konfigurowanie identyfikatora klienta

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

Tworzenie tematu Pub/Sub

Zanim utworzysz subskrypcję, musisz utworzyć temat Google Cloud Pub/Sub, który będzie otrzymywać odpowiednie zdarzenia, którymi jest zainteresowana Twoja aplikacja. Aby dowiedzieć się, jak utworzyć temat Pub/Sub, przeczytaj artykuł o tworzeniu i subskrybowaniu tematu Pub/Sub.

Pamiętaj, aby w żądaniach odwoływać się do konta usługi Dysku (drive-api-event-push@system.gserviceaccount.com).

Tworzenie subskrypcji Dysku

Zdarzenia w chmurze są wysyłane, gdy zmienia się temat subskrypcji (lub dowolny inny plik w hierarchii tematu). Jeśli na przykład utworzysz subskrypcję na dysku współdzielonym i zmieni się plik zagnieżdżony w kilku podfolderach na tym dysku, zostanie wygenerowane zdarzenie. Informacje o obsługiwanych zasobach i typach zdarzeń na Dysku znajdziesz w artykule Typy zdarzeń do tworzenia subskrypcji.

Ta aplikacja Node.js tworzy subskrypcję zdarzeń na Dysku dotyczącą pliku lub folderu, aby nasłuchiwać zdarzeń zmiany treści. Więcej informacji znajdziesz w artykule Tworzenie subskrypcji Google Workspace.

Aby uruchomić ten przykład, musisz mieć zainstalowane środowisko Node.js i menedżer pakietów npm. Musisz też upewnić się, że 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, która pozwala 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/v1/subscriptions';
  const data = {
    targetResource: 'TARGET_RESOURCE',
    eventTypes: ['EVENT_TYPES'],
    payload_options: {
      include_resource: {
        {
          'RESOURCE_DATA'
        }
      }
    },
    drive_options: {
      include_descendants: {
        {
          'INCLUDE_DESCENDANTS'
        }
      }
    },
    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 te elementy:

• SCOPES: co najmniej 1 zakres OAuth, który obsługuje każdy typ zdarzenia w subskrypcji. Sformatowane jako tablica ciągów znaków. Aby wyświetlić listę wielu zakresów, oddziel je przecinkami. Zalecaną sprawdzoną metodą jest 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, który chcesz 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 zawiera dane zasobu w ładunku zdarzenia. Ta właściwość wpływa na czas trwania subskrypcji. Więcej informacji znajdziesz w artykule Dane zdarzeń.

  • True: obejmuje wszystkie dane zasobów. Aby ograniczyć uwzględniane pola, dodaj fieldMask i określ co najmniej 1 pole zmienionego zasobu. Tylko subskrypcje zasobów Google 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 z typem MIME ustawionym na application/vnd.google-apps.folder. Nie można jej ustawić w folderze głównym Mojego dysku ani dysków współdzielonych.

  • True: subskrypcja obejmuje wszystkie pliki podrzędne na Dysku na liście zdarzeń.

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

• TOPIC_NAME: pełna nazwa tematu Pub/Sub utworzonego w projekcie w chmurze. Ten temat Pub/Sub odbiera zdarzenia dotyczące 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 aktywatora upewnij się, że temat Pub/Sub dla aktywatora 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 plik package.json pod kątem 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);
  }
});

• Gdy pole logiczne includeDescendants w DriveOptions ma wartość true, subskrypcje Dysku na dyskach współdzielonych i w folderach zawsze wysyłają zdarzenie, nawet jeśli plik, który je wywołał, jest zagnieżdżony wiele warstw 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 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 będą wywoływać 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ą swojego konta Google Workspace lub konta Google.

Informacje o limitach subskrypcji i ograniczeniach liczby żądań znajdziesz w artykule o limitach wykorzystania interfejsu Google Workspace Events API.

Powiązane artykuły

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