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:
- rfc2518: extensiones de HTTP para creación distribuida (WebDAV)
- Admite los métodos HTTP
GET
,PUT
,DELETE
,OPTIONS
yPROPFIND
. - No es compatible con los métodos HTTP
LOCK
,UNLOCK
,COPY
,MOVE
niMKCOL
. - No admite propiedades arbitrarias (definidas por el usuario) de WebDAV.
- No es compatible con el control de acceso WebDAV (rfc3744).
- Admite los métodos HTTP
- rfc5995: uso de POST para agregar miembros a las colecciones de WebDAV
- Admite la creación de nuevos contactos sin especificar un ID.
- rfc6352: CardDAV: Extensiones de vCard en la creación y el control de versiones distribuidos en la Web (WebDAV)
- Admite el método HTTP
REPORT
, pero no se implementan todos los informes definidos. - Admite proporcionar una colección principal y una colección de contactos.
- Admite el método HTTP
- rfc6578: Sincronización de colecciones para WebDAV
- Las aplicaciones cliente deben cambiar a este modo de operación después de la sincronización inicial.
- rfc6749: el marco de trabajo de autorización de OAuth 2.0 y rfc6750: el marco de trabajo de autorización de OAuth 2.0: uso del token del portador
- Admite la autenticación de programas cliente de CardDAV mediante la autenticación HTTP de OAuth 2.0. Google no admite ningún otro método de autenticación. Para la seguridad de los datos de contacto, exigimos que las conexiones CardDAV usen HTTPS.
- rfc6764: Localización de los servicios para las extensiones de calendario a WebDAV (CalDAV) y las extensiones de VCV a WebDAV (CardDAV)
- El arranque de las URLs de CardDAV debe llevarse a cabo de acuerdo con la sección 6 de rfc6764.
- Admite caldav-ctag-02: Calendar Collection Entity Tag (CTag) en CalDAV, que se comparte entre las especificaciones CardDAV y CalDAV. El
ctag
de los contactos es como un recursoETag
; cambia cuando se modifica algún elemento de la libreta de direcciones. Esto permite que el programa cliente determine rápidamente que no necesita sincronizar ningún contacto modificado. - Google usa VCard 3.0 como formato de codificación de contactos. Consulta: rfc6350: VCard 3.0.
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.
- Principal
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- https://www.googleapis.com/carddav/v1/principals/
- Conjunto de casas
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists
- https://www.googleapis.com/carddav/v1/principals/
- Libreta de direcciones
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default
- https://www.googleapis.com/carddav/v1/principals/
- Contacto
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default/contactId
- https://www.googleapis.com/carddav/v1/principals/
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 unsync-token
. Sondear periódicamente la propiedadgetctag
dará como resultado una limitación.
- Los programas cliente usan la solicitud
- Con el token de sincronización
- Los programas cliente usan la solicitud
PROPFIND
sync-token
en la libreta de direcciones para obtener elsync-token
que representa su estado actual. Las aplicaciones cliente deben almacenar este valor y emitir solicitudessync-collection
REPORT
periódicas para determinar los cambios desde la últimasync-token
emitida. Los tokens emitidos son válidos durante 29 días y la respuestaREPORT
contendrá unsync-token
nuevo.
- Los programas cliente usan la solicitud
- Usa ETags
- Las aplicaciones cliente emiten una solicitud
PROPFIND
degetetag
en el recurso de la libreta de direcciones (con el encabezadoDEPTH
igual aDEPTH_1
). Si se mantiene el valor deETag
de cada contacto, un programa cliente puede solicitar el valor de los contactos en los que se cambió suETag
.
- Las aplicaciones cliente emiten una solicitud
- 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 unETag
para el contacto.
- Las aplicaciones cliente recuperan contactos mediante una solicitud
- 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.
- Las aplicaciones cliente emiten una solicitud
- 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 elETag
conocido actualmente del contacto. Luego, el servidor rechazará la solicitudPUT
(conHTTP 412
) si elETag
actual en el servidor es diferente delETag
enviado por el programa cliente. Esto permite una serialización optimista de las actualizaciones.
- Las aplicaciones cliente emiten una solicitud
- Borrar un contacto
- Las aplicaciones cliente borran un contacto mediante la emisión de una solicitud
DELETE
contra el URI del contacto.
- Las aplicaciones cliente borran un contacto mediante la emisión de una solicitud