Administra contactos con el protocolo CardDAV

Puedes ver y administrar tus contactos mediante el protocolo CardDAV de Google.

Los contactos se almacenan en la Cuenta de Google del usuario. La mayoría de los servicios de Google tienen acceso a la lista de contactos. Tu aplicación cliente puede usar la API de CardDAV para crear contactos nuevos, editar o borrar contactos existentes, y consultar contactos que coincidan con criterios específicos.

Especificaciones

No se implementó la especificación completa, pero muchos clientes, como los Contactos de Apple iOSTM y macOS, deberían interoperar correctamente.

Para cada especificación relevante, la compatibilidad de CardDAV de Google es la siguiente:

CardDAV de Google requiere OAuth 2.0

La interfaz CardDAV de Google requiere OAuth 2.0. Consulta la documentación vinculada a continuación para obtener información sobre el uso de OAuth 2.0 para acceder a las APIs de Google:

Estableciendo conexión con el servidor CardDAV de Google

El protocolo CardDAV permite descubrir los URI de la libreta de direcciones y los recursos de contacto. No debes codificar ningún URI, ya que podría cambiar en cualquier momento.

Las aplicaciones cliente deben usar HTTPS, y se debe proporcionar autenticación OAuth 2.0 para la Cuenta de Google del usuario. El servidor CardDAV no autenticará una solicitud, a menos que llegue a través de HTTPS con autenticación OAuth 2.0 de una Cuenta de Google y tu aplicación esté registrada en DevConsole. Cualquier intento de conectarse a través de HTTP con la autenticación básica o con un correo electrónico o contraseña que no coincide con una Cuenta de Google genera un código de respuesta HTTP 401 Unauthorized.

Para usar CardDAV, tu programa cliente debe conectarse inicialmente a la ruta de descubrimiento canónica mediante una PROPFIND HTTP en lo siguiente:

https://www.googleapis.com/.well-known/carddav

Una vez que se redirecciona (HTTP 301) a un recurso de libreta de direcciones, el programa cliente puede realizar una PROPFIND en él para descubrir las propiedades DAV:current-user-principal, DAV:principal-URL y addressbook-home-set. El programa cliente puede descubrir la libreta de direcciones principal si realiza una PROPFIND en addressbook-home-set y busca los recursos addressbook y collection. Una descripción completa de este proceso está fuera del alcance de este documento. Consulta rfc6352 para obtener más información.

La ruta de redireccionamiento que se muestra en la respuesta HTTP 301 a través de un PROPFIND en el URI conocido no se debe almacenar en caché de forma permanente (de acuerdo con rfc6764). Los dispositivos deben reintentar la detección de URI conocida de forma periódica para verificar si la ruta almacenada en caché todavía está actualizada y volver a sincronizarse si la ruta cambia. Google recomienda una tasa de cambio cada 2 o 4 semanas.

Recursos

CardDAV usa conceptos de REST. Las aplicaciones cliente actúan en los recursos designados por sus URIs. La estructura actual del URI se especifica aquí para ayudar a los desarrolladores a comprender los conceptos de la siguiente sección. La estructura puede cambiar y no debe estar codificada. En su lugar, los recursos deben descubrirse de acuerdo con el RFC.

  1. Principal
    • https://www.googleapis.com/carddav/v1/principals/userEmail
  2. Conjunto de casas
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists
  3. Libreta de direcciones
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
  4. Contacto
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

Sincronización de contactos

La siguiente es una descripción general de las operaciones admitidas. Los desarrolladores deben buscar los detalles en el RFC relevante. La mayoría de las solicitudes y respuestas están codificadas en XML. Estas son las operaciones principales que usan las aplicaciones cliente para la sincronización:

  • Uso de CTag
    • Los programas cliente usan la solicitud getctag PROPFIND en el recurso de la libreta de direcciones para determinar si algún contacto cambió en el servidor y, por lo tanto, si se necesita una sincronización. Se garantiza que el valor de esta propiedad cambiará si cambia algún contacto. Las aplicaciones cliente deben almacenar este valor y usarlo solo en la sincronización inicial y como resguardo cuando se invalida un sync-token. Sondear periódicamente la propiedad getctag dará como resultado una limitación.
  • Con el token de sincronización
    • Los programas cliente usan la solicitud PROPFIND sync-token en la libreta de direcciones para obtener el sync-token que representa su estado actual. Las aplicaciones cliente deben almacenar este valor y emitir solicitudes sync-collection REPORT periódicas para determinar los cambios desde la última sync-token emitida. Los tokens emitidos son válidos durante 29 días y la respuesta REPORT contendrá un sync-token nuevo.
  • Usa ETags
    • Las aplicaciones cliente emiten una solicitud PROPFIND de getetag en el recurso de la libreta de direcciones (con el encabezado DEPTH igual a DEPTH_1). Si se mantiene el valor de ETag de cada contacto, un programa cliente puede solicitar el valor de los contactos en los que se cambió su ETag.
  • Cómo recuperar contactos
    • Las aplicaciones cliente recuperan contactos mediante una solicitud addressbook-multiget REPORT. En una lista de URI de contactos, el informe muestra todos los contactos solicitados como valores de VCard 3.0. Cada entrada incluye un ETag para el contacto.
  • Insertar un contacto
    • Las aplicaciones cliente emiten una solicitud POST con el nuevo contacto en formato VCard 3.0. La respuesta contendrá el ID del nuevo contacto.
  • Actualiza un contacto
    • Las aplicaciones cliente emiten una solicitud PUT con el contacto actualizado en formato VCard 3.0. El contacto se actualiza si ya existe en la libreta de direcciones.
    • Las aplicaciones cliente deben incluir un encabezado If-Match con el ETag conocido actualmente del contacto. Luego, el servidor rechazará la solicitud PUT (con HTTP 412) si el ETag actual en el servidor es diferente del ETag enviado por el programa cliente. Esto permite una serialización optimista de las actualizaciones.
  • Borrar un contacto
    • Las aplicaciones cliente borran un contacto mediante la emisión de una solicitud DELETE contra el URI del contacto.