O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Trabalhar com eventos do Google Drive

Nesta página, explicamos como receber eventos do Google Drive de Google Cloud Pub/Sub.

Um evento do Drive representa uma atividade ou mudança em um recurso do Drive, como um novo arquivo em uma pasta. Você pode usar eventos para entender o que aconteceu e tomar medidas ou responder de maneira significativa aos usuários.

Confira alguns exemplos de como usar eventos:

Observe e responda a mudanças em um arquivo, pasta ou drive compartilhado, como quando um arquivo é editado ou uma nova revisão é enviada.
Monitore as mudanças nos arquivos para melhorar a performance do seu app.
Audite atividades como compartilhamento, movimentação e exclusão de arquivos para ajudar a detectar possíveis vazamentos de dados e acesso não autorizado.
Ofereça insights sobre como os usuários estão gerenciando os arquivos, ajudando a identificar áreas em que o gerenciamento de conteúdo pode ser melhorado.
Acompanhe as mudanças nos arquivos para verificar a conformidade com os requisitos regulamentares ou as políticas de segurança.
Analise a atividade do Drive usando outros produtos do Google Cloud , como Eventarc, Workflows, e BigQuery.

Como os eventos funcionam

Sempre que algo acontece no Drive, um recurso da API Google Drive é criado, atualizado ou excluído. O Drive usa eventos para fornecer informações ao seu app sobre o tipo de atividade que ocorreu e o recurso da API Drive afetado.

O Drive categoriza os eventos por tipo. Os tipos de eventos ajudam a filtrar e receber apenas o tipo de informação necessário e permitem que você processe atividades semelhantes da mesma maneira.

A tabela a seguir mostra como uma atividade de exemplo no Drive afeta um recurso relacionado da API Drive e o tipo de evento que o app Drive recebe:

Atividade	Recurso da API Drive	Tipo de evento
Um usuário cria uma proposta de acesso em um arquivo.	Um `AccessProposal` recurso é criado.	Nova proposta de acesso
Um usuário cria uma aprovação em um arquivo.	Um `Approval` recurso é criado.	Nova aprovação
Um usuário posta um comentário em um arquivo do Google Docs, Sheets ou Slides.	Um recurso `Comment` é criado.	Novo comentário
Um usuário adiciona um arquivo a uma pasta ou drive compartilhado.	Um recurso `File` é criado.	Novo arquivo
Um usuário cria permissões em um arquivo.	Um recurso `Permission` é criado.	Nova permissão
Um usuário responde a um comentário.	Um recurso `Reply` é criado.	Nova resposta

Receber eventos do Google Drive

Tradicionalmente, o app Drive pode localizar eventos pela API Drive ou pela API Google Drive Activity. Com a adição de eventos do Drive na API Google Workspace Events, agora há um terceiro método para receber eventos:

Inscreva-se em eventos usando a API Google Workspace Events para recebê-los à medida que ocorrem. Para mais informações, consulte Inscrever-se em eventos do Google Drive.
Inscreva-se em eventos usando a API Drive. Receba eventos de mudança do usuário com o changes.watch método ou eventos de mudança de arquivo usando o files.watch método.
Consulte eventos recentes chamando a API Google Drive Activity.

A tabela a seguir explica a diferença e os motivos para se inscrever em eventos em vez de consultá-los:

	Inscrever-se em eventos do Google Workspace	Inscrever-se em eventos de observação da API Drive	Consultar eventos da API Drive Activity
