REST Resource: subscriptions

Recurso: Subscription

Uma assinatura para receber eventos sobre um recurso do Google Workspace. Para saber mais sobre as assinaturas, consulte a Visão geral da API Google Workspace Events.

Representação 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 expiration can be only one of the following:
  "expireTime": string,
  "ttl": string
  // End of list of possible types for union field expiration.
}
Campos
name

string

Identificador. Nome do recurso da assinatura.

Formato: subscriptions/{subscription}
uid

string

Apenas saída. Identificador exclusivo atribuído pelo sistema para a assinatura.
targetResource

string

Obrigatório. Imutável. O recurso do Google Workspace que é monitorado para eventos, formatado como o nome completo do recurso. Para saber mais sobre os recursos de destino e os eventos compatíveis, consulte Eventos do Google Workspace compatíveis.

Um usuário só pode autorizar seu app a criar uma assinatura para um determinado recurso de destino. Se o app tentar criar outra assinatura com as mesmas credenciais de usuário, a solicitação retornará um erro ALREADY_EXISTS.
eventTypes[]

string

Obrigatório. Lista não ordenada. Entrada para criar uma assinatura. Caso contrário, apenas saída. Um ou mais tipos de eventos para receber sobre o recurso de destino. Formatado de acordo com a especificação CloudEvents.

Os tipos de evento compatíveis dependem do recurso de destino da sua assinatura. Confira mais detalhes em Eventos do Google Workspace com suporte.

Por padrão, você também recebe eventos sobre o ciclo de vida da sua assinatura. Não é necessário especificar eventos de ciclo de vida para esse campo.

Se você especificar um tipo de evento que não existe para o recurso de destino, a solicitação vai retornar um código de status HTTP 400 Bad Request.
payloadOptions

object (PayloadOptions)

Opcional. Opções sobre quais dados incluir no payload do evento. Somente para eventos do Google Chat.
notificationEndpoint

object (NotificationEndpoint)

Obrigatório. Imutável. O endpoint em que a assinatura entrega eventos, como um tópico do Pub/Sub.
state

enum (State)

Apenas saída. O estado da assinatura. Determina se a assinatura pode receber eventos e enviá-los ao endpoint de notificação.
suspensionReason

enum (ErrorType)

Apenas saída. O erro que suspendeu a assinatura.

Para reativar a assinatura, resolva o erro e chame o método subscriptions.reactivate.
authority

string

Apenas saída. O usuário que autorizou a criação da assinatura.

Formato: users/{user}

Para usuários do Google Workspace, o valor {user} é o campo user.id da API Directory.
createTime

string (Timestamp format)

Apenas saída. O horário em que a assinatura foi criada.
updateTime

string (Timestamp format)

Apenas saída. A última vez que a assinatura foi atualizada.
reconciling

boolean

Apenas saída. Se true, a assinatura está sendo atualizada.
etag

string

Opcional. Essa checksum é calculada pelo servidor com base no valor de outros campos e pode ser enviada em solicitações de atualização para garantir que o cliente tenha um valor atualizado antes de continuar.

Campo de união expiration. A hora em que a assinatura expira.

O tempo máximo de expiração depende se a assinatura inclui dados de recursos nos payloads de eventos (especificados no campo PayloadOptions):

  • Se os payloads omitirem dados de recursos, até 7 dias.
  • Se os payloads incluem dados de recursos, até 4 horas. Se a sua organização do Google Workspace conceder acesso ao recurso por meio da delegação em todo o domínio, você poderá estender o tempo de expiração da assinatura em até 24 horas.

Depois que uma assinatura expira, ela é excluída automaticamente. Você vai receber eventos de ciclo de vida para o notification_endpoint 12 horas e uma hora antes do vencimento da assinatura. Para mais detalhes, consulte Receber e responder a eventos de ciclo de vida.

Para evitar que uma assinatura expire, use o método UpdateSubscription para estender a data de validade. Para mais detalhes, consulte Atualizar ou renovar uma assinatura. expiration pode ser apenas de um dos tipos a seguir:
expireTime

