Kontakte mit dem CardDAV-Protokoll verwalten

Sie können Ihre Kontakte mit dem CardDAV-Protokoll von Google ansehen und verwalten.

Kontakte werden im Google-Konto des Nutzers gespeichert. Die meisten Google-Dienste haben Zugriff auf die Kontaktliste. Ihre Clientanwendung kann die CardDAV API verwenden, um neue Kontakte zu erstellen, vorhandene Kontakte zu bearbeiten oder zu löschen und Kontakte abzufragen, die bestimmten Kriterien entsprechen.

Technische Daten

Die vollständige Spezifikation ist nicht implementiert, aber viele Clients wie Apple iOSTM Contacts und macOS sollten ordnungsgemäß zusammenarbeiten.

Für jede relevante Spezifikation bietet Google folgende CardDAV-Unterstützung:

• rfc2518: HTTP Extensions for Distributed Authoring (WebDAV)
  • Unterstützt die HTTP-Methoden GET, PUT, DELETE, OPTIONS und PROPFIND.
  • Unterstützt nicht die HTTP-Methoden LOCK, UNLOCK, COPY, MOVE oder MKCOL.
  • Unterstützt keine beliebigen (benutzerdefinierten) WebDAV-Properties.
  • Unterstützt nicht WebDAV Access Control (rfc3744).
• rfc5995: POST zum Hinzufügen von Mitgliedern zu WebDAV-Sammlungen verwenden
  • Unterstützt das Erstellen neuer Kontakte ohne Angabe einer ID.
• rfc6352: CardDAV: vCard Extensions to Web Distributed Authoring and Versioning (WebDAV)
  • Die HTTP-Methode REPORT wird unterstützt, aber es sind nicht alle definierten Berichte implementiert.
  • Unterstützt die Bereitstellung einer Hauptkonto- und einer Kontaktsammlung.
• rfc6578: Sammlungssynchronisierung für WebDAV
  • Clientanwendungen müssen nach der ersten Synchronisierung in diesen Betriebsmodus wechseln.
• rfc6749: The OAuth 2.0 Authorization Framework und rfc6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage
  • Unterstützt die Authentifizierung von CardDAV-Clientprogrammen mit der OAuth 2.0-HTTP-Authentifizierung. Google unterstützt keine andere Authentifizierungsmethode. Zur Sicherheit der Kontaktdaten müssen CardDAV-Verbindungen HTTPS verwenden.
• rfc6764: Locating Services for Calendaring Extensions to WebDAV (CalDAV) und vCard Extensions to WebDAV (CardDAV)
  • Das Bootstrapping von CardDAV-URLs muss gemäß Abschnitt 6 von rfc6764 erfolgen.
• Unterstützt das caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV, das auch von den CardDAV- und CalDAV-Spezifikationen genutzt wird. Der Kontakt ctag ist wie eine Ressource ETag; er ändert sich, wenn sich etwas im Adressbuch des Kontakts geändert hat. So kann das Client-Programm schnell feststellen, dass es keine geänderten Kontakte synchronisieren muss.
• Google verwendet VCard 3.0 als Kontaktcodierungsformat. Weitere Informationen finden Sie unter rfc6350: VCard 3.0.

CardDAV von Google erfordert OAuth 2.0

Die CardDAV-Oberfläche von Google erfordert OAuth 2.0. Informationen zur Verwendung von OAuth 2.0 für den Zugriff auf Google APIs finden Sie in der verlinkten Dokumentation unten:

• Mit OAuth 2.0 auf Google APIs zugreifen
• OAuth 2.0 für installierte Anwendungen verwenden

Verbindung zum CardDAV-Server von Google herstellen

Das CardDAV-Protokoll ermöglicht die Erkennung des Adressbuchs und der URIs der Kontaktressourcen. URIs dürfen nicht hartcodiert werden, da sie sich jederzeit ändern können.

Clientanwendungen müssen HTTPS verwenden und die OAuth 2.0-Authentifizierung muss für das Google-Konto des Nutzers bereitgestellt werden. Der CardDAV-Server authentifiziert eine Anfrage nur, wenn sie über HTTPS mit OAuth 2.0-Authentifizierung eines Google-Kontos ankommt und Ihre Anwendung in der DevConsole registriert ist. Jeder Versuch, eine Verbindung über HTTP mit Basisauthentifizierung oder mit einer E-Mail-Adresse bzw. einem Passwort herzustellen, die bzw. das nicht mit einem Google-Konto übereinstimmt, führt zu einem HTTP-401 Unauthorized-Antwortcode.

Um CardDAV zu verwenden, muss Ihr Clientprogramm zuerst eine Verbindung zum kanonischen Erkennungspfad herstellen. Dazu wird eine HTTP-PROPFIND ausgeführt:

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

