使ってみよう! Windows Live SDK/API

第16回Windows Live Application Based Storage API(1)

本記事の対象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.0と試験的なサービスです。今後サービス内容が変更される可能性は十分にありますのでご了承ください。

さて、Application Based Storage APIを利用するとWebサイト(Webアプリケーション)から多様なデータをWindows Liveデータセンター(ストレージ)へユーザーに代わり保管することができます。扱うことのできるデータは基本的には文字列となるアプリケーションの状態や設定値が想定されているようですが、画像などバイナリデータの保管も可能です。委任認証を利用していることからわかるように、ストレージへのアクセスはユーザーの承諾を得て初めてアプリケーションからアクセスが可能になります。ストレージは一般的なファイルシステムと同様にフォルダとファイルからなる階層構造となっています。

リソースへのアクセス

データにアクセスするにはWeb上でデータを読み書きするための規格であるAtomプロトコルを利用します。このAtomプロトコルの利用もApplication Based Storage APIの特徴です。共通的な仕様を利用しているため、ほかのAtomプロトコルを利用したアプリケーションとの連携も可能です。

実際にデータへアクセスする場合、ある書式に従ったURLへHTTPのGETやPOSTメソッドによりアクセスします。そのことによってファイル一覧の取得やフォルダの作成、ファイルのダウンロード・アップロードができます。その際の認証はWindows Live 委任認証により得られた委任トークンを使用した独自の認証方法になります。

承認の要求時にはオファーとアクションを指定する必要がありました。その承認要求に指定するpsパラメータには「ApplicationStorage.ReadWrite」と指定します。Application Based Storeage APIで指定できるオファーとアクションの組み合わせはこの1種類のみです。

そして、承認要求により委任トークンを取得後にアクセスする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]⁠。つまりWebサイトからはストレージの最上位階層には共有フォルダとWebサイトのドメインからアクセスできるフォルダの2個が見えている状態になります。共有のフォルダは「Common⁠⁠、それ以外の各ドメイン用のフォルダはGUIDによる名前が付いています。

ここまで説明した構造を図1に示します。

図1 ストレージの構造
図1 ストレージの構造

フォルダの階層は8段階までという制限があります。また、アップロードしたファイルの名前は変更できません(フォルダ名は変更可⁠⁠。

リソースパス

続いてアクセスする際にURLへ指定する、リソースへのパスの基本的な記述について説明します。フォルダやファイルには名前が付いていますが、APIからアクセスするときは一意な識別子を使って区別します。

たとえばRootFoldersの一覧を表す記述は次のようになります。

/RootFolders

RootFoldersは数字によって識別します。最上位階層のひとつフォルダを例に表すと次にように記述します。

/RootFolders(136)

この場合136という識別子が付いたフォルダ単体を表しています。

RootFoldersより下の階層にてコレクションを表すにはItemsを使用します。たとえばフォルダ「RootFolders(136)」が持つ要素、つまり このフォルダ直下にあるファイルの一覧を表すには次のようになります。

/RootFolders(136)/Items

RootFolders以外のオブジェクトは「150F」というような数字とアルファベット一文字の識別子によって表します。フォルダはF、文書はD、画像はPを使用します。たとえば以下のようになります。

/RootFolders(136)/Items('150F')
/RootFolders(136)/Items('152D')

上記の150Fというフォルダ直下のファイル一覧を表すには、

/RootFolders(136)/Items('150F')/Items

という具合になります。その中の文書を表すには、

/RootFolders(136)/Items('150F')/Items('170D')

となります。

最後に、上記の文書または画像へのリソースパスはアイテムノードを表していて、ファイルの中身(テキストやバイナリデータ)を表しているわけではありません。ファイル中身そのもののデータを取得する場合には次のように$valueを指定して表します。

/RootFolders(136)/Items('150F')/Items('170D')/$value

基本は以上です。理解頂けたでしょうか。リソースパスの記述と階層を図化したものを図2に示します。これら以外の記述による指定方法もありますが、それらについては出てきた時点で紹介します。

図2 ストレージの構造とリソースパス
図2 ストレージの構造とリソースパス

リソースプロバイダの応答の形式

リソースプロバイダにアクセスし、フォルダやファイルの一覧を取得する場合や、フォルダ・ファイル単体の情報を取得、または文書や画像データを取得する場合のリソースプロバイダから受け取るデータの形式についてみてみましょう。応答データ形式は、次の4種類に分類できます。

  • Feed
  • Entry
  • Plain XML
  • Binary Stream

Feed、Entry

ストレージの構造やリソースパスの説明にて示したように、指定できる情報にはコレクションノードとアイテムノードがありました。またAtomプロトコルによるAPIであることも紹介しました。これらに直接関係しているのが、FeedEntryです。AtomプロトコルはXMLベースの仕様のためXML形式のデータをリソースプロバイダから受け取ります。

コレクションノードをリソースパスに指定した場合は、AtomプロトコルのFeed要素として受け取ります。

リソースパスにコレクションノードを指定してフォルダ・ファイルの一覧情報を取得する場合、たとえば次のようにRootFoldersを指定したときは次のようなXMLデータを受け取ります。

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名前空間が指定されており(xmlns部分⁠⁠、独自形式のデータも含まれています(上記の例では省略しています⁠⁠。

アイテムノードをリソースパスとして指定して情報を取得する場合は、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の値は、次のようにアイテムノードを示すリソースパスの末尾に「/title」のように要素名を付けることで、その値だけをXMLデータとして取得することもできます。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

文書や画像データそのものを取得する場合は、リソースパスの末尾に「$value」を付けて表します。応答データは実際のファイル形式によるバイナリデータが返ってきます。

/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回を参照してください。

おすすめ記事

記事・ニュース一覧