string (Timestamp format)

Padrão não vazio. É o carimbo de data/hora em UTC de quando a assinatura expira. Sempre exibido na saída, independentemente do que foi usado na entrada.
ttl

string (Duration format)

Somente entrada. O time to live (TTL) ou a duração da assinatura. Se não for especificado ou definido como 0, vai usar a duração máxima possível.

PayloadOptions

Opções sobre quais dados incluir no payload do evento. Somente para eventos do Google Chat.

Representação JSON 
{
  "includeResource": boolean,
  "fieldMask": string
}
Campos
includeResource

boolean

Opcional. Informa se o payload do evento inclui dados sobre o recurso que foi alterado. Por exemplo, em um evento em que uma mensagem do Google Chat foi criada, se o payload contém dados sobre o recurso Message. Se for "false", o payload do evento vai incluir apenas o nome do recurso alterado.
fieldMask

string (FieldMask format)

Opcional. Se includeResource for definido como true, a lista de campos a serem incluídos no payload do evento. Separe os campos com uma vírgula. Por exemplo, para incluir o remetente e a hora de criação de uma mensagem do Google Chat, digite message.sender,message.createTime. Se omitido, o payload inclui todos os campos do recurso.

Se você especificar um campo que não existe para o recurso, o sistema vai ignorá-lo.

NotificationEndpoint

O endpoint em que a assinatura entrega eventos.

Representação JSON 
{

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

Campo de união endpoint.

endpoint pode ser apenas de um dos tipos a seguir:
pubsubTopic

string

Imutável. O tópico do Cloud Pub/Sub que recebe eventos para a assinatura.

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

Você precisa criar o tópico no mesmo projeto do Google Cloud em que criou a assinatura.

Quando o tópico recebe eventos, eles são codificados como mensagens do Cloud Pub/Sub. Para mais detalhes, consulte Vinculação de protocolo do Google Cloud Pub/Sub para CloudEvents.

Estado

Estados possíveis para a assinatura.

Enums
STATE_UNSPECIFIED Valor padrão. Esse valor não é usado.
ACTIVE A assinatura está ativa e pode receber e enviar eventos para o endpoint de notificação.
SUSPENDED A assinatura não pode receber eventos devido a um erro. Para identificar o erro, consulte o campo suspensionReason.
DELETED A assinatura é excluída.

ErrorType

Possíveis erros de uma assinatura.

Enums
ERROR_TYPE_UNSPECIFIED Valor padrão. Esse valor não é usado.
USER_SCOPE_REVOKED O usuário autorizado revogou a concessão de um ou mais escopos do OAuth. Para saber mais sobre a autorização para o Google Workspace, consulte Configurar a tela de consentimento OAuth.
RESOURCE_DELETED O recurso de destino da assinatura não existe mais.
USER_AUTHORIZATION_FAILURE O usuário que autorizou a criação da assinatura não tem mais acesso ao recurso de destino dela.
ENDPOINT_PERMISSION_DENIED O aplicativo Google Workspace não tem acesso para entregar eventos ao endpoint de notificação da sua assinatura.
ENDPOINT_NOT_FOUND O endpoint de notificação da assinatura não existe ou não pode ser encontrado no projeto do Google Cloud em que você criou a assinatura.
ENDPOINT_RESOURCE_EXHAUSTED O endpoint de notificação da assinatura não recebeu eventos devido à cota insuficiente ou ao limite de taxa.
OTHER Ocorreu um erro não identificado.

Métodos

create

 Cria uma assinatura do Google Workspace.

delete

 Exclui uma assinatura do Google Workspace.

get

 Consegue detalhes sobre uma assinatura do Google Workspace.

list

 Lista as assinaturas do Google Workspace.

patch

 Atualiza ou renova uma assinatura do Google Workspace.

reactivate

 Reativar uma assinatura suspensa do Google Workspace.