Gestionando Contactos Google: La API de People

Si trabajas con datos de contactos en tus aplicaciones y dependes de los servicios de Google, es fundamental estar al día con los cambios en sus APIs. La forma en que interactuábamos programáticamente con Google Contacts ha evolucionado, marcando el fin de una era y el comienzo de otra con una herramienta más moderna y potente. Prepárate para descubrir cómo gestionar tus contactos de Google de forma programática en la actualidad.

Durante años, la API de Google Contacts fue la herramienta estándar para desarrolladores que necesitaban acceder y gestionar los contactos de los usuarios de Google. Sin embargo, como parte de la evolución de los servicios de Google, esta API fue oficialmente desactivada el 19 de enero de 2022. Esto significa que cualquier aplicación que aún dependiera de esta API para sus funcionalidades de contactos dejó de funcionar correctamente a partir de esa fecha. La razón detrás de esta transición es la consolidación y mejora de las APIs de Google, migrando funcionalidades a plataformas más nuevas y versátiles que ofrecen una mejor experiencia y capacidades extendidas para los desarrolladores.

Adiós a la API de Contacts, Hola a la API de People

El sucesor directo y recomendado de la API de Google Contacts es la API de People (API de Personas). Esta API está diseñada para proporcionar una vista consolidada de la información de las personas, obtenida de diversas fuentes como los contactos personales del usuario autenticado, perfiles de Google, perfiles y contactos de dominio de Google Workspace, entre otros. La API de People no solo cubre las funcionalidades básicas de gestión de contactos que ofrecía la API de Contacts, sino que también introduce nuevas capacidades y un enfoque más amplio sobre la información de las personas.

La API de People permite a los desarrolladores realizar diversas acciones, incluyendo:

• Leer y gestionar los contactos del usuario autenticado.
• Leer y copiar los "Otros contactos" del usuario autenticado.
• Leer información de perfil para usuarios autenticados y sus contactos.
• Leer perfiles y contactos de dominio (para usuarios de Google Workspace).

Por ejemplo, si tu aplicación necesita acceder a la lista de contactos de un usuario, puede llamar a métodos como people.connections.list. Si el usuario otorga su consentimiento, la aplicación recibirá una lista de recursos de persona que representan sus contactos. Para obtener información detallada sobre una persona específica, se puede usar el método people.get.

Cambios Clave y Migración

