連絡先は、Google の CardDAV プロトコルを使用して表示、管理できます。
連絡先はユーザーの Google アカウントに保存されます。ほとんどの Google サービスは連絡先リストにアクセスできます。クライアント アプリケーションは、CardDAV API を使用して、新しい連絡先の作成、既存の連絡先の編集または削除、特定の条件に一致する連絡先の照会を行うことができます。
仕様
完全な仕様は実装されていませんが、Apple iOSTM Contacts や macOS などのクライアントの多くは正しく相互運用できます。
関連する各仕様における Google の CardDAV サポートは次のとおりです。
- rfc2518: HTTP Extensions for Distributed Authoring(WebDAV)
- HTTP メソッド
GET
、PUT
、DELETE
、OPTIONS
、PROPFIND
をサポートします。 - HTTP メソッド
LOCK
、UNLOCK
、COPY
、MOVE
、MKCOL
はサポートしません。 - 任意の(ユーザー定義の)WebDAV プロパティはサポートされていません。
- WebDAV アクセス制御(rfc3744)はサポートされていません。
- HTTP メソッド
- rfc5995: POST を使用して WebDAV コレクションにメンバーを追加する
- ID を指定せずに新しい連絡先を作成できます。
- rfc6352: CardDAV: ウェブ分散作成およびバージョニング(WebDAV)への vCard 拡張機能
- HTTP メソッド
REPORT
をサポートしますが、定義されたレポートがすべて実装されるわけではありません。 - プリンシパル コレクションと連絡先コレクションの提供をサポートします。
- HTTP メソッド
- rfc6578: WebDAV 用のコレクション同期
- クライアント アプリケーションは、最初の同期の後、このオペレーション モードに切り替える必要があります。
- rfc6749: OAuth 2.0 認可フレームワーク、rfc6750: OAuth 2.0 認可フレームワーク: 署名なしトークンの使用
- OAuth 2.0 HTTP 認証を使用した CardDAV クライアント プログラムの認証をサポートします。Google では他の認証方法をサポートしていません。連絡先データのセキュリティを確保するため、CardDAV 接続では HTTPS を使用する必要があります。
- rfc6764: WebDAV へのカレンダーの拡張機能(CalDAV)と vCard の WebDAV への拡張機能(CardDAV)の探索サービス
- CardDAV URL のブートストラップは、rfc6764 のセクション 6 に従って行う必要があります。
- CardDAV 仕様と CalDAV 仕様で共有される caldav-ctag-02: Calendar Collection Entity Tag(CTag)in CalDAV をサポートしています。連絡先
ctag
はリソースETag
に似ており、連絡先のアドレス帳が変更されると変わります。これにより、クライアント プログラムは、変更された連絡先を同期する必要がないことを素早く判断できます。 - Google では、連絡先のエンコード形式として VCard 3.0 を使用しています。rfc6350: VCard 3.0 をご覧ください。
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 に従って検出する必要があります。
- プリンシパル
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- https://www.googleapis.com/carddav/v1/principals/
- ホームセット
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists
- https://www.googleapis.com/carddav/v1/principals/
- アドレス帳
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default
- https://www.googleapis.com/carddav/v1/principals/
- 連絡先
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default/contactId
- https://www.googleapis.com/carddav/v1/principals/
連絡先の同期
以下に、サポートされているオペレーションの一般的な説明を示します。デベロッパーは、関連する 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
を使用)を拒否します。これにより、更新をオプティミスティックにシリアル化できます。
- クライアント アプリは、更新された連絡先を VCard 3.0 形式で
- 連絡先の削除
- クライアント アプリケーションは、連絡先 URI に対して
DELETE
リクエストを発行することにより、連絡先を削除します。
- クライアント アプリケーションは、連絡先 URI に対して