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

Opcional. Inmutable. Identificador. Nombre del recurso de la suscripción.

Formato: subscriptions/{subscription}
uid

string

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

string

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

Un usuario solo puede autorizar que tu app 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. Inmutable. Lista sin ordenar. Entrada para crear una suscripción. De lo contrario, solo muestra el resultado. Uno o más tipos de eventos para recibir acerca del recurso objetivo. Formato conforme a la especificación de CloudEvents.

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

De forma predeterminada, también recibes eventos acerca del ciclo de vida de tu suscripción. No es necesario que especifiques 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. 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. El extremo en el que la suscripción entrega eventos, como un tema de Pub/Sub.
state

enum (State)

Solo salida. 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. 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 {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. La hora de vencimiento de la suscripción.

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

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

Cuando vence una suscripción, se borra automáticamente. Recibes 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 Recibe y responde eventos de ciclo de vida.

Para evitar que venza una suscripción, puedes extender la fecha de vencimiento con el método UpdateSubscription. 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 que no está vacío. La marca de tiempo en UTC cuando 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. El tiempo de actividad (TTL) o la duración de la suscripción. Si no se especifica o se configura como 0, usa la duración máxima posible.

PayloadOptions

Opciones sobre qué datos incluir en la carga útil del evento. Solo es compatible con los 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 como true, 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 la hora de creación, 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

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. 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. Si deseas obtener más información, consulta Vinculación de protocolo de Google Cloud Pub/Sub para CloudEvents.

Estado

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

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 para 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 a que 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

 Se muestran las suscripciones a Google Workspace.

patch

 Actualiza o renueva una suscripción a Google Workspace.

reactivate

 Reactiva una suscripción suspendida a Google Workspace.