Creare un abbonamento a Google Workspace

Apps Script

• Per utilizzare i comandi di Google Cloud CLI in questa guida:
  1. Installa Google Cloud CLI.
  2. Per inizializzare l'interfaccia a riga di comando gcloud, esegui questo codice:

    gcloud init
    

• Un progetto Apps Script:
  • Utilizza il tuo progetto Google Cloud anziché quello predefinito creato automaticamente da Apps Script.
  • Per tutti gli ambiti che hai aggiunto per configurare la schermata per il consenso OAuth, devi aggiungere gli ambiti anche al file appsscript.json nel tuo progetto Apps Script. Ad esempio, se hai specificato l'ambito chat.messages, aggiungi quanto segue:

  "oauthScopes": [
    "https://www.googleapis.com/auth/chat.messages"
  ]
      

  • Attiva il servizio avanzato Google Workspace Events.

• Un progetto Google Cloud con la fatturazione abilitata. Per gli abbonamenti a Chat, devi anche attivare l'API Chat nel tuo progetto Cloud e configurare i campi Nome app, URL avatar e Descrizione. Per maggiori dettagli, consulta Crea un'app Google Chat.
• Richiede l'autenticazione e un ambito di autorizzazione appropriato per ogni tipo di evento nell'abbonamento:
  • In genere richiede l'autenticazione dell'utente con la schermata per il consenso OAuth configurata per l'app. Quando configuri la schermata per il consenso, devi specificare un ambito per supportare ogni tipo di evento per l'abbonamento. Per configurare la schermata per il consenso e identificare gli ambiti richiesti, consulta Scegli gli ambiti.
  • Per iscriversi a un evento di Chat come app di Chat, è necessaria l'autenticazione dell'app con l'approvazione una tantum dell'amministratore.

Python

• Python 3.6 o versioni successive
• Lo strumento di gestione dei pacchetti pip
• Le librerie client di Google più recenti per Python. Per installarli o aggiornarli, esegui questo comando nell'interfaccia a riga di comando:

    pip3 install --upgrade google-api-python-client google-auth-oauthlib
    

• Per utilizzare i comandi di Google Cloud CLI in questa guida:
  1. Installa Google Cloud CLI.
  2. Per inizializzare l'interfaccia a riga di comando gcloud, esegui questo codice:

    gcloud init
    

• Un progetto Google Cloud con la fatturazione abilitata. Per gli abbonamenti a Chat, devi anche attivare l'API Chat nel tuo progetto Cloud e configurare i campi Nome app, URL avatar e Descrizione. Per maggiori dettagli, consulta Crea un'app Google Chat.
• Richiede l'autenticazione e un ambito di autorizzazione appropriato per ogni tipo di evento nell'abbonamento:
  • In genere richiede l'autenticazione dell'utente con la schermata per il consenso OAuth configurata per l'app. Quando configuri la schermata per il consenso, devi specificare un ambito per supportare ogni tipo di evento per l'abbonamento. Per configurare la schermata per il consenso e identificare gli ambiti richiesti, consulta Scegli gli ambiti.
  • Per iscriversi a un evento di Chat come app di Chat, è necessaria l'autenticazione dell'app con l'approvazione una tantum dell'amministratore.

Console Google Cloud

Nella console Google Cloud, apri il progetto cloud per la tua app e attiva l'API Google Workspace Events e l'API Pub/Sub:

Abilita le API

gcloud

1. Nella directory di lavoro, accedi al tuo Account Google:

   gcloud auth login

2. Imposta il progetto sul progetto Cloud per la tua app:

   gcloud config set project PROJECT_ID

   Sostituisci PROJECT_ID con l'ID progetto del progetto Cloud per la tua app.

3. Abilita l'API Google Workspace Events e l'API Google Cloud Pub/Sub:

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

Console API di Google

1. Nella console API di Google, vai alla pagina Pub/Sub:

   Vai a Google Cloud Pub/Sub

   Assicurati che il progetto Cloud per la tua app sia selezionato.

2. Fai clic su add_box Crea argomento e segui questi passaggi:

   1. Inserisci un nome per l'argomento, ad esempio workspace-events-topic.
   2. Lascia selezionata l'opzione Aggiungi una sottoscrizione predefinita. Pub/Sub assegna a questa sottoscrizione predefinita un nome simile a quello dell'argomento, ad esempio workspace-events-topic-sub.
   3. (Facoltativo) Aggiorna o configura altre proprietà per l'argomento.