Nach der Weiterleitung (HTTP 301) an eine Adressbuchressource kann Ihr Clientprogramm dann einen PROPFIND-Vorgang für diese Ressource ausführen, um die Attribute DAV:current-user-principal, DAV:principal-URL und addressbook-home-set zu ermitteln. Ihr Clientprogramm kann dann das Hauptadressbuch ermitteln, indem es einen PROPFIND für addressbook-home-set ausführt und nach den Ressourcen addressbook und collection sucht. Eine vollständige Beschreibung dieses Prozesses geht jedoch über den Rahmen dieses Dokuments hinaus. Weitere Informationen finden Sie unter rfc6352.

Der Weiterleitungspfad, der in der HTTP 301-Antwort über PROPFIND für den bekannten URI zurückgegeben wird, darf nicht dauerhaft im Cache gespeichert werden (gemäß rfc6764). Geräte sollten die bekannte URI-Erkennung regelmäßig wiederholen, um zu prüfen, ob der im Cache gespeicherte Pfad noch aktuell ist, und neu zu synchronisieren, falls sich der Pfad ändert. Google empfiehlt einen Preis alle zwei bis vier Wochen.

Ressourcen

CardDAV verwendet REST-Konzepte. Clientanwendungen agieren auf Ressourcen, die durch ihre URIs festgelegt sind. Die aktuelle URI-Struktur wird hier angegeben, damit Entwickler die Konzepte im folgenden Abschnitt besser verstehen können. Die Struktur kann sich ändern und darf nicht hartcodiert sein. Vielmehr sollten die Ressourcen gemäß RFC erkannt werden.

1. Hauptkonto
   • https://www.googleapis.com/carddav/v1/principals/userEmail
2. Set „Home“
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists
3. Adressbuch
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
4. Kontakt
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

Kontakte synchronisieren

Im Folgenden finden Sie eine allgemeine Beschreibung der unterstützten Vorgänge. Entwickler sollten sich die Details im entsprechenden RFC ansehen. Anfragen und Antworten sind größtenteils in XML codiert. Dies sind die Hauptvorgänge, die von Clientanwendungen zur Synchronisierung verwendet werden:

• CTag verwenden
  • Clientprogramme verwenden die Anfrage getctag PROPFIND für die Adressbuchressource, um festzustellen, ob sich ein Kontakt auf dem Server geändert hat, und daher, ob eine Synchronisierung erforderlich ist. Der Wert dieser Eigenschaft ändert sich garantiert, wenn sich der Kontakt ändert. Clientanwendungen sollten diesen Wert speichern und nur bei der ersten Synchronisierung und als Fallback verwenden, wenn ein sync-token ungültig wird. Die regelmäßige Abfrage des Attributs getctag führt zu einer Drosselung.
• Synchronisierungstoken verwenden
  • Clientprogramme verwenden die sync-token-PROPFIND-Anfrage an das Adressbuch, um die sync-token für den aktuellen Status abzurufen. Clientanwendungen müssen diesen Wert speichern und regelmäßig sync-collection-REPORT-Anfragen senden, um Änderungen seit dem letzten ausgegebenen sync-token zu ermitteln. Ausgestellte Tokens sind 29 Tage lang gültig und die Antwort REPORT enthält ein neues sync-token.
• ETags verwenden
  • Clientanwendungen senden eine getetag PROPFIND-Anfrage an die Adressbuchressource, wobei der DEPTH-Header DEPTH_1 ist. Indem der ETag-Wert jedes Kontakts beibehalten wird, kann ein Clientprogramm den Wert der Kontakte anfordern, deren ETag geändert wurde.
• Kontakte abrufen
  • Clientanwendungen rufen Kontakte ab, indem sie die Anfrage addressbook-multiget REPORT senden. Anhand einer Liste von Kontakt-URIs werden im Bericht alle angeforderten Kontakte als VCard 3.0-Werte zurückgegeben. Jeder Eintrag enthält ein ETag für den Kontakt.
• Kontakt einfügen
  • Clientanwendungen senden eine POST-Anfrage an den neuen Kontakt im VCard 3.0-Format. Die Antwort enthält die ID des neuen Kontakts.
• Kontakt aktualisieren
  • Clientanwendungen senden eine PUT-Anfrage an den aktualisierten Kontakt im vCard 3.0-Format. Der Kontakt wird aktualisiert, wenn er bereits im Adressbuch vorhanden ist.
  • Clientanwendungen sollten einen If-Match-Header mit dem aktuell bekannten ETag des Kontakts enthalten. Der Server lehnt dann die PUT-Anfrage (mit HTTP 412) ab, wenn sich die aktuelle ETag auf dem Server von der ETag unterscheidet, die vom Clientprogramm gesendet wurde. Dies ermöglicht eine optimistische Serialisierung von Updates.
• Kontakt löschen
  • Clientanwendungen löschen einen Kontakt, indem sie eine DELETE-Anfrage an den Kontakt-URI senden.