Administra contactos con el protocolo CardDAV

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

Los contactos se almacenan en la Cuenta de Google del usuario. la mayoría de los servicios de Google 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 buscar contactos que coinciden con criterios particulares.

Especificaciones

No se implementa la especificación completa, pero muchos clientes, como Contactos de Apple iOS™ y macOS, deberían interactuar correctamente.

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

• rfc2518: Extensiones HTTP para la creación distribuida (WebDAV)
  • Admite los métodos HTTP GET, PUT, DELETE, OPTIONS y PROPFIND.
  • No admite los métodos HTTP LOCK, UNLOCK, COPY, MOVE ni MKCOL
  • No admite propiedades WebDAV arbitrarias (definidas por el usuario).
  • No admite el control de acceso de WebDAV (rfc3744).
• rfc5995: Uso de POST para agregar miembros a colecciones de WebDAV
  • Admite la creación de contactos nuevos sin especificar un ID.
• rfc6352: CardDAV: Extensiones de vCard para la autoría distribuida en la Web y Control de versiones (WebDAV)
  • Admite el método HTTP REPORT, pero no se admiten todos los informes definidos cuando se implementa un plan.
  • Admite proporcionar una colección principal y una 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 framework de autorización de OAuth 2.0: Uso de tokens de portador
  • Admite la autenticación de programas cliente de CardDAV con la autenticación HTTP de OAuth 2.0. Google no admite ningún otro método de autenticación. Por seguridad de los datos de contacto, solicitamos conexiones CardDAV para usar HTTPS
• rfc6764: Servicios de localización de extensiones de calendario para WebDAV (CalDAV) y extensiones de vCard para WebDAV (CardDAV)
  • El arranque de las URLs de CardDAV debe ocurrir de acuerdo con la sección 6 de rfc6764
• Admite 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 es como un recurso ETag; cambia cuando algo en el contacto la libreta de direcciones cambió. Esto permite que el programa cliente determine rápidamente que no necesite sincronizar ningún contacto modificado.
• Google utiliza VCard 3.0 como formato de codificación de contactos. Consulta lo siguiente: rfc6350: VCard 3.0

CardDAV de Google requiere OAuth 2.0

La interfaz de 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:

• Usa OAuth 2.0 para acceder a las APIs de Google
• Cómo usar OAuth 2.0 para aplicaciones instaladas

Conéctate al servidor CardDAV de Google

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

Las aplicaciones cliente deben usar HTTPS, y se debe proporcionar la 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 OAuth 2.0 autenticación de una Cuenta de Google, y tu aplicación se registra en Consola del desarrollador. Cualquier intento de conexión a través de HTTP con la autenticación básica o con un correo electrónico o una contraseña que no coincide con una Cuenta de Google genera una solicitud Código de respuesta de 401 Unauthorized.

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

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

Una vez redirigido (HTTP 301) a un recurso de libreta de direcciones, tu programa cliente puedes realizar un PROPFIND para descubrir el DAV:current-user-principal, DAV:principal-URL y addressbook-home-set propiedades. Luego, tu programa cliente puede descubrir la libreta de direcciones principal realizando una PROPFIND en addressbook-home-set y buscando 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 detalles.

La ruta de redireccionamiento que se muestra en la respuesta HTTP 301 a través de un PROPFIND en el URI conocido no debe almacenarse en caché de forma permanente (según rfc6764). Los dispositivos deben volver a intentar el descubrimiento de URIs conocidos de forma periódica para verificar si la ruta almacenada en caché sigue actualizada y volver a sincronizarla si la ruta cambia. Google recomienda una frecuencia de cada 2 a 4 semanas.

Recursos

CardDAV usa conceptos de REST. Las aplicaciones cliente actúan sobre recursos designadas por sus URIs. La estructura actual del URI se especifica aquí para ayudarte a los desarrolladores a comprender los conceptos de la siguiente sección. La estructura puede cambian y no deben codificarse. En cambio, los recursos deben descubrirse según la RFC.

1. Principal
   • https://www.googleapis.com/carddav/v1/principals/userEmail
2. Configuración de la casa
   • 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. Desarrolladores debe buscar los detalles en la RFC relevante. Las solicitudes y las respuestas se codifican principalmente en XML. Estas son las operaciones principales que usan las aplicaciones cliente para la sincronización:

• Cómo usar CTag
  • Los programas cliente usan la solicitud getctag PROPFIND en la libreta de direcciones. recurso para determinar si algún contacto cambió en el servidor y por lo tanto, si es necesaria 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. Sondeando periódicamente a las La propiedad getctag generará una limitación.
• Cómo usar sync-token
  • Los programas cliente usan la solicitud sync-token PROPFIND en la dirección. Reserva para obtener el objeto sync-token que representa su estado actual. Cliente las aplicaciones deben almacenar este valor y emitir sync-collection de forma periódica REPORT solicitudes para determinar los cambios desde la última emisión sync-token Los tokens emitidos son válidos por 29 días, y la respuesta REPORT contendrá un sync-token nuevo.
• Cómo usar ETags
  • Las aplicaciones cliente emiten una solicitud de PROPFIND de getetag en la dirección Reservar recurso (con el encabezado DEPTH igual a DEPTH_1). Manteniendo el valor ETag de cada contacto, un programa cliente puede solicitar el valor de contactos a los que se les cambió ETag
• Cómo recuperar contactos
  • Las aplicaciones cliente recuperan contactos emitiendo un addressbook-multiget solicitud REPORT. Si se proporciona una lista de URIs de contacto, el informe muestra todos los contactos solicitados como valores de vCard 3.0. Cada incluye un ETag para el contacto.
• Cómo insertar un contacto
  • Las aplicaciones cliente emiten 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 envían 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. El servidor rechazará PUT solicitud (con HTTP 412) si el ETag actual en el servidor se es diferente de la ETag enviada por el programa cliente. Esto permite que una serialización optimista de las actualizaciones.
• Cómo borrar un contacto
  • Las aplicaciones cliente borran un contacto mediante una solicitud de DELETE con el URI del contacto.