3. Fai clic su Crea. Il nome completo dell'argomento è formattato come projects/PROJECT_ID/topics/TOPIC_ID. Utilizza questo nome completo in un passaggio successivo.

4. Concedi l'accesso per pubblicare messaggi Pub/Sub nel tuo argomento:

   1. Nella pagina dell'argomento, vai al riquadro laterale e apri la scheda Autorizzazioni.
   2. Fai clic su Aggiungi entità.
   3. Nel campo Aggiungi entità, aggiungi il service account per l'applicazione Google Workspace che invia gli eventi alla tua sottoscrizione:
      1. Per gli eventi di Chat, chat-api-push@system.gserviceaccount.com.
      2. Per gli eventi di Drive, drive-api-event-push@system.gserviceaccount.com.
      3. Per gli eventi di Meet, meet-api-event-push@system.gserviceaccount.com.
   4. Nel menu Assegna i ruoli, seleziona Pub/Sub Publisher.
   5. Fai clic su Salva. L'aggiornamento delle autorizzazioni per l'argomento può richiedere alcuni minuti.

gcloud

1. Nel tuo progetto cloud, crea un argomento eseguendo questo comando:

   gcloud pubsub topics create TOPIC_ID

   Sostituisci TOPIC_ID con un ID univoco per l'argomento, ad esempio workspace-events-topic.

   L'output mostra il nome completo dell'argomento, formattato come projects/PROJECT_ID/topics/TOPIC_ID. Prendi nota del nome e assicurati che il valore di PROJECT_ID sia l'ID progetto cloud della tua app. Utilizza il nome dell'argomento nel passaggio successivo e per creare l'abbonamento a Google Workspace in un secondo momento.

2. Concedi l'accesso per pubblicare messaggi nel tuo argomento:

   gcloud pubsub topics add-iam-policy-binding TOPIC_NAME --member='serviceAccount:GOOGLE_WORKSPACE_APPLICATION' --role='roles/pubsub.publisher'

   Sostituisci quanto segue:

   • TOPIC_NAME: il nome completo dell'argomento, che è l'output del passaggio precedente. Formattato come projects/PROJECT_ID/topics/TOPIC_ID.

   • GOOGLE_WORKSPACE_APPLICATION: l'applicazione Google Workspace che deve inviare eventi alla tua sottoscrizione:

     • Per ricevere eventi da Chat, utilizza uno dei seguenti service account:
       • Per le app di Chat (create come componenti aggiuntivi di Google Workspace che estendono Chat), utilizza l'indirizzo email del service account nella pagina di configurazione dell'API Chat. Per saperne di più, consulta Crea un'app Google Chat che utilizza Pub/Sub.
       • Per le app di Chat che non sono componenti aggiuntivi, utilizza chat-api-push@system.gserviceaccount.com. Per saperne di più, consulta Crea un'app Google Chat che utilizza Pub/Sub.
     • Per ricevere eventi da Drive, utilizza drive-api-event-push@system.gserviceaccount.com.
     • Per ricevere eventi da Meet, utilizza meet-api-event-push@system.gserviceaccount.com.

   L'aggiornamento delle autorizzazioni per l'argomento può richiedere alcuni minuti.

3. Crea una sottoscrizione Pub/Sub per l'argomento:

    gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME

   Sostituisci quanto segue:

   • SUBSCRIPTION_NAME: un nome per la sottoscrizione, ad esempio workspace-events-subscription.
   • TOPIC_NAME: il nome dell'argomento creato nel passaggio precedente.

Apps Script

