Windows Live™ Contacts API は HTTP ベースのサービスです。このサービスを使用すると、プログラムによって Windows Live Contacts アドレス帳データベース サービスにクエリを送信し、結果を取得することができます。
Windows Live Contacts API は、Windows Live ユーザーのアドレス帳に対応した詳細な連絡先管理インターフェイスに加えて、招待状を送信する際に必要な連絡先データのサブセットを表示する方法を提供します。
それぞれの表示方法と一連の機能は、データの所有者によって制御されます。データの所有者とは、Windows Live Hotmail® や Windows Live Messenger など、Windows Live の各製品やアプリケーションを使用してアドレス帳を管理する Windows Live ユーザーのことです。
代理認証
サードパーティの開発者が Live Contacts サービスにおいて Windows Live ユーザーのデータにアクセスできるようにするには、最初にデータの所有者にアクセス許可を求める必要があります。その際には Windows Live ユーザーに対して、そのユーザーのデータへのアクセスを要求しているサードパーティ サービスによる "同意" ページが表示されます。
アクセス要求のタイプは、Windows Live ID 代理認証サービスに対して、要求されているデータ固有のオファー ID を提供することによって決まります。
詳細については、「アプリケーション プロバイダ向けの Windows Live ID Delegated Authentication SDK」を参照してください。
Windows Live ユーザーは、Windows Live にサインインした後に、要求を受諾または拒否することができます。ユーザーが要求を受諾すると、その同意が保存され、同意トークンが呼び出し元のサードパーティに返されます。
次に、その同意トークンのパーツを使用して Live Contacts API への呼び出しが行われ、その API は以下の条件がすべて真の場合にデータを返します。
- サードパーティ向けに保存された同意が期限切れではない
- サードパーティ向けに保存された同意が Windows Live ユーザーによって破棄されていない
- 要求されているデータに対して委任トークンが有効である
- 委任トークンが期限切れではない
Windows Live Contacts のオファー
上記で説明したように、Windows Live ユーザーのアドレス帳データにアクセスできるようにするには、サードパーティがそのデータを配置する用途に基づき、データの所有者が最初にアクセス要求に同意する必要があります。サードパーティは要件に応じて、以下の 1 つ以上のオファーに対応した代理認証サービスを提供することにより、アクセスを要求することができます。
| オファー ID | アクセスの範囲 |
|---|---|
Contacts.Update |
すべての連絡先情報の更新/追加 |
Contacts.View |
すべての連絡先情報の表示 |
Contacts.Invite |
名、姓、および優先される電子メール アドレスの表示 |
アクセスはこのプロセスから返される同意トークンを使用してのみ提供されるため、Windows Live Contacts サービスを使用する前に、代理認証サービスとプロセスに関するオンライン ドキュメントをお読みください。
アプリケーション プロバイダ向けの Windows Live ID Delegated Authentication SDK
Windows Live Contacts サービスの必要条件
代理認証サービスから返される同意トークン内には、Windows Live Contacts サービスへの呼び出しを行う際に重要となる以下の 2 つの要素があります。
- 代理認証トークン (DAT)
- Location ID (lid)
同意トークンは返されるときに URL でエンコードされ、通常は以下に示す同意トークンの各部を展開するために最初にエンコードが解除されます。
同意トークンから取り出される lid パラメータは、サービスを介してアクセスされるアドレス帳を識別する目的で使用されるため、サービス URL 部分を形成しています。
DAT の値は、サードパーティの呼び出し元アプリケーションを認証するトークンであり、Live Contacts サービスによってユーザーの保存済みの同意レコードに照らして検証され、呼び出し元のサードパーティと lid パラメータで識別されるアドレス帳の組み合わせに対して、委任された権限が最新かつ有効であるかが確認されます。
次に、たとえば以下の方法で、呼び出し用の HTTP 承認ヘッダーを作成する目的で DAT の値が使用されます。
Request.Headers.Add(“Authorization”, “DelegatedToken dt=\”” + DAT + “\””);
このヘッダーの値は、最初に同意プロセスによって返される DAT となり、要求 URI によって識別されるユーザーの場所に対応する必要があり、対応しない場合は呼び出しが拒否されます。
同意の承認または DAT が期限切れの場合、その呼び出しは拒否されるため、再びユーザーの同意を求めるか、同意トークンを書き換える必要があります。
Windows Live Contacts サービス エントリ ポイント
同意トークンの取得には代理認証サービスを使用し、承認ヘッダーの作成には DAT を使用し、Live Contacts サービス エントリ ポイントの作成には同意トークンの lid パラメータを使用します。
サードパーティ製アプリケーションが Contacts.Invite のオファー ID を使用してアクセスを要求した場合は、以下のサービス エントリ ポイントが有効になり、GET メソッドにのみ適用されます。
https://livecontacts.services.live.com/users/@C@\<intlid>/rest/invitationsbyemail
サードパーティ製アプリケーションが、他の使用可能な Contacts オファーのいずれかを使用してアクセスを要求した場合は、以下のサービス エントリ ポイントによって、Contacts スキーマ全体へのアクセスが提供されます。
https://livecontacts.services.live.com/users/@C@\<intlid>/rest/livecontacts
この URL の <intlid> 部分は、代理認証サービスから返される同意トークン内の lid 値から生成される符号付き 64 ビットの整数です。
以下に、lid の値を intlid に変換する代表的な方法を示します。
Long intlid=Int64.Parse(lid,System.Globalization.NumberStyles.HexNumber)
注意 どちらのエントリ ポイントも SSL 接続を必要とします。その他の接続方法は使用できません。
ドキュメント マップ
SDK ドキュメントは以下の 4 つのセクションに分かれています。
Windows Live Contacts API をお使いになる前に — Windows Live Contacts とのインターフェイスに使用される Windows Live Contacts Representational State Transfer (REST) の実装について紹介しています。
Windows Live Contacts API について — Windows Live Contacts API とショッピング サイトのシナリオについて説明しています。
Windows Live Contacts API の使用 — データの形式と要素、要求の作成と提供、アクセス制御リスト (ACL) と認証、保護者による制限、および Windows Live Contacts API で使用される URI とヘッダーの形式について説明しています。
Windows Live Contacts API リファレンス — 開発者が Windows Live Contacts API で使用可能なメソッドについての情報が記載されています。
その他のリソース
- Windows Live のその他のサービスや開発者向けサービスについては、http://dev.live.com を参照してください。
- その他の XML ベースのサービスやテクノロジについては、MSDN XML Developer Center を参照してください。
- Web サービスやその他の分散テクノロジについては、MSDN Developer Center を参照してください。
- HTTP/1.1 プロトコルについては、http://www.w3.org/Protocols/rfc2616/rfc2616.html を参照してください。
関連項目
その他のリソース
アプリケーション プロバイダ向けの Windows Live ID Delegated Authentication SDK