CardDAV プロトコルで連絡先を管理する

連絡先は、Google の CardDAV プロトコルを使用して表示、管理できます。

連絡先はユーザーの Google アカウントに保存されます。ほとんどの Google サービスは連絡先リストにアクセスできます。クライアント アプリケーションは、CardDAV API を使用して、新しい連絡先の作成、既存の連絡先の編集または削除、特定の条件に一致する連絡先の照会を行うことができます。

仕様

完全な仕様は実装されていませんが、Apple iOSTM Contacts や macOS などのクライアントの多くは正しく相互運用できます。

関連する各仕様における Google の CardDAV サポートは次のとおりです。

Google の CardDAV で OAuth 2.0 が必要

Google の CardDAV インターフェースには OAuth 2.0 が必要です。OAuth 2.0 を使用して Google API にアクセスする方法については、以下のリンク先のドキュメントをご覧ください。

Google の CardDAV サーバーに接続する

CardDAV プロトコルを使用すると、アドレス帳と連絡先リソースの URI を検出できます。URI は随時変更される可能性があるため、URI をハードコードしないでください。

クライアント アプリケーションは HTTPS を使用し、ユーザーの Google アカウントに OAuth 2.0 認証を提供する必要があります。CardDAV サーバーは、Google アカウントの OAuth 2.0 認証を使用して HTTPS 経由で受信され、アプリケーションが DevConsole に登録されている場合を除き、リクエストを認証しません。Basic 認証または Google アカウントと一致しないメールアドレスとパスワードを使用して HTTP 経由で接続しようとすると、HTTP 401 Unauthorized レスポンス コードが返されます。

CardDAV を使用するには、クライアント プログラムは最初に次の場所で HTTP PROPFIND を実行して、正規の検出パスに接続する必要があります。

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

アドレスブック リソースにリダイレクトされた（HTTP 301）と、クライアント プログラムはそのリソースで PROPFIND を実行して、DAV:current-user-principal、DAV:principal-URL、addressbook-home-set プロパティを検出できます。クライアント プログラムは、addressbook-home-set で PROPFIND を実行し、addressbook リソースと collection リソースを探すことで、プリンシパル アドレス帳を見つけることができます。このプロセスの詳しい説明は、このドキュメントの範囲外です。詳しくは、rfc6352 をご覧ください。

既知の URI で PROPFIND を介して HTTP 301 レスポンスで返されるリダイレクト パスは、永続的にキャッシュしないでください（rfc6764 を参照）。デバイスは、よく知られた URI の検出を定期的に再試行して、キャッシュされたパスがまだ最新かどうかを確認し、パスが変更された場合は再同期する必要があります。Google では 2 ～ 4 週間ごとの料金をおすすめします。

関連情報

CardDAV は REST コンセプトを使用します。クライアント アプリケーションは、URI で指定されたリソースに対して動作します。現在の URI 構造は、次のセクションのコンセプトを理解しやすいようにここで指定しています。構造は変わる可能性があるため、ハードコードしないでください。リソースは RFC に従って検出する必要があります。

  1. プリンシパル
    • https://www.googleapis.com/carddav/v1/principals/userEmail
  2. ホームセット
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists
  3. アドレス帳
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
  4. 連絡先
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

連絡先の同期

以下に、サポートされているオペレーションの一般的な説明を示します。デベロッパーは、関連する RFC で詳細を確認する必要があります。リクエストとレスポンスは主に XML でエンコードされます。クライアント アプリケーションで同期に使用される主なオペレーションは次のとおりです。

  • CTag の使用
    • クライアント プログラムは、アドレス帳リソースで getctag PROPFIND リクエストを使用して、サーバーで連絡先が変更されたかどうか、したがって同期が必要かどうかを判断します。連絡先が変更されると、このプロパティの値は変更されることが保証されます。クライアント アプリケーションは、この値を保存し、最初の同期時と、sync-token が無効になった際のフォールバックとしてのみ使用する必要があります。getctag プロパティを定期的にポーリングすると、スロットリングが発生します。
  • sync-token の使用
    • クライアント プログラムは、アドレス帳で sync-token PROPFIND リクエストを使用して、現在の状態を表す sync-token を取得します。クライアント アプリケーションは、この値を保存し、定期的に sync-collection REPORT リクエストを発行して、最後に発行された sync-token からの変更を特定する必要があります。発行されたトークンは 29 日間有効で、REPORT レスポンスには新しい sync-token が含まれます。
  • ETag の使用
    • クライアント アプリケーションは、アドレス帳リソース（DEPTH ヘッダーが DEPTH_1 と等しい）に getetag PROPFIND リクエストを発行します。各連絡先の ETag 値を維持することで、クライアント プログラムは ETag が変更された連絡先の値をリクエストできます。
  • 連絡先を取得する
    • クライアント アプリケーションは、addressbook-multiget REPORT リクエストを発行して連絡先を取得します。レポートでは、連絡先 URI のリストを指定して、リクエストされたすべての連絡先を VCard 3.0 の値として返します。各エントリには連絡先の ETag が含まれています。
  • 連絡先を挿入する
    • クライアント アプリケーションは、新しい連絡先を含む POST リクエストを VCard 3.0 形式で発行します。レスポンスには新しい連絡先の ID が含まれます。
  • 連絡先の更新
    • クライアント アプリは、更新された連絡先を VCard 3.0 形式で PUT リクエストを発行します。連絡先がすでにアドレス帳に存在する場合は、連絡先が更新されます。
    • クライアント アプリケーションには、連絡先の現在認識されている ETag を含む If-Match ヘッダーを含める必要があります。サーバーの現在の ETag がクライアント プログラムから送信された ETag と異なる場合、サーバーは PUT リクエスト（HTTP 412 を使用）を拒否します。これにより、更新をオプティミスティックにシリアル化できます。
  • 連絡先の削除
    • クライアント アプリケーションは、連絡先 URI に対して DELETE リクエストを発行することにより、連絡先を削除します。