1. Nel progetto Apps Script, crea un nuovo file di script denominato createSubscription e aggiungi il seguente codice:

   function createSubscription() {
     // The Google Workspace resource to monitor for events.
     const targetResource = 'TARGET_RESOURCE';
   
     // The types of events to receive.
     const eventTypes = [EVENT_TYPES];
   
     // The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
     const pubsubTopic = 'TOPIC_NAME';
   
     // Whether to include resource data or not.
     const resourceData = RESOURCE_DATA;
   
     // Call the Workspace Events API using the advanced service.
     const response = WorkspaceEvents.Subscriptions.create({
       targetResource: targetResource,
       eventTypes: eventTypes,
       notificationEndpoint: {
         pubsubTopic: pubsubTopic,
       },
       payloadOptions: {
         includeResource: resourceData
       }
     });
     console.log(response);
   }
   

   Sostituisci quanto segue:

   • TARGET_RESOURCE: la risorsa Google Workspace a cui ti stai iscrivendo, formattata con il nome completo della risorsa. Ad esempio, per iscriverti a uno spazio di Chat con l'ID spazio AAAABBBB, utilizza //chat.googleapis.com/spaces/AAAABBBB.
   • EVENT_TYPES: uno o più tipi di eventi a cui vuoi iscriverti nella risorsa di destinazione. Formato come array di stringhe, ad esempio 'google.workspace.chat.message.v1.created'.
   • TOPIC_NAME: il nome completo dell'argomento Pub/Sub che hai creato nel tuo progetto Cloud. Formattato come projects/PROJECT_ID/topics/TOPIC_ID.

   • RESOURCE_DATA: un valore booleano che specifica se la sottoscrizione include i dati della risorsa nel payload:

     • True: include tutti i dati delle risorse. Per limitare i campi inclusi, aggiungi il campo fieldMask e specifica almeno un campo per la risorsa modificata. Solo gli abbonamenti alle risorse di Chat supportano l'inclusione dei dati delle risorse.
     • False: esclude i dati delle risorse.

2. Per creare l'abbonamento a Google Workspace, esegui la funzione createSubscription nel tuo progetto Apps Script.

Python

1. Nella directory di lavoro, crea un file denominato create_subscription.py e aggiungi il seguente codice:

   """Create subscription."""
   
   from google_auth_oauthlib.flow import InstalledAppFlow
   from googleapiclient.discovery import build
   
   # Specify required scopes.
   SCOPES = [SCOPES]
   
   # Authenticate with Google Workspace and get user authentication.
   flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
   CREDENTIALS = flow.run_local_server()
   
   # The Google Workspace resource to monitor for events.
   TARGET_RESOURCE = 'TARGET_RESOURCE'
   
   # The types of events to receive.
   EVENT_TYPES = [EVENT_TYPES]
   
   # The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
   TOPIC = 'TOPIC_NAME'
   
   # Call the Workspace Events API using the service endpoint.
   service = build(
       'workspaceevents',
       'v1',
       credentials=CREDENTIALS,
   )
   
   BODY = {
       'target_resource': TARGET_RESOURCE,
       'event_types': EVENT_TYPES,
       'notification_endpoint': {'pubsub_topic': TOPIC},
       'payload_options': {'include_resource': RESOURCE_DATA},
   }
   response = service.subscriptions().create(body=BODY).execute()
   print(response)
   

   Sostituisci quanto segue:

   • SCOPES: uno o più ambiti OAuth che supportano ogni tipo di evento per l'abbonamento. Formattato come array di stringhe. Per elencare più ambiti, separali con virgole. Ad esempio: 'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'.
   • TARGET_RESOURCE: la risorsa Google Workspace a cui ti stai iscrivendo, formattata con il nome completo della risorsa. Ad esempio, per iscriverti a uno spazio di Chat con l'ID spazio AAAABBBB, utilizza //chat.googleapis.com/spaces/AAAABBBB.
   • EVENT_TYPES: uno o più tipi di eventi a cui vuoi iscriverti nella risorsa di destinazione. Formato come array di stringhe, ad esempio 'google.workspace.chat.message.v1.created'.
   • TOPIC_NAME: il nome completo dell'argomento Pub/Sub che hai creato nel tuo progetto Cloud. Formattato come projects/PROJECT_ID/topics/TOPIC_ID.

   • RESOURCE_DATA: un valore booleano che specifica se la sottoscrizione include i dati della risorsa nel payload:

     • True: include tutti i dati delle risorse. Per limitare i campi inclusi, aggiungi il campo fieldMask e specifica almeno un campo per la risorsa modificata. Solo gli abbonamenti alle risorse di Chat supportano l'inclusione dei dati delle risorse.
     • False: esclude i dati delle risorse.

2. Per creare l'abbonamento a Google Workspace, esegui questo comando nel terminale:

   python3 create_subscription.py

