本記事の対象APIは既にサポートされていません。記事は参考程度にご利用ください。
Application Based Storage API
今回からWindows Live ユーザーデータAPI群よりWindows Live Application Based Storage APIについて紹介します。このAPIは、Windows Live委任認証を利用する必要があります。委任認証については本連載の第14回と15回に紹介しましたので参考にしてください。また、Application Based Storage APIは、執筆時点でのAPIバージョンはAlpha 1.
さて、Application Based Storage APIを利用するとWebサイト
リソースへのアクセス
データにアクセスするにはWeb上でデータを読み書きするための規格であるAtomプロトコルを利用します。このAtomプロトコルの利用もApplication Based Storage APIの特徴です。共通的な仕様を利用しているため、ほかのAtomプロトコルを利用したアプリケーションとの連携も可能です。
実際にデータへアクセスする場合、ある書式に従ったURLへHTTPのGETやPOSTメソッドによりアクセスします。そのことによってファイル一覧の取得やフォルダの作成、ファイルのダウンロード・
承認の要求時にはオファーとアクションを指定する必要がありました。その承認要求に指定するpsパラメータには
そして、承認要求により委任トークンを取得後にアクセスするURLの書式は次のようになります。
https://cumulus.services.live.com/@C@[LID]/AtomApplicationStorage[/リソースへのパス][LID]には委任認証により取得した承認トークンのlidパラメータ、つまりユーザーデータの場所を示す識別子です。URLの末尾にはリソースへのパスを指定します。具体的なアクセス方法は後ほど紹介します。
ストレージの構造と構成
先にストレージについて一般的なファイルシステムと同じ階層構造と書きましたが、Application Based Storage独特の仕様もあります。URLに指定するリソースパスを指定するためにも理解が必要になってきますので、まずはApplication Based Storage APIで扱うストレージの構造について理解しましょう。
コレクションノードとアイテムノード
Application Based Storageはコレクションノードとアイテムノードと呼ばれる大きくふたつの要素から構成されています。コレクションノードには次の種類があり、コレクションノードは複数の要素を持つことができます。わかりやすく言えばフォルダですね。
- RootFolders
- Items
- DocumentStreams
- PhotoStreams
各コレクションの種類の内容はひとまず後にして、続いてアイテムノードには次の種類があります。
- Folder
- Document
- DocumnetStream
- Photo
- PhotoStream
アイテムノードにもFolderと名のつくものがあり少しややこしいですが、コレクションノードは複数の要素を表すもので、アイテムノードは単体のオブジェクトを表すものと考えてください。
ストレージの最上位の階層にはRootFoldersと呼ばれる特別なフォルダ群があります。そのフォルダより下の階層にあるフォルダに格納されているフォルダとファイル群はItemsと呼びます。
フォルダに格納できるもの、一般的にいうフォルダとファイルは、フォルダを表すFolder、文書ファイルを表すDocumentと画像を表すPhotoがあります。アップロードできる文書と画像の種類は何でもよいというわけでなく、サポートされているものは限られています。
DocumentStream(s)、PhotoStream(s)はここで扱いませんので割愛します。
RootFolders
ストレージの最上位階層にあるRootFoldersと呼ばれるフォルダ群のフォルダは、APIにより削除や名前の変更はできません。また、この階層のフォルダは、すべてのドメインで共有できるフォルダと、アクセスできるドメインが限定される複数のフォルダから成っています
ここまで説明した構造を図1に示します。
フォルダの階層は8段階までという制限があります。また、アップロードしたファイルの名前は変更できません
リソースパス
続いてアクセスする際にURLへ指定する、リソースへのパスの基本的な記述について説明します。フォルダやファイルには名前が付いていますが、APIからアクセスするときは一意な識別子を使って区別します。
たとえばRootFoldersの一覧を表す記述は次のようになります。
/RootFoldersRootFoldersは数字によって識別します。最上位階層のひとつフォルダを例に表すと次にように記述します。
/RootFolders(136)この場合136という識別子が付いたフォルダ単体を表しています。
RootFoldersより下の階層にてコレクションを表すにはItemsを使用します。たとえばフォルダ
/RootFolders(136)/ItemsRootFolders以外のオブジェクトは
/RootFolders(136)/Items('150F')/RootFolders(136)/Items('152D')上記の150Fというフォルダ直下のファイル一覧を表すには、
/RootFolders(136)/Items('150F')/Itemsという具合になります。その中の文書を表すには、
/RootFolders(136)/Items('150F')/Items('170D')となります。
最後に、上記の文書または画像へのリソースパスはアイテムノードを表していて、ファイルの中身
/RootFolders(136)/Items('150F')/Items('170D')/$value基本は以上です。理解頂けたでしょうか。リソースパスの記述と階層を図化したものを図2に示します。これら以外の記述による指定方法もありますが、それらについては出てきた時点で紹介します。
リソースプロバイダの応答の形式
リソースプロバイダにアクセスし、フォルダやファイルの一覧を取得する場合や、フォルダ・
- Feed
- Entry
- Plain XML
- Binary Stream
Feed、Entry
ストレージの構造やリソースパスの説明にて示したように、指定できる情報にはコレクションノードとアイテムノードがありました。またAtomプロトコルによるAPIであることも紹介しました。これらに直接関係しているのが、FeedとEntryです。AtomプロトコルはXMLベースの仕様のためXML形式のデータをリソースプロバイダから受け取ります。
コレクションノードをリソースパスに指定した場合は、AtomプロトコルのFeed要素として受け取ります。
リソースパスにコレクションノードを指定してフォルダ・
https://cumulus.services.live.com/@C@[LID]/AtomApplicationStorage/RootFolders<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:AS="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns:AppStorage="http://dev.live.com/AppStorage"
xmlns:Live="LiveAtomBase:">
...
<entry AS:type="Folder">
...
</entry>
<entry AS:type="Folder">
...
</entry>
</feed>
ほとんどの部分を省略しましたが、注目する点はコレクションの場合、<feed>要素の中に0個～複数個の<entry>要素が含まれたXMLデータとなります。entry要素の中を調べることでコレクション内にどういったアイテムが格納されているかを知ります。また、Application Based Storage用に複数のXML名前空間が指定されており
アイテムノードをリソースパスとして指定して情報を取得する場合は、AtomプロトコルのEntry要素としてデータを受け取ります。
https://cumulus.services.live.com/@C@[LID]/AtomApplicationStorage/RootFolders(n)<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:AS="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns:AppStorage="http://dev.live.com/AppStorage"
xmlns:Live="LiveAtomBase:"
AS:type="Folder">
<category ... />
<id>...</id>
<published>2008-07-12T12:11:26.147Z</published>
<updated>2008-09-07T08:47:06.353Z</updated>
<title>Common</title>
<author>
<name>Default Name</name>
</author>
<link href="..." rel="edit" type="application/atom+xml;type=entry" title="Folder" />
<link href="..." rel="related" type="application/atom+xml;type=feed" title="Items" />
<content type="application/xml">
<AS:properties>
<AppStorage:ID>136</AppStorage:ID>
</AS:properties>
</content>
</entry>
<entry>要素がひとつ返ってきています。アイテムノードを指定した場合、そのフォルダやファイルの情報を取得できますが、Feed要素で十分であることが多いのであまり使用しないのではないかと思います。
Plain XML
Feed要素やEntry要素で受け取った情報の中にあるtitle、published、updated、Versionの値は、次のようにアイテムノードを示すリソースパスの末尾に
https://cumulus.services.live.com/@C@[LID]/AtomApplicationStorage/RootFolders(n)/title<?xml version="1.0" encoding="utf-8"?>
<AppStorage:title
xmlns="http://www.w3.org/2005/Atom"
xmlns:AS="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns:AppStorage="http://dev.live.com/AppStorage"
xmlns:Live="LiveAtomBase:">Common</AppStorage:title>
Binary Stream
文書や画像データそのものを取得する場合は、リソースパスの末尾に
/RootFolders(136)/Items('150F')/Items('170D')/$valueおわりに
今回はここまでです。全くコードを書きませんでしたが、次回からは実際にアプリケーションを作りながらストレージにアクセスします。次のようなHTTP GETメソッドによる要求を行うと今回紹介した応答データを取得できます。先に進みたい方はトライしてみてください。詳しいコードは次回扱います。
GET /AtomApplicationStorage[/リソースへのパス] HTTP/1.1
Host: cumulus.services.live.com
User-Agent: [Name of User Agent]
Authorization: DelegatedToken dt="[委任トークン]"
括弧の部分は適当な値を指定してください。何もしていない状態でもRootFoldersの情報は取得できますね。委任トークンの取得方法や委任認証は本連載の14回と15回を参照してください。