La migración de la antigua API de Contacts a la API de People implica cambios importantes que los desarrolladores deben entender. Uno de los cambios más significativos se refiere al manejo de los 'Otros contactos' (Other Contacts) y los ámbitos de autorización (scopes). La antigua API utilizaba un ámbito general (https://www.google.com/m8/feeds) que daba acceso tanto a contactos personales como a información de directorio. La API de People reemplaza este ámbito con dos ámbitos más específicos para un control más granular:

• Para acceder a contactos personales: https://www.googleapis.com/auth/contacts
• Para acceder a información de directorio: https://www.googleapis.com/auth/directory.readonly

Es importante destacar que el ámbito antiguo (https://www.google.com/m8/feeds) funciona ahora como un alias para el nuevo ámbito https://www.googleapis.com/auth/contacts. Esto significa que las concesiones de OAuth existentes con el ámbito antiguo seguirán funcionando para cualquier punto final en la API de People que requiera el ámbito https://www.googleapis.com/auth/contacts. Por lo tanto, las operaciones de lectura y escritura de contactos y grupos de contactos personales deberían seguir funcionando con el ámbito antiguo si ya lo tenías configurado.

Sin embargo, para acceder a los "Otros contactos" o a los datos del directorio, la API de People requiere los nuevos ámbitos específicos mencionados anteriormente. Debes asegurarte de que tu aplicación solicita y gestiona estos nuevos ámbitos si necesitas acceder a estas categorías de información.

Funcionalidades Detalladas de la API de People

La API de People ofrece una amplia gama de funcionalidades para interactuar con los datos de las personas. Estas funcionalidades se dividen principalmente en operaciones de lectura (Read) y mutación (Mutate), aplicándose a contactos personales, 'Otros contactos', fotos de contactos y grupos de contactos.

Gestión de Contactos Personales

Para leer y modificar los contactos personales del usuario autenticado, se requiere generalmente el ámbito https://www.googleapis.com/auth/contacts (para lectura y escritura) o https://www.googleapis.com/auth/contacts.readonly (solo para lectura).

• Leer un contacto específico: Utiliza el método people.get, proporcionando el nombre del recurso del contacto.
• Leer varios contactos específicos: Utiliza el método people.getBatchGet para recuperar un conjunto de contactos por sus nombres de recurso.
• Leer contactos usando conexiones: El método people.connections.list permite listar los contactos a los que el usuario autenticado está conectado.
• Crear un nuevo contacto: Utiliza el método people.createContact para añadir un nuevo contacto a la lista personal del usuario.
• Actualizar un contacto existente: El método people.updateContact permite modificar los campos de un contacto que previamente has leído de la lista de conexiones.
• Eliminar un contacto: Utiliza el método people.deleteContact para eliminar un contacto de la lista personal del usuario.

Gestión de Fotos de Contactos

La gestión de fotos de contactos también es posible a través de la API de People, requiriendo el ámbito https://www.googleapis.com/auth/contacts.

• Actualizar la foto de un contacto: Utiliza el método people.updateContactPhoto.
• Eliminar la foto de un contacto: Utiliza el método people.deleteContactPhoto.

Manejo de 'Otros Contactos'

El tratamiento de los 'Otros contactos' es una de las áreas con diferencias significativas en la API de People. Estos contactos son, por diseño, de solo lectura a través de la API, con algunas limitaciones importantes:

• Solo se pueden leer los 'Otros contactos', no se pueden modificar directamente a través de la API. Si se necesitan modificar, el usuario debe primero añadirlos como un contacto personal.
• Solo se devuelve información básica para 'Otros contactos', específicamente nombres, direcciones de correo electrónico y números de teléfono. Otros campos detallados no están disponibles a través de la API para esta categoría.
• Para leer 'Otros contactos', se requiere un ámbito específico y nuevo: https://www.googleapis.com/auth/contacts.other.readonly.
• El punto final para leer 'Otros contactos' es otherContacts.list.
• Aunque no se pueden modificar directamente, es posible copiar un 'Otro contacto' a la lista de contactos personales del usuario utilizando el método otherContacts.copyOtherContactToMyContactsGroup. Esta operación requiere tanto el ámbito de lectura de 'Otros contactos' como el ámbito de escritura de contactos personales (https://www.googleapis.com/auth/contacts.other.readonly y https://www.googleapis.com/auth/contacts).

Los administradores de Google Workspace tienen permisos de solo lectura para "Otros contactos" a través del nuevo ámbito. La API no admite el envío de señales de mutación/escritura de vuelta a "Otros contactos".

Trabajando con Grupos de Contactos

La gestión de grupos de contactos también se ha integrado en la API de People, reemplazando la forma en que se manejaban en la API antigua. Los puntos finales para grupos de contactos requieren el ámbito https://www.googleapis.com/auth/contacts (para mutación) o https://www.googleapis.com/auth/contacts.readonly (para lectura).

• Obtener un grupo de contactos específico: Utiliza people.contactGroups.get.
• Listar grupos de contactos: El método people.contactGroups.list permite recuperar la lista de grupos de contactos del usuario.
• Crear un grupo de contactos: Utiliza people.contactGroups.create para añadir un nuevo grupo.
• Actualizar un grupo de contactos: El método people.contactGroups.update permite modificar un grupo existente.
• Eliminar un grupo de contactos: Utiliza people.contactGroups.delete para eliminar un grupo.
• Añadir o eliminar miembros de un grupo: El método people.contactGroups.members.modify permite modificar la lista de miembros de un grupo. Nota: También puedes modificar la pertenencia a grupos actualizando el campo memberships de un contacto individual usando people.updateContact.

Aquí tienes una tabla que muestra cómo se mapean algunos campos de grupos de contactos de la antigua API a la nueva API de People:

Acceso a Información de Directorio (Google Workspace)

Para los usuarios de Google Workspace, la API de People permite acceder a la Lista Global de Direcciones (Global Address List), que incluye perfiles de dominio y contactos. El acceso a esta información requiere el ámbito https://www.googleapis.com/auth/directory.readonly.

• Listar todos los contactos y perfiles de directorio: Utiliza people.listDirectoryPeople.
• Buscar contactos y perfiles de directorio: El método people.searchDirectoryPeople permite buscar dentro del directorio.

Es importante notar que, al igual que con los 'Otros contactos', los perfiles y contactos de dominio de directorio son de solo lectura a través de la API de People; las mutaciones (creación, actualización, eliminación) no son compatibles para este tipo de datos.

Entendiendo los Datos de Persona Fusionados

Una característica clave de la API de People es su capacidad para presentar una vista unificada de la información de una persona, fusionando datos de múltiples fuentes. La información de una persona puede provenir de perfiles públicos de Google, datos de perfiles de dominio de Google Workspace (si el administrador del dominio ha habilitado el uso compartido externo y se ha otorgado el ámbito directory.readonly), información de perfil privado del usuario autenticado (si se han otorgado los ámbitos de perfil correspondientes) y, por supuesto, los contactos personales del usuario (si se ha otorgado el ámbito de contactos).

La fusión ocurre si las fuentes están conectadas a través de direcciones de correo electrónico verificadas, números de teléfono o URLs de perfil. La API intenta consolidar esta información para ofrecer una representación lo más completa posible de una persona. Sin embargo, es crucial entender que solo los datos basados en contactos personales (aquellos gestionados directamente por el usuario en Google Contacts) pueden ser modificados a través de los puntos finales de mutación de la API. Los datos provenientes de perfiles o contactos de dominio son de solo lectura.

Cómo Habilitar y Acceder a la API de People

Para empezar a usar la API de People en tu proyecto, primero necesitas habilitarla en la Google Cloud Console y obtener las credenciales adecuadas (como una clave de API o configurar OAuth 2.0, dependiendo de tus necesidades). El proceso general para habilitar una API en Google Cloud implica:

1. Navegar a la sección 'API y servicios' y luego a 'Biblioteca' en la Google Cloud Console de tu proyecto.
2. Buscar la 'Google People API' en la biblioteca.
3. Seleccionar la API y hacer clic en el botón 'Habilitar'.

Es posible que necesites permisos específicos en el proyecto de Google Cloud para poder habilitar APIs. Si no tienes acceso directo, deberás coordinar con un administrador de seguridad para que te otorgue los permisos necesarios o habilite la API por ti. Una vez habilitada, podrás configurar las credenciales (como ID de cliente OAuth) necesarias para autenticar tus llamadas a la API. Consulta la documentación de Google Cloud sobre cómo autorizar solicitudes para obtener más detalles.

También puedes usar la herramienta de línea de comandos gcloud para habilitar servicios. Por ejemplo:

• Listar tus proyectos: gcloud projects list
• Establecer el proyecto por defecto: gcloud config set project YOUR_PROJECT_ID
• Listar servicios disponibles: gcloud services list --available
• Habilitar la API de People (el nombre del servicio sería algo como people.googleapis.com): gcloud services enable people.googleapis.com

Asegúrate de tener el SDK de Google Cloud instalado y configurado para usar los comandos gcloud.

Preguntas Frecuentes sobre la API de People

¿La API de Google Contacts sigue funcionando?

No, la API de Google Contacts fue desactivada el 19 de enero de 2022. Cualquier aplicación que la utilizara debe migrar a la API de People para seguir funcionando correctamente.

¿La API de People puede modificar 'Otros contactos'?

No, los 'Otros contactos' son de solo lectura a través de la API de People. Solo puedes leer información básica (nombres, emails, teléfonos) o copiarlos a tus contactos personales para poder modificarlos.

¿Puedo usar el ámbito antiguo https://www.google.com/m8/feeds con la API de People?

Sí, este ámbito actúa como un alias para https://www.googleapis.com/auth/contacts y funcionará para leer y escribir contactos y grupos de contactos personales, manteniendo la compatibilidad con concesiones OAuth existentes.

¿Cómo accedo a los contactos del directorio de mi organización (Google Workspace)?

Debes usar los puntos finales people.listDirectoryPeople o people.searchDirectoryPeople con el ámbito https://www.googleapis.com/auth/directory.readonly. Es importante recordar que el acceso al directorio es de solo lectura a través de la API de People.

Conclusión

En resumen, aunque la antigua API de Google Contacts ya no está activa, Google proporciona una solución moderna y robusta en la forma de la API de People. Esta API no solo cubre las funcionalidades esenciales para gestionar los contactos personales, sino que también ofrece capacidades para acceder a 'Otros contactos' (con ciertas limitaciones) y a información de directorio para usuarios de Google Workspace. La migración a la API de People es un paso necesario para mantener tus aplicaciones funcionales y aprovechar las características más recientes que Google ofrece para la gestión programática de la información de personas. Asegúrate de entender los nuevos ámbitos y el manejo específico de 'Otros contactos' para una transición exitosa y para aprovechar al máximo las capacidades de la API de People.

Si quieres conocer otros artículos parecidos a Gestionando Contactos Google: La API de People puedes visitar la categoría Bases de datos.