Casos de uso	Processar ou responder a eventos em tempo real. Monitore as mudanças nos recursos para melhorar a performance do seu app. Receba dados de eventos estruturados pelo Pub/Sub e use produtos do Google Cloud, como o Cloud Run.	Detecte mudanças nos metadados de arquivos e monitore com eficiência as mudanças em itens específicos com notificações em tempo real. Oferece suporte a um URL de callback de webhook para evitar a pesquisa repetida dos endpoints da API.	Busque um histórico detalhado de todas as atividades, incluindo informações granulares sobre cada evento. Recupere atividades precisas que incluem informações `ActionDetail`, `Actor` e `Target` para tarefas específicas, como auditorias.
API	API Google Workspace Events	API Google Drive	API Google Drive Activity
Fonte de eventos	Arquivos, pastas e drives compartilhados	`changes.watch` e `files.watch`	`DriveActivity`
Eventos aceitos	`AccessProposal` `Approval` `Comment` `File` `Permission` `Reply` Para uma lista de tipos de eventos aceitos, consulte Tipos de eventos para criar assinaturas na documentação da API Google Workspace Events.	`Channel` Para uma lista de tipos de eventos aceitos, consulte Entender os eventos de notificação da API Google Drive na documentação da API Drive.	`Action` Para uma lista de campos aceitos, consulte o recurso `Action` na documentação de referência da API Drive Activity .
Formato de eventos	Uma mensagem do Pub/Sub, formatada de acordo com a CloudEvent specification. Para mais detalhes, consulte Estrutura dos eventos do Google Workspace.	Um recurso da API Drive (`Channel`)	Um recurso da API Drive Activity (`Action`)
Dados de eventos	String codificada em Base64 com ou sem dados de recursos. Para exemplos de payloads, consulte Dados de eventos.	Payload JSON que contém dados de recursos. Para um exemplo de payload, consulte o `Channel` recurso na documentação de referência.	Payload JSON que contém dados de recursos. Para um exemplo de payload, consulte o `activity.query` corpo da resposta na documentação de referência.

Começar a usar eventos do Drive

Este guia explica como criar e gerenciar uma assinatura de eventos do Google Workspace em um recurso do Drive. Isso permite que seu app receba eventos pelo Google Cloud Pub/Sub.

Criar um projeto do Google Cloud

Para gerar um projeto do Google Cloud, consulte Criar um projeto do Google Cloud project.

Ativar a API Google Workspace Events, a API Google Cloud Pub/Sub e a API Google Drive

Antes de usar as APIs do Google, é necessário ativá-las em um projeto do Google Cloud. É possível ativar uma ou mais APIs em um único projeto do Google Cloud.

Console do Google Cloud

No console do Google Cloud, abra o projeto na nuvem do Google Cloud para seu app e ative a API Google Workspace Events, a API Pub/Sub e a API Drive:

Ativar as APIs
Confirme se você está ativando as APIs no projeto na nuvem correto e clique em Próxima.
Confirme se você está ativando as APIs corretas e clique em Ativar.

gcloud

No diretório de trabalho, faça login na sua Conta do Google:
```
gcloud auth login
```
Defina seu projeto como o projeto na nuvem para seu app:
```
gcloud config set project PROJECT_ID
```
Substitua PROJECT_ID pelo ID do projeto do projeto na nuvem para seu app.

Ative a API Google Workspace Events, a API Pub/Sub e a API Drive:

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

Configurar um ID do cliente

Para gerar um ID do cliente OAuth 2.0, consulte Criar credenciais de ID do cliente OAuth.

Criar um tópico do Pub/Sub

Antes de criar uma assinatura, é necessário criar um tópico do Google Cloud Pub/Sub que receba eventos relevantes para seu aplicativo. Para criar o tópico do Pub/Sub, consulte Criar e inscrever-se em um tópico do Pub/Sub tópico.

Faça referência à conta de serviço do Drive (drive-api-event-push@system.gserviceaccount.com) para suas solicitações.

Criar uma assinatura do Drive

Os eventos do Cloud são enviados quando o assunto da assinatura (ou qualquer outro arquivo na hierarquia do assunto) muda. Por exemplo, se você criar uma assinatura em um drive compartilhado e um arquivo mudar que esteja aninhado em várias subpastas nesse drive compartilhado, um evento será gerado. Para recursos aceitos e tipos de eventos do Drive, consulte Tipos de eventos para criar assinaturas.

O aplicativo Node.js a seguir cria uma assinatura de eventos do Drive em um arquivo ou pasta para detectar eventos de mudança de conteúdo. Para mais informações, consulte Criar uma assinatura do Google Workspace subscription.

Para executar este exemplo, verifique se o Node.js e o npm estão instalados. Você também precisa verificar se tem as dependências necessárias instaladas para executar este exemplo.

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

Para criar uma assinatura do Drive, use o método subscriptions.create da API Google Workspace Events para criar um Subscription recurso:

// 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);

Substitua:

SCOPES: um ou mais escopos OAuth que oferecem suporte a cada tipo de evento para a assinatura. Formatado como uma matriz de strings. Para listar vários escopos, separe-os por vírgulas. Como prática recomendada, use o escopo mais restritivo que ainda permita que seu app funcione. Por exemplo, 'https://www.googleapis.com/auth/drive.file'.
TARGET_RESOURCE: o recurso do Google Workspace a que você está se inscrevendo, formatado como o nome completo do recurso. Por exemplo, para se inscrever em um arquivo ou pasta do Drive, use //drive.googleapis.com/files/FileID.
EVENT_TYPES: um ou mais tipos de eventos a que você quer se inscrever no recurso de destino. Formate como uma matriz de strings, como 'google.workspace.drive.file.v3.contentChanged'.
RESOURCE_DATA: um booleano que especifica se a assinatura inclui dados de recursos no payload do evento. Essa propriedade afeta a duração da assinatura. Para saber mais, consulte Dados de eventos.
- True: inclui todos os dados de recursos. Para limitar os campos incluídos, adicione o fieldMask e especifique pelo menos um campo para o recurso alterado. Somente as assinaturas de recursos do Chat e do Drive oferecem suporte à inclusão de dados de recursos.
- False: exclui dados de recursos.
INCLUDE_DESCENDANTS: um campo booleano que faz parte de DriveOptions. Disponível apenas quando o targetResource é um arquivo do Drive ou um drive compartilhado que tem o tipo MIME definido como application/vnd.google-apps.folder. Não pode ser definido na pasta raiz do Meu Drive ou em drives compartilhados.
- True: a assinatura inclui todos os arquivos descendentes do Drive na lista de eventos.
- False: a assinatura é criada para o arquivo único ou drive compartilhado especificado como targetResource.
TOPIC_NAME: o nome completo do tópico do Pub/Sub que você criou no projeto na nuvem. Esse tópico do Pub/Sub recebe eventos para a assinatura. Formatado como projects/PROJECT_ID/topics/TOPIC_ID. O notificationEndpoint campo é usado para especificar o tópico do Pub/Sub e é onde a assinatura entrega eventos.

Testar a assinatura do Drive

Para testar se você está recebendo eventos do Drive, acione um evento e extraia mensagens para a assinatura do Pub/Sub. Para mais informações, consulte Testar a assinatura do Google Workspace.

Processar eventos do Drive usando o Cloud Functions

Os eventos do Drive são enviados para o tópico do Pub/Sub na assinatura que você cria. Ao criar o gatilho, verifique se o tópico do Pub/Sub para o gatilho corresponde ao tópico do Pub/Sub na assinatura do evento. Em seguida, você pode implantar a função do Cloud Run e fazer edições no arquivo para conferir as mudanças de eventos nos registros.

Antes de criar a função, atualize o package.json para as dependências:

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

Em seguida, crie o código-fonte da função:

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);
  }
});

Limitações

Quando o campo booleano includeDescendants em DriveOptions é true, as assinaturas do Drive em drives e pastas compartilhados sempre enviam um evento, mesmo que o arquivo que acionou o evento esteja aninhado em muitas camadas abaixo da pasta usada para a assinatura do Drive.
Mesmo que você tenha criado uma assinatura em uma pasta, talvez não receba todos os eventos na hierarquia de arquivos, já que o usuário ou aplicativo pode não ter acesso a eles. Nesse caso, a assinatura permanece ativa, mas você não receberá eventos para recursos aos quais não tem acesso.
As assinaturas são aceitas para eventos em todos os arquivos e pastas, mas não na pasta raiz de drives compartilhados. As assinaturas são aceitas apenas para arquivos e pastas dentro de drives compartilhados. As mudanças feitas diretamente na pasta raiz de um drive compartilhado não acionam eventos.
O usuário que autoriza a assinatura precisa ter permissão no arquivo correspondente aos eventos a que ele se inscreve.
A assinatura só recebe eventos para recursos em que o usuário tem acesso por meio d e sua conta do Google Workspace ou Conta do Google.

Trabalhar com eventos do Google Drive Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.