REST Resource: subscriptions

Risorsa: Abbonamento

Un abbonamento per ricevere eventi relativi a una risorsa Google Workspace. Per scoprire di più sugli abbonamenti, consulta la panoramica dell'API Google Workspace Events.

Rappresentazione JSON 
{
  "name": string,
  "uid": string,
  "targetResource": string,
  "eventTypes": [
    string
  ],
  "payloadOptions": {
    object (PayloadOptions)
  },
  "notificationEndpoint": {
    object (NotificationEndpoint)
  },
  "state": enum (State),
  "suspensionReason": enum (ErrorType),
  "authority": string,
  "createTime": string,
  "updateTime": string,
  "reconciling": boolean,
  "etag": string,

  // Union field subscription_options can be only one of the following:
  "driveOptions": {
    object (DriveOptions)
  }
  // End of list of possible types for union field subscription_options.

  // Union field expiration can be only one of the following:
  "expireTime": string,
  "ttl": string
  // End of list of possible types for union field expiration.
}
Campi
name

string

Identificatore. Nome della risorsa dell'abbonamento.

Formato: subscriptions/{subscription}
uid

string

Solo output. Identificatore univoco assegnato dal sistema per l'abbonamento.
targetResource

string

Obbligatorio. Immutabile. La risorsa Google Workspace monitorata per gli eventi, formattata come nome completo della risorsa. Per scoprire di più sulle risorse di destinazione e sugli eventi che supportano, consulta Eventi Google Workspace supportati.

Un utente può autorizzare la tua app a creare un solo abbonamento per una determinata risorsa di destinazione. Se la tua app tenta di creare un altro abbonamento con le stesse credenziali utente, la richiesta restituisce un errore ALREADY_EXISTS.
eventTypes[]

string

Obbligatorio. Elenco non ordinato. Input per la creazione di un abbonamento. In caso contrario, solo output. Uno o più tipi di eventi da ricevere sulla risorsa di destinazione. Formattato in base alla specifica CloudEvents.

I tipi di eventi supportati dipendono dalla risorsa di destinazione del tuo abbonamento. Per maggiori dettagli, vedi Eventi Google Workspace supportati.

Per impostazione predefinita, ricevi anche eventi relativi al ciclo di vita del tuo abbonamento. Non è necessario specificare gli eventi del ciclo di vita per questo campo.

Se specifichi un tipo di evento che non esiste per la risorsa di destinazione, la richiesta restituisce un codice di stato HTTP 400 Bad Request.
payloadOptions

object (PayloadOptions)

(Facoltativo) Opzioni relative ai dati da includere nel payload dell'evento. Supportato solo per gli eventi di Google Chat e Google Drive.
notificationEndpoint

object (NotificationEndpoint)

Obbligatorio. Immutabile. L'endpoint in cui la sottoscrizione pubblica gli eventi, ad esempio un argomento Pub/Sub.
state

enum (State)

Solo output. Lo stato dell'abbonamento. Determina se l'abbonamento può ricevere eventi e inviarli all'endpoint di notifica.
suspensionReason

enum (ErrorType)

Solo output. L'errore che ha comportato la sospensione dell'abbonamento.

Per riattivare l'abbonamento, risolvi l'errore e chiama il metodo subscriptions.reactivate.
authority

string

Solo output. L'utente che ha autorizzato la creazione dell'abbonamento.

Formato: users/{user}

Per gli utenti di Google Workspace, il valore {user} è il campo user.id dell'API Directory.
createTime

string (Timestamp format)

Solo output. L'ora in cui viene creato l'abbonamento.
updateTime

string (Timestamp format)

Solo output. L'ultima volta che l'abbonamento è stato aggiornato.
reconciling

boolean

Solo output. Se true, l'abbonamento è in fase di aggiornamento.
etag

string

(Facoltativo) Questo checksum viene calcolato dal server in base al valore di altri campi e potrebbe essere inviato nelle richieste di aggiornamento per garantire che il client disponga di un valore aggiornato prima di procedere.
Campo unione subscription_options. Opzioni di abbonamento aggiuntive disponibili per risorse di destinazione specifiche per gli abbonamenti a Google Workspace. subscription_options può essere solo uno dei seguenti:
driveOptions

object (DriveOptions)

(Facoltativo) Funzionalità supportate solo per gli abbonamenti alle risorse di Drive.

Campo unione expiration. L'ora in cui scade l'abbonamento.

Il tempo di scadenza massimo dipende dal fatto che l'abbonamento includa dati delle risorse nei payload degli eventi (specificati nel campo PayloadOptions):

  • Se i payload omettono i dati delle risorse, fino a 7 giorni.
  • Se i payload includono dati delle risorse, fino a 4 ore. Se la tua organizzazione Google Workspace concede l'accesso alla risorsa tramite la delega a livello di dominio, puoi estendere la scadenza dell'abbonamento fino a 24 ore.

Una volta scaduto, l'abbonamento viene eliminato automaticamente. Ricevi gli eventi del ciclo di vita notification_endpoint 12 ore e 1 ora prima della scadenza dell'abbonamento. Per maggiori dettagli, vedi Ricevere e rispondere agli eventi del ciclo di vita.

Per evitare che una sottoscrizione scada, puoi utilizzare il metodo UpdateSubscription per estenderne la data di scadenza. Per maggiori dettagli, vedi Aggiornare o rinnovare un abbonamento. expiration può essere solo uno dei seguenti:
expireTime

