CardDAV プロトコルを使用して連絡先を管理する

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

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

仕様

完全な仕様は実装されていませんが、Apple iOSTM 連絡先や macOS などの多くのクライアントが正しく相互運用する必要があります。

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

Google の CardDAV を使用するには OAuth 2.0 が必要です

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

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

CardDAV プロトコルを使用すると、アドレス帳と連絡先リソースの URI を検出できます。URI はハードコードしないでください。ハードコードはいつでも変更できるからです。

クライアント アプリケーションでは HTTPS を使用し、ユーザーの Google アカウントに対して OAuth 2.0 認証を行う必要があります。CardDAV サーバーは、Google アカウントの OAuth 2.0 認証により HTTPS 経由で到着し、アプリケーションが DevConsole に登録されない限り、リクエストを認証しません。Basic 認証を使用して HTTP 経由で接続しようとすると、またはメールアドレスとパスワードが Google アカウントと一致しない場合は、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 検出を定期的に再試行して、キャッシュされたパスがまだ最新であることを確認し、パスが変更された場合は再同期する必要があります。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/list
  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 PROPFIND リクエストを使用して、現在の状態を表す sync-token を取得します。クライアント アプリケーションは、この値を保存して、前回の sync-token 以降の変更を確認するために、定期的に sync-collection REPORT リクエストを発行する必要があります。発行されたトークンは 29 日間有効で、REPORT レスポンスには新しい sync-token が含まれます。
  • ETag の使用
    • クライアント アプリケーションがアドレスブック リソースで getetag PROPFIND リクエストを発行します（DEPTH ヘッダーは DEPTH_1 になります）。各連絡先の ETag 値を保持することで、クライアント プログラムは、ETag が変更された連絡先の値をリクエストできます。
  • 連絡先の取得
    • クライアント アプリケーションは、addressbook-multiget REPORT リクエストを発行して連絡先を取得します。連絡先 URI のリストを指定すると、リクエストされたすべての連絡先が VCard 3.0 値として返されます。各エントリには、連絡先の ETag が含まれています。
  • 連絡先の挿入
    • クライアント アプリケーションが、VCard 3.0 形式の新しい連絡先を含む POST リクエストを発行します。レスポンスには、新しい連絡先の ID が含まれます。
  • 連絡先の更新
    • クライアント アプリケーションが、VCard 3.0 形式の更新された連絡先を使用して PUT リクエストを発行します。連絡先がアドレス帳にすでに存在する場合、連絡先が更新されます。
    • クライアント アプリケーションには、現在連絡先に登録されている ETag を含む If-Match ヘッダーを含める必要があります。サーバー上の現在の ETag がクライアント プログラムから送信された ETag と異なる場合、サーバーは HTTP 412 を使用して PUT リクエストを拒否します。これにより、更新の楽観的なシリアル化が可能になります。
  • 連絡先の削除
    • クライアント アプリケーションは、連絡先 URI に対して DELETE リクエストを発行して連絡先を削除します。