REST Resource: subscriptions

Recurso: Subscription

Uma assinatura para receber eventos sobre um recurso do Google Workspace. Para saber mais sobre 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 que é monitorado quanto a eventos, formatado como o nome completo do recurso. Saiba mais sobre os recursos de destino e os eventos compatíveis em Eventos do Google Workspace compatíveis.

Um usuário só pode autorizar o 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. Imutável. Lista não ordenada. Entrada para criar uma assinatura. Caso contrário, apenas a saída. Um ou mais tipos de eventos a receber sobre o recurso de destino. Formatado de acordo com a especificação do CloudEvents.

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

Por padrão, você também recebe eventos sobre o ciclo de vida da sua assinatura. Não é preciso especificar eventos de ciclo de vida para este 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. Mostra a última vez que a assinatura foi atualizada.
reconciling

boolean

Apenas saída. Se for true, 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 de sua assinatura incluir dados de recursos em payloads de eventos (especificados no campo PayloadOptions):

  • Se os payloads omitirem os dados dos recursos, até sete dias.
  • se os payloads incluírem dados de recursos, até quatro horas. Se sua organização do Google Workspace conceder acesso ao recurso por meio da 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ê recebe eventos de ciclo de vida para a 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. Saiba mais 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)

Apenas entrada. A vida útil (TTL) ou a duração da assinatura. Se não for especificada ou definida como 0, será usada 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. Indica 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. Use vírgulas para separar os campos. Por exemplo, para incluir o remetente de uma mensagem do Google Chat e criar o horário, 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, ele será ignorado pelo sistema.

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}

É necessário criar o tópico no mesmo projeto do Google Cloud em que você criou essa assinatura.

Quando o tópico recebe eventos, eles são codificados como mensagens do Cloud Pub/Sub. Para ver 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 ao 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 de uma assinatura.

Enums
ERROR_TYPE_UNSPECIFIED Valor padrão. Esse valor não é usado.
USER_SCOPE_REVOKED O usuário que autoriza revogou a concessão de um ou mais escopos do OAuth. Para saber mais sobre a autorização no Google Workspace, consulte Configurar a tela de permissão OAuth.
RESOURCE_DELETED O recurso de destino para a 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 app Google Workspace não tem acesso para enviar 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 ao limite de taxa atingido.
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.