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

第19回Windows Live Photo API(1)

本記事の対象APIは既にサポートされていません。記事は参考程度にご利用ください。

今回からはWindows Live スペースのフォト アルバムを操作できるWindows Live Photo APIについてです。

Windows Live スペース フォト アルバム

ブログサービスであるWindows Live スペースとその機能のひとつフォト アルバムをご存知でしょうか。フォト アルバムは、写真などの画像ファイルをアルバムとして分類し、Webサイト上にアップロードして公開できるサービスです図1⁠。

図1 フォト アルバム
図1 フォト アルバム

通常は、ユーザーはアルバムの作成や写真のアップロードをWebサイトまたはWindows Live フォト ギャラリーから行いますが、Windows Live SDKにはフォト アルバムをプログラムから操作できるAPIが提供されています。今回からは、そのAPIを使ってみましょう。

Windows Live Photo API

フォト アルバムを操作できるAPIはWindows Live Photo APIと呼ばれ、使用するプロトコルの違いにより

  • Windows Live Photo WebDAV API
  • Windows Live Photo ATOM API

の2種類があります。

API利用によって次の操作が可能です。

  • 写真のアップロードおよびダウンロード
  • アルバムの作成
  • 写真またはアルバムの名前変更および削除

Live Photo APIは、Windows Live ID委任認証と併せて利用します。つまり、フォト アルバムを操作するためにあらかじめユーザーの承認を得る必要があります。委任認証については本連載の第14回15回に紹介しています。

以上のことからAPI利用によりWindows Liveユーザーのブログスペースをフォトストレージとして使用したり、ブログスペースからフォトを参照・利用するなどのWebアプリケーションの作成が可能であることがわかります。

WebDAV API、ATOM APIともCTP(Community Technology Preview)リリースです。今後、仕様が変わる可能性がありますので利用には注意してください。

アクセス許可

ここからは委任認証を理解しているものとして進めます。委任認証ではアプリケーションプロバイダ(通常はWebサイト)が必要とするアクセス許可(オファーとアクション)を指定し、ユーザーの承認を得る必要があります。今回のPhoto APIではフォト アルバムに対しての操作のオファーおよびアクションを指定します。

Photo APIで使用するオファーとアクションの組み合わせは次の2種類です。

オファー・アクション 説明
SpacesPhotos.Read アルバムと写真に対する読み取り専用でのアクセス許可
SpacesPhotos.ReadWrite アルバムと写真に対する読み取りおよび追加・変更のアクセス許可

必要とするオファー・アクションを承認要求URL、psパラメータに指定しましょう。コンマ(,)区切りで両方を指定することも可能です。ユーザーがアクセスする承認要求ページは図2のようになります。

図2 承認要求ページ
図2 承認要求ページ

図は2種類のオファーとアクションを指定した場合です。

フォト アルバムへのアクセス

本連載はAtom Publishing(AtomPub)プロトコルに基づいたWindows Live Photo ATOM APIの利用方法を紹介します。AtomPubプロトコルはHTTPによるXMLをベースとしたWeb APIによく使用される仕様です。以前のLive Photo API ⁠以前はWindows Live Spaces Photo APIと呼ばれていました)は、WebDAVプロトコルのみでしたがCTPリリースからAtomPubによる操作が可能になりました。

フォト アルバムを操作するには、次の書式に従ったURLへアクセスし、HTTPのGETやPOSTメソッドによりアルバム・写真情報の取得やアップロードを行います。

https://cumulus.services.live.com/@C@[LID]/AtomSpacesPhotos[/リソースへのパス]

[LID]にはユーザーデータの場所を示す識別子、委任認証により取得した承認トークンのlidパラメータを指定します。URLの末尾にはリソースへのパス、つまりアルバムや写真を示す値を指定します。

上記URLへアクセスするときに、HTTPのAuthorizationヘッダを指定する必要があります。ヘッダの値に承認トークンのdeltパラメータの値(委任トークン)を使います。

以上をまとめると、フォト アルバムへアクセスするHTTPのリクエストヘッダは次のようになります。

[HTTP Method] /AtomSpacesPhotos[/リソースへのパス] HTTP/1.1
Host: cumulus.services.live.com
User-Agent: [Name of User Agent]
Authorization: DelegatedToken dt="[委任トークン]"

フォト アルバムの構造