string (Timestamp format)

Valore predefinito non vuoto. Il timestamp in UTC di quando scade l'abbonamento. Viene sempre visualizzato nell'output, indipendentemente da ciò che è stato utilizzato nell'input.
ttl

string (Duration format)

Solo input. La durata (TTL) dell'abbonamento. Se non specificato o impostato su 0, utilizza la durata massima possibile.

DriveOptions

Opzioni aggiuntive supportate per la pubblicazione degli eventi di Drive.

Rappresentazione JSON 
{
  "includeDescendants": boolean
}
Campi
includeDescendants

boolean

(Facoltativo) Immutabile. Per gli abbonamenti agli eventi di Google Drive, se ricevere eventi relativi ai file di Drive che sono figli della cartella o del Drive condiviso di destinazione.

  • Se false, l'abbonamento riceve solo eventi relativi alle modifiche alla cartella o al Drive condiviso specificato come targetResource.
  • Se true, il campo mimeType della risorsa file deve essere impostato su application/vnd.google-apps.folder.

Per maggiori dettagli, vedi Tipi di eventi di Google Drive.

PayloadOptions

Opzioni relative ai dati da includere nel payload dell'evento. Supportato solo per gli eventi di Google Chat e Google Drive.

Rappresentazione JSON 
{
  "includeResource": boolean,
  "fieldMask": string
}
Campi
includeResource

boolean

(Facoltativo) Indica se il payload dell'evento include dati sulla risorsa modificata. Ad esempio, per un evento in cui è stato creato un messaggio di Google Chat, se il payload contiene dati sulla risorsa Message. Se è false, il payload dell'evento include solo il nome della risorsa modificata.
fieldMask

string (FieldMask format)

(Facoltativo) Se includeResource è impostato su true, l'elenco dei campi da includere nel payload dell'evento. Separa i campi con una virgola. Ad esempio, per includere il mittente e l'ora di creazione di un messaggio di Google Chat, inserisci message.sender,message.createTime. Se omesso, il payload include tutti i campi per la risorsa.

Se specifichi un campo che non esiste per la risorsa, il sistema lo ignora.

NotificationEndpoint

L'endpoint in cui l'abbonamento pubblica gli eventi.

Rappresentazione JSON 
{

  // Union field endpoint can be only one of the following:
  "pubsubTopic": string
  // End of list of possible types for union field endpoint.
}
Campi

Campo unione endpoint.

endpoint può essere solo uno dei seguenti:
pubsubTopic

string

Immutabile. L'argomento Pub/Sub che riceve gli eventi per la sottoscrizione.

Formato: projects/{project}/topics/{topic}

Devi creare l'argomento nello stesso progetto Google Cloud in cui crei questo abbonamento.

Nota: l'API Google Workspace Events utilizza le chiavi di ordinamento a vantaggio degli eventi sequenziali. Se l'argomento Cloud Pub/Sub ha una policy di archiviazione dei messaggi configurata per escludere la regione Google Cloud più vicina, la pubblicazione di eventi con chiavi di ordinamento non andrà a buon fine.

Quando l'argomento riceve eventi, questi vengono codificati come messaggi Pub/Sub. Per maggiori dettagli, vedi Google Cloud Pub/Sub Protocol Binding for CloudEvents.

Stato

Stati possibili per l'abbonamento.

Enum
STATE_UNSPECIFIED Valore predefinito. Questo valore non viene utilizzato.
ACTIVE L'abbonamento è attivo e può ricevere e distribuire eventi al relativo endpoint di notifica.
SUSPENDED La sottoscrizione non può ricevere eventi a causa di un errore. Per identificare l'errore, consulta il campo suspensionReason.
DELETED L'abbonamento viene eliminato.

ErrorType

Possibili errori per un abbonamento.

Enum
ERROR_TYPE_UNSPECIFIED Valore predefinito. Questo valore non viene utilizzato.
USER_SCOPE_REVOKED L'utente che ha autorizzato ha revocato la concessione di uno o più ambiti OAuth. Per scoprire di più sull'autorizzazione per Google Workspace, vedi Configurare la schermata per il consenso OAuth.
RESOURCE_DELETED La risorsa di destinazione per l'abbonamento non esiste più.
USER_AUTHORIZATION_FAILURE L'utente che ha autorizzato la creazione dell'abbonamento non ha più accesso alla risorsa di destinazione dell'abbonamento.
ENDPOINT_PERMISSION_DENIED L'applicazione Google Workspace non ha accesso per inviare eventi all'endpoint di notifica del tuo abbonamento.
ENDPOINT_NOT_FOUND L'endpoint di notifica dell'abbonamento non esiste o non è possibile trovarlo nel progetto Google Cloud in cui hai creato l'abbonamento.
ENDPOINT_RESOURCE_EXHAUSTED L'endpoint di notifica dell'abbonamento non ha ricevuto eventi a causa di una quota insufficiente o del raggiungimento del limite di frequenza.
OTHER Si è verificato un errore non identificato.

Metodi

create

 Crea un abbonamento a Google Workspace.

delete

 Elimina un abbonamento a Google Workspace.

get

 Recupera i dettagli di un abbonamento a Google Workspace.

list

 Elenca gli abbonamenti a Google Workspace.

patch

 Aggiorna o rinnova un abbonamento a Google Workspace.

reactivate

 Riattiva un abbonamento a Google Workspace sospeso.