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

Opcional. Imutável. 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 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 compatíveis do Google Workspace.

Um usuário só pode autorizar o app a criar uma assinatura para 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. Imutável. Lista não ordenada. Entrada para criar uma assinatura. Caso contrário, somente saída. Um ou mais tipos de eventos a serem recebidos 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. Veja mais detalhes em Eventos compatíveis do Google Workspace.

Por padrão, você também recebe eventos sobre o ciclo de vida da 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 retornará um código de status HTTP 400 Bad Request.
payloadOptions

object (PayloadOptions)

Opcional. Opções sobre quais dados incluir no payload do evento. Compatível apenas com 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 entregá-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. A hora em que a assinatura é criada.
updateTime

string (Timestamp format)

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

boolean

Apenas saída. Se o valor for true, significa que a assinatura está em processo de atualização.
etag

string

Opcional. Essa soma de verificação é 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 prosseguir.

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

O prazo de validade máximo depende da sua assinatura incluir dados de recursos em payloads de eventos (especificados no campo PayloadOptions):

  • Se os payloads omitirem os dados de recursos, esse prazo será de até sete dias.
  • Se os payloads incluírem dados de recursos, até 4 horas. Se a organização do Google Workspace conceder acesso ao recurso usando a delegação em todo o domínio, você poderá estender o prazo de validade da assinatura para até 24 horas.

Quando 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. Veja mais detalhes em 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 especificada ou definida como 0, usa a duração máxima possível.

PayloadOptions

Opções sobre quais dados incluir no payload do evento. Compatível apenas com eventos do Google Chat.

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

boolean

Opcional. Se o payload do evento inclui dados sobre o recurso que foi alterado. Por exemplo, para um evento em que uma mensagem do Google Chat foi criada, se o payload contém dados sobre o recurso Message. Se for falso, o payload do evento 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 de uma mensagem do Google Chat e o horário de criação, 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 ignorar esse campo.

NotificationEndpoint

O endpoint em que a assinatura envia 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 entregar 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 foi excluída.

ErrorType

Possíveis erros em 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 permissão 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 da assinatura.
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 foi 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 à limitação 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

 Recebe detalhes sobre uma assinatura do Google Workspace.

list

 Lista as assinaturas do Google Workspace.

patch

 Atualiza ou renova uma assinatura do Google Workspace.

reactivate

 Reativa uma assinatura suspensa do Google Workspace.