REST Resource: subscriptions

Recurso: Subscription

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 Eventos de Google Workspace.

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 el 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 objetivo y los eventos que admiten, consulta Eventos de Google Workspace admitidos.

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

string

Obligatorio. Inmutable. Lista sin ordenar. Entrada para crear una suscripción. De lo contrario, solo el resultado. Uno o más tipos de eventos para recibir sobre el recurso objetivo. Tienen 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 los eventos de Google Workspace admitidos.

De forma predeterminada, también recibes eventos sobre el 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 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. 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. 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 que se creó 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 verificación según el valor de otros campos, y se puede enviar 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 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 (especificado en el campo PayloadOptions):

  • Si las cargas útiles omiten los datos de recursos, puede tardar 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 de todo el dominio, puedes extender el tiempo de vencimiento de la suscripción hasta por 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 Recibe y responde eventos del 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. Es la marca de tiempo en UTC de cuándo vence la suscripción. Siempre se muestra en el resultado, sin importar lo que se usó 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

Opciones sobre qué datos incluir en la carga útil del evento. Solo es compatible con 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 configura 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 al 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 ignorará.

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 los eventos de la suscripción

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

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

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

Estado

Estados posibles para la suscripción.

Enumeradores
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 para una suscripción.

Enumeradores
ERROR_TYPE_UNSPECIFIED Valor predeterminado Este valor no se usa.
USER_SCOPE_REVOKED El usuario que autoriza revocó el otorgamiento de uno o más permisos de OAuth. Para obtener más información sobre la autorización de 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 alcanzó el límite de frecuencia.
OTHER Se produjo un error desconocido.

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

 Muestra una lista de las suscripciones a Google Workspace.

patch

 Actualiza o renueva una suscripción a Google Workspace.

reactivate

 Reactiva una suscripción suspendida a Google Workspace.