Google Calendar Activities

Google Calendar Activities

Versión: 1.0.5  ·  ID: zoan-packages-googlecalendar  ·  Autor: Zoan Software

El paquete Google Calendar crea, actualiza, busca y responde eventos, y gestiona sus invitados, directamente por la API de Google: agendar reuniones a partir de solicitudes, reprogramar en bloque, leer la agenda del día para preparar trabajo o enviar invitaciones sin abrir el calendario.

La autenticación

Todo empieza con Google Calendar — Connect, que admite dos modos en authType:

Modo	Qué necesitas	Cuándo conviene
oauth (por defecto)	Una conexión OAuth de Google de Zoan Cloud autorizada con el permiso de Calendar (https://www.googleapis.com/auth/calendar). Se pasa en credential como credential("nombre-clave"); Zoan Cloud renueva el token solo.	El robot gestiona la agenda de una persona o de una cuenta del equipo.
service-account	Una llave de service account (JSON completo) guardada como credencial, en serviceAccount. Con impersonateUser (domain-wide delegation) opera el calendario de ese usuario del Workspace; sin él, solo los calendarios compartidos con el email de la service account.	Ejecuciones desatendidas sin consentimiento de una persona.

Coloca las demás actividades dentro del body de Connect para que hereden la sesión (ZoanGoogleCalendarSession) y esta se cierre sola al terminar.

Calendarios, fechas y avisos

• calendarId: por defecto primary, el calendario principal de la cuenta. Para otro calendario usa su ID, que obtienes con Get calendars (suele tener forma de email).
• Fechas: pasa un DateTime directamente (p. ej. DateTime.Today.AddDays(1)) o un texto ISO 8601 (2026-06-15T14:30:00). No dependen del idioma ni de la configuración regional del equipo: se envían a Google con desfase explícito. Desde la versión 1.0.5.
  • Una hora sin desfase (un DateTime normal o un texto sin Z ni -05:00) se interpreta en la zona de timeZone o, si lo omites, en la zona del calendario; nunca en la del equipo del robot.
  • Con desfase (2026-06-15T14:30:00-05:00, DateTimeOffset o DateTime en UTC) se respeta el instante exacto.
  • Un texto como 04/03/2026 se rechaza: es ambiguo (día/mes o mes/día).
• Día completo: con allDay = true se usa solo la fecha. En Google la fecha de fin de un evento de día completo es exclusiva: un evento del 15 de junio va de 2026-06-15 a 2026-06-16.
• notify: decide si Google envía correos a los invitados al crear, cambiar o cancelar. Déjalo apagado mientras pruebas para no enviar invitaciones reales.

Datos de un evento

Create event, Update event, Get events, Get event by ID, Add attendee y Respond devuelven cada evento como un Dictionary con estas claves:

Clave	Tipo	Contenido
id	string	ID del evento. En eventos recurrentes, cada ocurrencia tiene su propio ID.
summary	string	Título.
description	string	Descripción (nulo si no tiene).
location	string	Ubicación (nulo si no tiene).
start	string	Inicio: ISO 8601 con desfase (p. ej. 2026-06-15T14:30:00.0000000-05:00) o solo fecha (2026-06-15) si es de día completo.
end	string	Fin, mismo formato. En día completo, la fecha es exclusiva (el día siguiente al último).
allDay	bool	true si es de día completo.
status	string	confirmed, tentative o cancelled.
organizer	string	Email del organizador.
attendees	List	Invitados: cada uno un Dictionary con email (string), response (string: needsAction, accepted, declined o tentative) y optional (bool). Nulo si el evento no tiene invitados.
htmlLink	string	Enlace al evento en Google Calendar.
meetLink	string	Enlace de Google Meet, si el evento tiene uno; si no, nulo.

Actividades

Actividad	Tipo	Salida	Descripción
Google Calendar — Connect	googlecalendar-connect	ZoanGoogleCalendarSession	Abre una sesión autenticada con Google Calendar
Google Calendar — Create event	googlecalendar-create-event	Dictionary<string,object>	Crea un evento en un calendario
Google Calendar — Update event	googlecalendar-update-event	Dictionary<string,object>	Actualiza campos de un evento existente (solo los que indiques)
Google Calendar — Get events	googlecalendar-get-events	List<Dictionary<string,object>>	Lista o busca eventos dentro de un rango de fechas
Google Calendar — Get event by ID	googlecalendar-get-event	Dictionary<string,object>	Obtiene un evento concreto por su ID
Google Calendar — Get calendars	googlecalendar-get-calendars	List<Dictionary<string,object>>	Lista los calendarios accesibles por la cuenta
Google Calendar — Add attendee	googlecalendar-add-attendee	Dictionary<string,object>	Añade uno o varios invitados a un evento (conserva los existentes)
Google Calendar — Respond (RSVP)	googlecalendar-respond	Dictionary<string,object>	Responde a una invitación: aceptar, rechazar o provisional
Google Calendar — Delete event	googlecalendar-delete-event	—	Elimina un evento de un calendario
Google Calendar — Close	googlecalendar-close	—	Cierra una sesión de Google Calendar

Errores de la API de Google

Cuando Google rechaza una llamada, la actividad falla con un error de tipo GoogleApiException cuyo mensaje empieza por The service calendar has thrown an exception. HttpStatusCode is … seguido del texto de Google (siempre en inglés: lo envía Google):

Código	Causa habitual	Qué hacer
NotFound	El calendarId o el eventId no existen, o la cuenta no ve ese calendario.	Comprueba los IDs con Get calendars y Get events.
Gone	El evento ya fue eliminado.	Si buscabas borrarlo, el resultado ya es el esperado: captúralo y sigue.
BadRequest	Datos rechazados: fin anterior o igual al inicio (The specified time range is empty), email de invitado inválido, zona horaria desconocida.	Revisa fechas, emails y timeZone.
Forbidden	La cuenta solo puede leer ese calendario, no es organizadora del evento, la conexión no incluye el permiso de Calendar, o se superó una cuota.	Usa un calendario donde la cuenta tenga permiso de edición, o reautoriza la conexión.
Unauthorized	El token ya no es válido (acceso revocado, conexión expirada).	Reconectar la conexión en Zoan Cloud.
TooManyRequests	Se superó la cuota de solicitudes por minuto de Google.	Envuelve la actividad en Retry con espera.

Captura cualquiera de ellos con Try / Catch; error.Type vale GoogleApiException.