Console API di Google

1. Attiva uno o più tipi di eventi nella risorsa di destinazione del tuo abbonamento a Google Workspace. Ad esempio, se hai effettuato l'iscrizione ai nuovi messaggi in uno spazio di Chat, pubblica un messaggio nello spazio.

2. Nella console API di Google, vai alla pagina Pub/Sub:

   Vai a Pub/Sub.

   Assicurati che il progetto Cloud per la tua app sia selezionato.

3. Nel menu Pub/Sub, fai clic su Sottoscrizioni.

4. Nella tabella, individua la sottoscrizione Pub/Sub per l'argomento e fai clic sul nome della sottoscrizione.

5. Fai clic sulla scheda Messaggi.

6. Fai clic su Pull. La generazione di un messaggio Pub/Sub da parte di un evento può richiedere alcuni minuti.

gcloud

1. Attivare uno o più tipi di eventi nella risorsa di destinazione del tuo abbonamento a Google Workspace. Ad esempio, se hai effettuato l'iscrizione ai nuovi messaggi in uno spazio di Chat, pubblica un messaggio nello spazio.

2. Esegui questo comando:

   gcloud pubsub subscriptions pull PUBSUB_SUBSCRIPTION_NAME --format=json --limit=MESSAGE_COUNT --auto-ack

   Sostituisci quanto segue:

   • PUBSUB_SUBSCRIPTION_NAME: il nome completo della tua sottoscrizione Pub/Sub, formattato come projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID.
   • MESSAGE_COUNT: il numero massimo di messaggi Pub/Sub che vuoi estrarre.

   La generazione di un messaggio Pub/Sub da parte di un evento può richiedere fino a qualche minuto.

Python

  """Create subscription."""

  from google.oauth2 import service_account
  from apiclient.discovery import build

  # Specify required scopes.
  SCOPES = ['https://www.googleapis.com/auth/chat.app.messages.readonly']

  # Specify service account details.
  CREDENTIALS = (
      service_account.Credentials.from_service_account_file('credentials.json')
      .with_scopes(SCOPES)
  )

  # The Google Workspace resource to monitor for events.
  TARGET_RESOURCE = '//chat.googleapis.com/spaces/SPACE_ID'

  # The types of events to receive.
  EVENT_TYPES = [
                  'google.workspace.chat.message.v1.created',
                  'google.workspace.chat.message.v1.updated',
                  'google.workspace.chat.message.v1.deleted',
                ]

  # The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
  TOPIC = 'TOPIC_NAME'

  # Call the Workspace Events API using the service endpoint.
  service = build(
      'workspaceevents',
      'v1',
      credentials=CREDENTIALS,
  )

  BODY = {
      'target_resource': TARGET_RESOURCE,
      'event_types': EVENT_TYPES,
      'notification_endpoint': {'pubsub_topic': TOPIC},
      'payload_options': {'include_resource': RESOURCE_DATA},
  }
  response = service.subscriptions().create(body=BODY).execute()
  print(response)

Python

"""Create a customer subscription."""

from google.oauth2 import service_account
from apiclient.discovery import build

# Specify required scopes.
# Replace with the scopes needed for the event types you want to receive.
SCOPES = ['https://www.googleapis.com/auth/chat.app.all.messages.readonly']

# Specify service account details.
CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
)

# Monitor all events for the Google Workspace organization.
TARGET_RESOURCE = '//admin.googleapis.com/customers/CUSTOMER_ID'

# The types of events to receive.
EVENT_TYPES = [
    'google.workspace.chat.message.v1.created',
    'google.workspace.chat.message.v1.updated',
    'google.workspace.chat.message.v1.deleted',
]

# The endpoint to deliver events to.
TOPIC = 'TOPIC_NAME'

# Call the Workspace Events API.
# Note: Use the v1beta endpoint for Developer Preview features.
service = build(
    'workspaceevents',
    'v1beta',
    credentials=CREDENTIALS,
)

BODY = {
    'target_resource': TARGET_RESOURCE,
    'event_types': EVENT_TYPES,
    'notification_endpoint': {'pubsub_topic': TOPIC},
    'payload_options': {'include_resource': RESOURCE_DATA},
}

response = service.subscriptions().create(body=BODY).execute()
print(response)