REST Resource: subscriptions

Recurso: Suscripción

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 en busca de 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 de Google Workspace compatibles.

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

string

Obligatorio. Lista sin ordenar. Entrada para crear una suscripción. De lo contrario, solo se muestra la salida. Uno o más tipos de eventos que se recibirán sobre el recurso de destino. Tiene el formato 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 especificar eventos de ciclo de vida para este campo.

Si especificas un tipo de evento que no existe para el recurso de destino, la solicitud muestra 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 es compatible con los 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 enviarlos al extremo de notificaciones.
suspensionReason

enum (ErrorType)

Solo salida. 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. 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. Es la hora en la que se crea la suscripción.
updateTime

string (Timestamp format)

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

boolean

Solo salida. Si es true, la suscripción está en proceso de actualización.
etag

string

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

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

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

  • Si las cargas útiles omiten los 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 mediante la delegación en todo el dominio, puedes extender el tiempo de vencimiento de la suscripción hasta por 24 horas.

Cuando 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 información, consulta Cómo recibir y responder eventos de ciclo de vida.

Para evitar que venza una suscripción, 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. La marca de tiempo en UTC cuando vence la suscripción. Siempre se muestra en la salida, independientemente de lo que se haya usado en la entrada.
ttl

string (Duration format)

Solo entrada. 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, 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 de un mensaje de Google Chat y crear la hora, 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 ignora.

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 Cloud 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.

Cuando el tema recibe eventos, estos se codifican como mensajes de Cloud Pub/Sub. Para obtener más información, consulta la Vinculación de protocolos 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 borrará 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 autorizado revocó el otorgamiento de uno o más permisos de OAuth. Si quieres obtener más información sobre la autorización para Google Workspace, consulta Configura 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 El extremo de notificación de la suscripción no existe o 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 pudo recibir 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

 Obtén detalles sobre una suscripción a Google Workspace.

list

 Se muestran las suscripciones a Google Workspace.

patch

 Actualiza o renueva una suscripción a Google Workspace.

reactivate

 Reanuda una suscripción suspendida a Google Workspace.