REST Resource: subscriptions

Recurso: Suscripción

Es una suscripción para recibir eventos sobre un recurso de Google Workspace. Para obtener más información sobre las suscripciones, consulta la descripción general de la API de Google Workspace Events.

Representación 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. Es el nombre del recurso de la suscripción.

Formato: subscriptions/{subscription}
uid

string

Solo salida. Es el identificador único asignado por el sistema para la suscripción.
targetResource

string

Obligatorio. Inmutable. Es el recurso de Google Workspace que se supervisa para detectar eventos, con el formato de nombre de recurso completo. Para obtener información sobre los recursos de destino y los eventos que admiten, consulta Eventos admitidos de Google Workspace.

Un usuario solo puede autorizar tu app para crear una suscripción para un recurso objetivo determinado. Si tu app intenta crear otra suscripción con las mismas credenciales de usuario, la solicitud devolverá un error ALREADY_EXISTS.
eventTypes[]

string

Obligatorio. Lista sin ordenar. Es la entrada para crear una suscripción. De lo contrario, solo salida. Uno o más tipos de eventos que se recibirán sobre el recurso objetivo. Se formatea según la especificación de CloudEvents.

Los tipos de eventos admitidos dependen del recurso de destino de tu suscripción. Para obtener más información, consulta Eventos de Google Workspace compatibles.

De forma predeterminada, también recibes eventos sobre el ciclo de vida de tu suscripción. No es necesario que especifiques eventos del ciclo de vida para este campo.

Si especificas un tipo de evento que no existe para el recurso de destino, la solicitud devolverá un código de estado HTTP 400 Bad Request.
payloadOptions

object (PayloadOptions)

Opcional. Son opciones sobre qué datos incluir en la carga útil del evento. Solo se admite para eventos de Google Chat.
notificationEndpoint

object (NotificationEndpoint)

Obligatorio. Inmutable. Es el extremo en el que la suscripción entrega eventos, como un tema de Pub/Sub.
state

enum (State)

Solo salida. Es el estado de la suscripción. Determina si la suscripción puede recibir eventos y entregarlos al extremo de notificación.
suspensionReason

enum (ErrorType)

Solo salida. Es el error que suspendió la suscripción.

Para reactivar la suscripción, resuelve el error y llama al método subscriptions.reactivate.
authority

string

Solo salida. Es el usuario que autorizó la creación de la suscripción.

Formato: users/{user}

Para los usuarios de Google Workspace, el valor de {user} es el campo user.id de la API de Directory.
createTime

string (Timestamp format)

Solo salida. Fecha y hora en que se creó la suscripción.
updateTime

string (Timestamp format)

Solo salida. Es la última vez que se actualizó la suscripción.
reconciling

boolean

Solo salida. Si es true, la suscripción se está actualizando.
etag

string

Opcional. El servidor calcula esta suma de comprobación según el valor de otros campos y es posible que se envíe en las solicitudes de actualización para garantizar que el cliente tenga un valor actualizado antes de continuar.

Campo de unión expiration. Es la fecha y hora en que vence la suscripción.

El tiempo máximo de vencimiento depende de si tu suscripción incluye datos de recursos en las cargas útiles de eventos (especificados en el campo PayloadOptions):

  • Si las cargas útiles omiten datos de recursos, hasta 7 días.
  • Si las cargas útiles incluyen datos de recursos, hasta 4 horas. Si tu organización de Google Workspace otorga acceso al recurso a través de la delegación en todo el dominio, puedes extender el tiempo de vencimiento de la suscripción hasta 24 horas.

Una vez que vence una suscripción, se borra automáticamente. Recibirás eventos de ciclo de vida en notification_endpoint 12 horas y una hora antes de que venza la suscripción. Para obtener más detalles, consulta Cómo recibir y responder a eventos de ciclo de vida.

Para evitar que una suscripción venza, puedes usar el método UpdateSubscription para extender su fecha de vencimiento. Para obtener más información, consulta Cómo actualizar o renovar una suscripción. expiration puede ser solo uno de los siguientes:
expireTime

string (Timestamp format)

