Kontakte mit dem CardDAV-Protokoll verwalten

Sie können Ihre Kontakte mit dem CardDAV-Protokoll von Google anzeigen 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 bestimmte Kriterien erfüllen.

Spezifikationen

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

Für jede relevante Spezifikation wird der CardDAV-Support von Google so verwendet:

• 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.
  • Beliebige (benutzerdefinierte) WebDAV-Properties werden nicht unterstützt.
  • Unterstützt nicht die WebDAV-Zugriffssteuerung (rfc3744)
• rfc5995: Mit POST Mitglieder zu WebDAV-Sammlungen hinzufügen
  • Unterstützt das Erstellen neuer Kontakte ohne Angabe einer ID.
• rfc6352: CardDAV: vCard Extensions to Web Distributed Authoring and Versioning (WebDAV)
  • Unterstützt die HTTP-Methode REPORT, aber nicht alle definierten Berichte sind implementiert.
  • Unterstützt die Bereitstellung einer Haupt- und einer Kontaktsammlung.
• rfc6578: Sammlungssynchronisierung für WebDAV
  • Client-Anwendungen müssen nach der ersten Synchronisierung in diesen Betriebsmodus wechseln.
• rfc6749: The OAuth 2.0 Authorization Framework und rfc6750: OAuth 2.0 Authorization Framework: Bearer Token Usage
  • Unterstützt die Authentifizierung von CardDAV-Clientprogrammen mit OAuth 2.0-HTTP-Authentifizierung. Google unterstützt keine andere Authentifizierungsmethode. Für die Sicherheit von Kontaktdaten ist die Verwendung von HTTPS für CardDAV-Verbindungen erforderlich.
• rfc6764: Services for Calendaring Extensions to WebDAV (CadDAV) and vCard Extensions to WebDAV (CardDAV)
  • Das Bootstrapping von CardDAV-URLs muss gemäß Abschnitt 6 von rfc6764 erfolgen.
• Unterstützt caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV, das von den CardDAV- und CalDAV-Spezifikationen gemeinsam genutzt wird. Die Kontakte ctag sind wie eine Ressource ETag. Sie ändern sich, wenn sich etwas im Adressbuch des Kontakts geändert hat. So kann das Clientprogramm schnell feststellen, dass keine geänderten Kontakte synchronisiert werden müssen.
• Google verwendet VCard 3.0 als Format für die Kontaktcodierung. Weitere Informationen finden Sie unter rfc6350: VCard 3.0.

Für CardDAV von Google ist OAuth 2.0 erforderlich

Für die CardDAV-Benutzeroberfläche von Google ist OAuth 2.0 erforderlich. Informationen zum Verwenden 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

Verbindung zum CardDAV-Server von Google herstellen

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

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

Damit Sie CardDAV verwenden können, muss Ihr Clientprogramm zuerst eine Verbindung zum kanonischen Erkennungspfad herstellen, indem Sie ein HTTP-PROPFIND für Folgendes ausführen:

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

Nach der Weiterleitung (HTTP 301) zu einer Adressbuchressource kann dein Clientprogramm anschließend eine PROPFIND 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. Dazu führt es eine PROPFIND auf der addressbook-home-set aus und sucht nach den Ressourcen addressbook und collection. Eine ausführliche Beschreibung dieses Prozesses wird in diesem Dokument nicht behandelt. Weitere Informationen finden Sie unter rfc6352.

Der Weiterleitungspfad, der in der HTTP 301-Antwort über eine PROPFIND-Antwort im bekannten URI zurückgegeben wird, darf nicht dauerhaft 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 sie neu synchronisieren, wenn sich der Pfad ändert. Google empfiehlt alle zwei bis vier Wochen.

Ressourcen

CardDAV verwendet REST-Konzepte. Clientanwendungen wirken sich auf Ressourcen aus, die anhand ihrer URIs angegeben 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. Stattdessen sollten die Ressourcen gemäß RFC erkannt werden.

1. Hauptkonto
   • https://www.googleapis.com/carddav/v1/Principals/userEmail
2. Set „Zuhause“
   • 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 nach den Details im entsprechenden RFC suchen. Anfragen und Antworten werden meistens in XML codiert. Dies sind die Hauptvorgänge, die von Clientanwendungen zur Synchronisierung verwendet werden:

• CTag verwenden
  • Clientprogramme verwenden die getctag-PROPFIND-Anfrage an die Adressbuchressource, um festzustellen, ob sich ein Kontakt auf dem Server geändert hat und daher eine Synchronisierung erforderlich ist. Der Wert dieser Eigenschaft ändert sich garantiert, wenn sich ein Kontakt ändert. Clientanwendungen sollten diesen Wert speichern und nur bei der ersten Synchronisierung und als Fallback verwenden, wenn sync-token ungültig wird. Das regelmäßige Abrufen des Attributs getctag führt zu einer Drosselung.
• Sync-Token verwenden
  • Clientprogramme verwenden die PROPFIND-Anfrage sync-token für das Adressbuch, um die sync-token abzurufen, die ihren aktuellen Status darstellt. Client-Anwendungen müssen diesen Wert speichern und regelmäßig sync-collection-REPORT-Anfragen senden, um Änderungen seit dem letzten sync-token zu ermitteln. Ausgestellte Tokens sind 29 Tage lang gültig und die Antwort REPORT enthält einen neuen sync-token.
• ETags verwenden
  • Clientanwendungen senden eine getetag-PROPFIND-Anfrage an die Adressbuchressource (mit einem DEPTH-Header, der DEPTH_1 entspricht). Wenn der Wert ETag jedes Kontakts beibehalten wird, kann ein Clientprogramm den Wert von Kontakten anfordern, deren ETag geändert wurde.
• Kontakte abrufen
  • Clientanwendungen rufen Kontakte ab, indem sie eine addressbook-multiget-REPORT-Anfrage senden. Bei einer Liste von Kontakt-URIs werden im Bericht alle angeforderten Kontakte als VCard 3.0-Werte zurückgegeben. Jeder Eintrag enthält eine ETag für den Kontakt.
• Kontakt einfügen
  • Clientanwendungen senden eine POST-Anfrage mit dem neuen Kontakt im VCard 3.0-Format. Die Antwort enthält die ID des neuen Kontakts.
• Kontakt aktualisieren
  • Clientanwendungen senden eine PUT-Anfrage mit dem 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 Anfrage PUT (mit HTTP 412) ab, wenn sich die aktuelle ETag auf dem Server von der vom Clientprogramm gesendeten ETag unterscheidet. Dies ermöglicht eine optimale Serialisierung von Updates.
• Kontakt löschen
  • Clientanwendungen löschen einen Kontakt durch die Ausgabe einer DELETE-Anfrage an den Kontakt-URI.