アルバムやフォトにアクセスする際のURLに指定するリソースのパスについてまず理解しましょう[1]⁠。そのためにはフォト アルバムの構造およびパスの書式を知る必要があります。また、Live サービスからどのような形式の応答があるかも理解する必要があります。

最初にフォト アルバムのストレージの構造とリソースパスの関係をみてみましょう。

ユーザーからみたアルバムとフォト

アルバムとフォトの関係を図3に示します。

図3 アルバムとフォトの関係
図3 アルバムとフォトの関係

実際にサービスを利用しているとわかるように、アルバムはその中に複数のフォトを持つことができ、フォトはひとつのアルバムに属しています。アルバムの中にアルバムを作成したり、アルバムに属さないフォトを作成したりすることはできません。ただし、フォトのないアルバムを作ることは可能です。

また、アルバム、フォトにはそれぞれユーザーが命名した名前が付いています(図中では「旅行⁠⁠、⁠ペット」など⁠⁠。

リソースの種類とパスの記述

APIで使用するリソースのパス指定では、ひとつのアルバムやフォトを表すパス指定のほかに、アルバムのリストやアルバムに属するフォトのリストなどコレクションを表すパスの記述も可能です。

リソースパスではアルバムはフォルダ(Folders)として表記されています。あるユーザーのアルバムすべてを表すリソースパスは次のようになります。

/Folders

それぞれのアルバムは名前とは別に番号により管理されています。たとえば、あるひとつアルバムは次のように記述します。

/Folders(123)

ひとつのアルバム内のフォトすべてを表すパスは次にようになります。

/Folders(123)/Photos

フォトも番号で管理されています。アルバム内のひとつのフォトのリソースパスは以下のようになります。

/Folders(123)/Photos(456)

以上を先ほどの図で説明すると図4のようになります。

図4 フォト アルバムの構造とリソースパス
図4 フォト アルバムの構造とリソースパス

フォトのタイプ

ユーザーからみたフォトはひとつでも、実際にはWeb用の画像やサムネイル用など異なったタイプの画像データとして保存されています。APIではこれらを区別してアクセスが可能です。リソースパスの指定では「ImageStreams」を使い表します。

あるフォトのすべてのタイプを表すコレクションは、

/Folders(123)/Photos(456)/ImageStreams

と記述し、その中のひとつの形式は次のように書きます。

/Folders(123)/Photos(456)/ImageStreams(1)

アルバムやフォトと同様に番号で管理されています。アルバムやフォトに付けられる番号はWindows Liveサービスにより自動で割り振られた、あるユーザーにとって一意であること以外は意味のないものですが、ImageStreamsの番号はその画像データのタイプを示しています。タイプには次の表のものがあります。

番号 タイプ
1 WebReady(Web用)
2 Thumbnail(サムネイル)
3 HighRes(高解像度)
4 MobileReady(モバイル用)
5 FullScreen
6 MiniPhoto
7 Other

通常、サービスを利用しているとフォトのアップロード時に、Web用、サムネイル、モバイル用のデータが作成されるようです。プリント用のフォトを追加した場合は、高解像度データも保存されています。

ユーザーからみた場合、アルバムーフォトのみの階層構造ですが、実際には図5に示すような構造になっています。

図5 フォトタイプを含めたフォト アルバムの構造とリソースパス
図5 フォトタイプを含めたフォト アルバムの構造とリソースパス

バイナリデータ

ここまでに示したフォト単体を示すリソースパスの記述はユーザーがアップロードした画像バイナリデータそのものを表すものではありません。⁠Folders(13)/Photos(456)」のように記述したパスは、フォトの名前や画像形式(JPEGやPNGなど)などの情報を含むメタデータへのパスとなります。

データそのものを表すパスは、⁠/$value」をパスの末尾に付けて記述します。

/Folders(123)/Photos(456)/ImageStreams(1)/$value

次のように記述も可能です。この場合は、ImageStreams(1)/$valueを指定したときと同じWeb用の画像を示すパスとなります。

/Folders(123)/Photos(456)/$value

当然ながら実データがない、アルバム一覧(/Folders)やフォト一覧(/Folders(n)/Photos⁠⁠、アルバム単体(/Folders(n))に$valueを使用することはできません。


今回はここまでです。アルバムやフォトにアクセスするときのリソースパスについて理解いただけたでしょうか。次回は今回の内容に続いてLive サービスからの応答形式を理解し、実際にコードを記述しながら、フォト情報の取得やバイナリデータの取得を行う予定です。

おすすめ記事

記事・ニュース一覧