Valor predeterminado no vacío. Es la marca de tiempo en UTC que indica cuándo vence la suscripción. Siempre se muestra en la salida, sin importar lo que se haya usado en la entrada.
ttl

string (Duration format)

Solo entrada. Es el tiempo de actividad (TTL) o la duración de la suscripción. Si no se especifica o se establece en 0, se usa la duración máxima posible.

PayloadOptions

Son opciones sobre qué datos incluir en la carga útil del evento. Solo se admite para eventos de Google Chat.

Representación JSON 
{
  "includeResource": boolean,
  "fieldMask": string
}
Campos
includeResource

boolean

Opcional. Indica si la carga útil del evento incluye datos sobre el recurso que cambió. Por ejemplo, para un evento en el que se creó un mensaje de Google Chat, indica si la carga útil contiene datos sobre el recurso Message. Si es falso, la carga útil del evento solo incluye el nombre del recurso modificado.
fieldMask

string (FieldMask format)

Opcional. Si includeResource se establece en true, es la lista de campos que se incluirán en la carga útil del evento. Separa los campos con una coma. Por ejemplo, para incluir el remitente y la hora de creación de un mensaje de Google Chat, ingresa message.sender,message.createTime. Si se omite, la carga útil incluye todos los campos del recurso.

Si especificas un campo que no existe para el recurso, el sistema lo ignorará.

NotificationEndpoint

Es el extremo en el que la suscripción entrega eventos.

Representación 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ón endpoint.

endpoint puede ser una de las siguientes opciones:
pubsubTopic

string

Inmutable. Es el tema de Pub/Sub que recibe eventos para la suscripción.

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

Debes crear el tema en el mismo proyecto de Google Cloud en el que creas esta suscripción.

Nota: La API de Workspace Events usa claves de ordenamiento para el beneficio de los eventos secuenciales. Si el tema de Cloud Pub/Sub tiene una política de almacenamiento de mensajes configurada para excluir la región de Google Cloud más cercana, fallará la publicación de eventos con claves de ordenamiento.

Cuando el tema recibe eventos, estos se codifican como mensajes de Pub/Sub. Para obtener más detalles, consulta la vinculación del protocolo de Google Cloud Pub/Sub para CloudEvents.

Estado

Son los estados posibles de la suscripción.

Enumeraciones
STATE_UNSPECIFIED Valor predeterminado Este valor no se usa.
ACTIVE La suscripción está activa y puede recibir y entregar eventos a su extremo de notificación.
SUSPENDED La suscripción no puede recibir eventos debido a un error. Para identificar el error, consulta el campo suspensionReason.
DELETED Se borró la suscripción.

ErrorType

Son los posibles errores de una suscripción.

Enumeraciones
ERROR_TYPE_UNSPECIFIED Valor predeterminado Este valor no se usa.
USER_SCOPE_REVOKED El usuario autorizante revocó el otorgamiento de uno o más permisos de OAuth. Para obtener más información sobre la autorización para Google Workspace, consulta Cómo configurar la pantalla de consentimiento de OAuth.
RESOURCE_DELETED El recurso de destino de la suscripción ya no existe.
USER_AUTHORIZATION_FAILURE El usuario que autorizó la creación de la suscripción ya no tiene acceso al recurso de destino de la suscripción.
ENDPOINT_PERMISSION_DENIED La aplicación de Google Workspace no tiene acceso para entregar eventos al extremo de notificación de tu suscripción.
ENDPOINT_NOT_FOUND No existe el extremo de notificación de la suscripción, o bien no se puede encontrar en el proyecto de Google Cloud en el que creaste la suscripción.
ENDPOINT_RESOURCE_EXHAUSTED El extremo de notificación de la suscripción no recibió eventos debido a que la cuota es insuficiente o se alcanzó el límite de frecuencia.
OTHER Se produjo un error no identificado.

Métodos

create

 Crea una suscripción a Google Workspace.

delete

 Borra una suscripción a Google Workspace.

get

 Obtiene detalles sobre una suscripción a Google Workspace.

list

 Enumera las suscripciones a Google Workspace.

patch

 Actualiza o renueva una suscripción a Google Workspace.

reactivate

 Reactiva una suscripción suspendida a Google Workspace.