Se usó la API de Cloud Translation para traducir esta página.

Administrar 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 los que coincidan con criterios específicos.

Especificaciones

La especificación completa no está implementada, pero muchos clientes, como los contactos de Apple iOSTM y macOS, deben interoperar correctamente.

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

rfc2518: Extensiones de HTTP para la creación distribuida (WebDAV)
- Admite los métodos HTTP GET, PUT, DELETE, OPTIONS y PROPFIND.
- No es compatible con los métodos HTTP LOCK, UNLOCK, COPY, MOVE ni MKCOL.
- No admite propiedades arbitrarias (definidas por el usuario) de WebDAV.
- No es compatible con el Control de acceso WebDAV (rfc3744).
rfc5995: Cómo usar POST para agregar miembros a las colecciones de WebDAV
- Permite crear contactos nuevos sin especificar un ID.
rfc6352: CardDAV: Extensiones de vCard para la creación y el control de versiones distribuidos en la Web (WebDAV)
- Admite el método HTTP REPORT, pero no todos los informes definidos se implementan.
- Admite proporcionar una colección principal y una colección de contactos.
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 framework 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 2.0 de OAuth. Google no admite ningún otro método de autenticación. Para garantizar la seguridad de los datos de contacto, las conexiones CardDAV requieren HTTPS.
rfc6764: Localización de servicios para las extensiones de Calendario en WebDAV (CalDAV) y las extensiones de vCard en WebDAV (CardDAV)
- El arranque de las URL CardDAV debe realizarse de acuerdo con la sección 6 de rfc6764.
Compatible con caldav-ctag-02: Etiqueta de entidad de colección de calendario (CTag) en CalDAV, que se comparte entre las especificaciones de CardDAV y CalDAV. Los contactos ctag son como un recurso ETag; cambian cuando algo cambia en la libreta de direcciones de contacto. Esto permite que el programa cliente determine rápidamente que no necesita sincronizar ningún contacto modificado.
Google utiliza VCard 3.0 como formato de codificación de contacto. 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 API de Google:

Conectando con el servidor CardDAV de Google

El protocolo CardDAV permite descubrir los URI de la libreta de direcciones y de 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 de CardDAV no autenticará una solicitud, a menos que llegue a través de HTTPS con la autenticación de OAuth 2.0 de una Cuenta de Google, y tu aplicación está registrada en DevConsole. Cualquier intento de conectarte mediante HTTP con la autenticación básica o con un correo electrónico o una contraseña que no coincidan con una Cuenta de Google dará como resultado 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 la ejecución de un PROPFIND HTTP en:

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 un PROPFIND para descubrir las propiedades DAV:current-user-principal, DAV:principal-URL y addressbook-home-set. Tu programa cliente puede descubrir la libreta de direcciones principal si realiza un 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 el descubrimiento de URI conocido de forma periódica para verificar si la ruta de acceso almacenada en caché aún está actualizada y volver a sincronizarse si la ruta cambia. Google recomienda aplicar una tasa cada dos o cuatro semanas.

Recursos

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

Director
- https://www.googleapis.com/carddav/v1/principales/userEmail
Conjunto de la casa
- https://www.googleapis.com/carddav/v1/principales/userEmail/lists
Libreta de direcciones
- https://www.googleapis.com/carddav/v1/principales/userEmail/lists/default
Contacto
- https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

Sincronizando contactos

La siguiente es una descripción general de las operaciones admitidas. Los desarrolladores deben buscar los detalles en la RFC correspondiente. 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:

Usa CTag
- Los programas cliente usan la solicitud getctag PROPFIND en el recurso de 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. El sondeo periódico de la propiedad getctag generará una limitación.
Uso del token de sincronización
- Los programas cliente usan la solicitud sync-token PROPFIND 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 REPORT periódicas sync-collection 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.
Uso de ETags
- Las aplicaciones cliente emiten una solicitud getetag PROPFIND en el recurso de libreta de direcciones (con el encabezado DEPTH igual a DEPTH_1). Si mantienes el valor ETag de cada contacto, un programa cliente puede solicitar el valor de los contactos que tenían su ETag modificado.
Recuperación de contactos
- Las aplicaciones cliente recuperan contactos mediante el envío de 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.
Inserción de un contacto
- Las aplicaciones cliente envían una solicitud POST con el contacto nuevo en formato VCard 3.0. La respuesta contendrá el ID del contacto nuevo.
Cómo actualizar un contacto
- Las aplicaciones cliente emiten una solicitud PUT con el contacto actualizado en formato VCard 3.0. El contacto se actualiza si el contacto ya existe en la libreta de direcciones.
- Las aplicaciones cliente deben incluir un encabezado If-Match con el ETag conocido del contacto. El servidor rechazará la solicitud PUT (con HTTP 412) si el ETag actual del servidor es diferente del ETag que envía el programa cliente. Esto permite una serialización optimista de actualizaciones.
Cómo borrar un contacto
- Las aplicaciones cliente borran un contacto mediante la emisión de una solicitud DELETE al URI del contacto.