天使やカイザーと呼ばれて

OpenSocial Hackathonは6月にも行います！

5月15日に行われたmixi&OpenSocial-Japan主催OpenSocial Hackathonは、とても高いレベルの成果を参加者の方々がもたらしてくれました。その熱もまだまだ冷めないうちに、OpenSocial Hackathonを6月にも行います！
今回はGoogle Developer Day 2009 Japanの一環として、各APIごとにHackathonが行われます。もちろん、OpenSocial Hackathonもその仲間の一つです。昨年のように、GDDと同じ日ではないので、GDDに参加される方も、そうでない方も、Hackathonに参加することができます。既にGDDの登録受け付けは終了していますが、Hackathonの応募はまだまだ受付中です。
Googlerも、API Expertも、当日は参加された方々のサポートを全力で行いますので、奮ってご応募ください！
========================================
【OpenSocial Hackathon in GDD 2009 Japan】
OpenSocialアプリケーションを開発するHackathonです。
対象: OpenSocialアプリケーションを開発し、公開する予定のある方。
条件: OpenSocialのチュートリアルを終えていること。gooホーム Sandboxや
mixi Platformなど、いずれかのSNSの開発環境に登録していること。
人数: 先着30名様
事前ミーティング: 2009年6月3日 19:00-21:00
Hackathon: 2009年6月11日 10:00-18:00
※ 原則としてHackathon参加者は、事前ミーティングにも参加いただきます。
========================================
応募フォームは下記のURLです。
http://spreadsheets.google.com/viewform?formkey=cnNGZEh0UjVfNkdkY25fRmx2eDJRekE6MA
OpenSocial Hackathonで皆さまとお会いできるのを楽しみにしております。

Posted:

05.27.2009

Category:

OpenSocial

mixi主催OpenSocial Hackathonのレポート

5月15日に行った「mixi&OpenSocial-Japan主催OpenSocial Hackathon」のレポートを、mixi engineer blogに掲載しました！
[mixi主催OpenSocial Hackathonが開催されました!] – mixi engineer blog
http://alpha.mixi.co.jp/blog/?p=895

Posted:

05.27.2009

Category:

OpenSocial

Content Upload Support (0.9)

OpenSocial v0.9で追加になった「Content Upload Support」仕様について紹介します。OpenSocialアプリケーションでは、画像や動画などが良く使われますし、Album APIも追加になったので、このアップロードの仕様追加は比較的重要なものかと思います。

—

[Content Upload Support]

Content Upload Supportは、OpenSocialコンテナに対して、JSON/XML/AtomPub RESTfulやJSON-RPCを使った呼び出しを通じてファイルをアップロードすることを可能にします。このメカニズムは、以下のような局面で使用することができます: (もちろん他の用途も考えられます)

• ユーザのプロフィール/サムネイル画像のアップロード
• アップロードされたメディアアイテムコンテンツを持つアクティビティストリームエントリの作成
• ユーザのアルバムに含めるための、コンテナに対して音声/動画/画像といったコンテンツのアップロード

背景:

v0.8.1までの(Activity, Person, AppDataなどの)リソースの取得、更新、作成、または削除のためのOpenSocialコンテナへのRESTful呼び出しは、標準的なHTTPメソッド(GET, PUT, POST, DELETE)を使って行われます。特に、PUTやPOSTはリソースを作成あるいは更新するために使われます。HTTPリクエストのPOST Body部には、リソースを作成あるいは更新するためのJSON/XML/AtomPubリクエストが含まれます。しかしながら、OpenSocialにおいて、コンテンツをアップロードすることを可能とする標準的なメカニズムはありませんでした。

OpenSocialコンテナへのJSON/XML-RPC呼び出しにおいて、POST Body部はリクエストのコンテンツを運びます([Appendix B]を参照)。JSON-RPCまたはXML-RPCサービスによるコンテンツアップロードを可能とする標準的なメカニズムは存在していません。

OpenSocialコンテナへのコンテンツのアップロードを可能とすることが必要なことは明白です。本仕様は、ユーザにプロフィール写真をアップロードすることや、アクティビティストリームにメディアアイテムを追加することや、彼らのオンラインアルバムに写真を追加することを可能とするでしょう。

解説:

RESTful呼び出しを使ったアップロード:

レギュラーアップロード:

RESTfulは各リソースの作成、更新、取得や削除のためのエンドポイントを提供します。これらの考えと同じ連鎖に従うとすると、新しく関連づけられるリソースの作成は、含まれるエンティティのURLへのリソースのコンテンツをポストすることによって行われるでしょう。そのレスポンスは、IDや他の関連づけられる属性を含みます。(これはRFC 5023 Section 9.6に似ています)。コンテンツをアップロードするためには、Content-Typeヘッダはアップロードされるファイルの種別を指定しなければなりませんし、それらがエンティティのアップロードのリクエストとして扱われるようにするために、application/xml、application/atom+xmlやapplication/jsonとしてはいけないことに注意してください。その”Accept-Type”ヘッダは、期待するレスポンスの書式を示すために使われます。

ショートカットアップロード:

ショートカットメカニズムも、コンテナエンティティにおいて、新しいコンテナエンティティの作成の2つのステップのプロセスを簡単に避けることを可能とし、コンテンツをアップロードできる提案です。各REST仕様として、コンテナエンティティはatom/xml/json属性を持つ特定のURLの新しいPOSTによって生成されます。そのURLパラメータ(オプション)におけるその属性を持つURLへのPOSTや、POST Bodyにおけるコンテンツのアップロードは、エンティティを作成し関連づけられたアップロードをするためのショートカットメソッドになるでしょう。このためのContent-Typeは、アップロードされているコンテントタイプのセットとなることに注意してください。

[Appendix A]は、レギュラーアップロードとショートカットアップロードの例を示します。

JSON/XML-RPCを使ったアップロード:

JSON/XML-RPCの既存のメカニズムにおいて、POST HTTPリクエストは、POST Body内の要求オペレーションの詳細として置かれます。このメカニズムは、サポートされ続けるでしょう。加えて、マルチパートフォームデータリクエストメカニズム(“Content-Type: multipart/form-data”)は、コンテンツのアップロードを可能とするでしょう。そのようなリクエストは、名前によって識別される各フィールドを伴ういくつかのセクション(fields)によって分割されたPOST Bodyを持ちます。そのフィールド名”request”は予約されていて、要求する処理の詳細を含んでいます(普通のPOSTオペレーションにおけるPOST Bodyのコンテンツと同じ)。

これをイメージするための良い例が、[Appendix B]として提供されます。

レスポンス:

アップロードが成功したら、そのリクエストに対するレスポンスコードは、リソースのアクション要求のレスポンスコードとして関連づけられるでしょう。しかしながら、ファイルサイズの制限違反のために失敗した場合、413(“Request Entity Too Large”)のエラーコードが返されるべきです。そのファイルアップロードに関連づけられてリクエストされたアクションはまた、実行されないでしょう。

Appendix A: REST

このセクションでは、アルバム内にメディアアイテムを作成することを依頼する例を使います。アルバムのための仕様はここです: http://docs.google.com/Doc?id=dpbz5zc_5gdbp3dgd。本質的に、その例はコンテナにコンテンツをアップロードするための2つの方式(レギュラー、ショートカット)で記述します。

レギュラーアップロード:

ほとんどのシナリオにおいて、アップデートされたコンテンツは、エンティティの作成と関連があります。エンティティの作成は、日常的にコンテンツのアップロードから生じます。例えば、新しいメディアアイテムの作成のリクエストは、写真のアップロードの手順を生みます。そのリクエストはこのようなものです:

Step 1: イメージのプレースホルダーとなるメディアアイテムを作成する。
Step 2: 写真をアップロードする。

その2つのステップのリクエストは、以下のような内容となります。

Step 1: POSTリクエストによるアルバム(id:112233)へメディアアイテム(イメージのプレースホルダー)を作成する

リクエスト

<br /> POST /album/112233/mediaitem/ HTTP/1.1<br /> <usual headers><br /> Content-Type: application/atom+xml<br /> Content-Length: length<br /> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:osapi="http://opensocial.org/2008/opensocialapi"><br /> <content type="application/xml"><br /> <mediaitem xmlns="http://ns.opensocial.org/2008/opensocial"></p> <caption>Lena</caption> <p><media_type>IMAGE</media_type><br /> </mediaitem><br /> </content><br /> <title /><br /> <updated>2008-10-24T20:30:40.500Z</updated><br /> <author /><br /> </entry><br />

レスポンス

<br /> <feed xmlns="http://www.w3.org/2005/Atom" xmlos:ossearch="http://a9.com/-/spec/opensearch/1.1"><br /> <author><uri>urn:guid:example.org:33445577722</uri></author></p> <link rel="next" href="http://api.example.org/..." /> <ossearch:totalResults>100</ossearch:totalResults><br /> <ossearch:startIndex>1</ossearch:startIndex><br /> <ossearch:itemsPerPage>10</ossearch:itemsPerPage><br /> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:osapi="http://opensocial.org/2008/opensocialapi"><br /> <content type="application/xml"><br /> <mediaitem xmlns="http://ns.opensocial.org/2008/opensocial"><br /> <id>223344</id></p> <caption>Lena</caption> <p><media_type>IMAGE</media_type><br /> </mediaitem><br /> </content><br /> <title /><br /> <updated>2008-10-24T20:30:40.500Z</updated><br /> <author /><br /> </entry><br /> </feed><br />

そのレスポンスはメディアアイテムが作成され、メディアアイテムのIDが223344であることを示しています。

Step 2: メディアアイテムプレースホルダーの中にイメージをアップロードする

リクエスト

<br /> POST /album/112233/mediaitem/223344 HTTP/1.1<br /> <usual headers><br /> Accept-Type: application/xml<br /> Content-Type: image/gif<br /> Content-Length: length<br /> GIF89a….<binary data><br /> <textarea name="code" class="xml" cols="80" rows="5"></p> <p>レスポンス</p> <p><textarea name="code" class="xml" cols="80" rows="5"><br /> <response><br /> <startIndex> 1 </startindex><br /> <itemsPerPage> 1 </itemsPerPage><br /> <totalResults> 1 </totalResults><br /> <entry> … </entry><br /> </response><br />

アップロードメソッドのショートカット

上記で示したこの2つのステップのプロセスは、アップロードするアイテムにセットするコンテントタイプを伴う単一のPOSTリクエストによって一つにマージすることが可能です。そのPOST URLは、オプション的に属性を渡すことができます。そのAccept-typeは、期待されるレスポンスの書式を指定します。

リクエスト

<br /> POST /album/112233/mediaitem/?caption=Lena&media_type=IMAGE HTTP/1.1<br /> <usual headers><br /> Accept-Type: application/json<br /> Content-Type: image/gif<br /> Content-Length: length<br /> GIF89a….<binary data><br />

レスポンス

<br /> {<br /> “startIndex” : 1,<br /> “itemsPerPage” : 1,<br /> “totalResults” : 1,<br /> “entry” : {<br /> “id” : “223344″,<br /> “caption” : “Lena”,<br /> “media_type” : “IMAGE”,<br /> }<br /> }<br />

Appendix B: RPC

このセクションでは、JSON/RPCリクエストを使ってメディアアイテムを伴うアクティビティを作成するための例を示します。XMLリクエストもこれに類似しています。

既存のRPCメカニズム

メディアアイテムを伴うアクティビティの作成のための既存のJSON/RPCリクエストは、このようになるでしょう:
(URLパラメータは外部サーバにホストされたコンテンツへポイントしていることに注意してください)

<br /> POST /social/rpc?st=<security token> HTTP/1.1<br /> <usual headers><br /> Content-Type: application/json<br /> [{<br /> "method":"activities.create",<br /> "params": {<br /> "userId":["@viewer"],<br /> “groupId”:”@self”,<br /> “appId”:”@app”,<br /> “activity”: {<br /> “title”: “hello world!”,<br /> “mediaItems”: [ {<br /> "mimeType":"image",<br /> "url":"http://robotics.eecs.berkeley.edu/~sastry/ee20/images/lena.gif"<br /> } ]<br /> }<br /> },<br /> “id”:”key”<br /> }]<br />

アップロードを伴うRPC

コンテンツアップロードを伴うリクエストも先のリクエストと似ていて、以下のようになります:
(現在のURLパラメータは”@field:image1″ですので注意してください。また、フィールドが”request”や”image1″であることも注意ください。)

<br /> <usual headers><br /> Content-type: multipart/form-data; boundary=————abcdef012345xyZ<br /> Content-length: <contentLength><br /> ————abcdef012345xyZ<br /> Content-Disposition: form-data; name=”request”<br /> [{<br /> "method":"activities.create",<br /> "params": {<br /> "userId":["@viewer"],<br /> “groupId”:”@self”,<br /> “appId”:”@app”,<br /> “activity”: {<br /> “title”: “hello world!”,<br /> “mediaItems”: [ {<br /> "mimeType":"image",<br /> "url":"@field:image1"<br /> } ]<br /> }<br /> },<br /> “id”:”key”<br /> }]<br /> ————abcdef012345xyZ<br /> Content-Disposition: form-data; name=”image1″<br /> GIF89….<image data><br /> ————abcdef012345xyZ<br />

Posted:

05.15.2009

Category:

OpenSocial

Content Rewriter Feature (0.9)

OpenSocial v0.9からちゃんと規定された「Content Rewriter Feature」について紹介します。実は多くのSNSで、v0.8.1から使えていた機能です。

—

[Content Rewriter Feature]

OpenSocialでは、ユーザからの細かく、しかも多量なリクエストを効率よく捌くために、OpenSocialコンテナによって積極的にキャッシュが行われます。ただし、OpenSocialアプリケーションによっては、何でもかんでもキャッシュされては困ることも十分考えられます。Content Rewriter Featureは、OpenSocialアプリケーションがキャッシュの振る舞いを制御できるようにするための機能となります。

Conent Rewriter Featureは、開発されたガジェットのコンテンツをRewriteする機構のサポートの追加であり、新しい標準的なオプショナルガジェットFeature「content-rewrite」を導入することで、開発者にRewriterの振る舞いをどうするかを制御させることができます。content-rewrite featureは、コンテナがコンテンツのレンダリングおよびプロキシ時に行うことができるRewriteのオペレーションのセットであり、コンテンツがRewriteされる際のルールを定義します。

つまり、content-rewrite featureによって記述されたルールに基づいて、コンテナが積極的に外部リソースのキャッシュを行うように指定することもできるし、その逆も可能ということです。

定義:

Rewriter featureは、一般的なフォームを持ちます。

<br /> <Optional feature="content-rewrite"><br /> <Param name="expires">86400</Param><br /> <Param name="include-url"></Param><br /> <Param name="exclude-url">excluded</Param><br /> <Param name="exclude-url">moreexcluded</Param><br /> <Param name="minify-css">true</Param><br /> <Param name="minify-js">true</Param><br /> <Param name="minify-html">true</Param><br /> </Optional><br />

各パラメータは以下のように定義されています。

• expires – RewriteされたURLを経由してプロキシから取得されたコンテンツの最小HTTPキャッシュ時間として効果するための時間(秒)です。初期値は、86400です。
• include-url – 大文字小文字を区別する文字列としてこのパラメータ値を含む任意のURLは、Rewriteすることが考慮されます。リテラル文字列”*”は、全てのURLを意味する特別なケースです。もし値を伴うこのエントリが指定されなかった場合は、”*”が指定されたとみなします。このパラメータは繰り返し書くことができます。
• exclude-url – 大文字小文字を区別する文字列としてこのパラメータ値を含む任意のURLは、Rewriteすることから除外されます。リテラル文字列”*”は、全てのURLを意味し、全てのRewriteを無効にします。このパラメータは繰り返し書くことができます。
• minify-css – コンテナがstyleタグや参照されているcssファイルの中のcssを最小化することを試みるかどうか制御します。有効な値は”true”または”false”です。初期値は”true”です。
• minify-js – コンテナがstyleタグや参照されているJSファイルの中のJSを最小化することを試みるかどうか制御します。有効な値は”true”または”false”です。初期値は”true”です。
• minify-html – コンテナがHTMLコンテンツを最小化することを試みるかどうか制御します。有効な値は”true”または”false”です。初期値は”true”です。

“exclude-url”によるマッチングは、”include-url”によるマッチングよりも優先されます。

全てのURLを意味する”*”の特別な使用は、文字列のGLOBまたはRegExマッチングによるサポートとして解釈されるべきではないことに注意してください。

コンテナは、以下を含むリンクをRewriteする際に追加の最適化を行うことは自由であり、制限されません:

• styleタグから@importディレクティブを展開し、それらをHTMLコンテンツに含まれるheadタグの中のlinkタグとして変換すること。
• 独立したURLからフェッチされたコンテンツをProxyによってまとめるために、連続したlinkタグから一つのlinkタグへ複数のCSSをマージすること。
• 連続した<script src=xxx>タグをProxyがフェッチすることで一つにまとめたものとしてマージすること。

例:

gifイメージのみのRewrite:

<br /> <Optional feature="content-rewrite"><br /> <Param name="include-url">.gif</Param><br /> </Optional><br />

“animated”や”cdn”を含まないgifイメージのみのRewrite:

<br /> <Optional feature="content-rewrite"><br /> <Param name="include-url">.gif</Param><br /> <Param name="exclude-url">animated</Param><br /> <Param name="exclude-url">cdn</Param><br /> </Optional><br />

全てのRewriteの無効化:

<br /> <Optional feature="content-rewrite"><br /> <Param name="exclude-url">*</Param><br /> </Optional><br />

Posted:

05.14.2009

Category:

OpenSocial

Clarify timing of callback execution in JS API (0.9)

OpenSocial v0.9にて追加となった「Clarify timing of callback execution in JS API」仕様について紹介します。コールバック関数の呼び出しに関する規定についてですが、このようなちょっとしたことでも、OpenSocialアプリケーション開発者にとっては非常に重要です。
—
[Clarify timing of callback execution in JS API]
今までのOpenSocial APIでは、コールバック関数が呼び出されるタイミングについて、実装がはっきりしないという問題がありました。
例えば、requestPermission(permissions, reason, opt_callback)関数のケースを考えてみましょう。この関数の実装をサポートしないコンテナは、’not implemented’という結果でopt_callback関数を同期的に呼び出します。一方、この関数を解決するためにXHRを使って実装が行われる場合、そのコールバック関数は非同期的に呼び出されるでしょう。これは、コールバック関数の実行のタイミングにおいて、ガジェットはコンテナの実装依存を気にしなければならないことを意味しています。全てのコールバック関数の呼び出しが非同期的に行われることを保証することで、開発者はクロスコンテナでの振る舞いの違いを意識する必要がなくなるでしょう。
本仕様では、コールバック関数の呼び出しを伴う全てのAPIについて、以下の文章を追加することで、コールバック関数が非同期的に呼び出されることを保証します。
The callback function will not be called until after the existing callstack has completed execution.
(このコールバック関数は、既存のコールスタックが完全に実行された後までは呼び出されることはないでしょう。)
本仕様に関しては、window.setTimeout(, 0); を使うことで、手間をかけることなく達成することができるでしょう。

Posted:

05.12.2009

Category:

OpenSocial

Anonymous Viewer (0.9)

OpenSocial v0.9において追加された仕様「Anonymous Viewer」について紹介しましょう。この仕様は、Viewerが特定されない、あるいはViewerの情報を取得する権限がない場合に、OpenSocialアプリケーションがViewer情報をどのように得るべきか、を示したものです。もちろんコンテナによっては、Viewer情報を取得しようとした際に、この仕様の内容ではなく、エラーを返す場合もあります。
—
[Anonymous Viewer]
OpenSocialでは、従来から匿名のViewerをサポートしていました。しかし、特に匿名のViewerのPerson IDについて、標準的なレスポンスはありませんでした。コンテナは匿名ユーザのIDをコンテナ自身の表記で実装していました。
アプリケーションが匿名ユーザであることを知ることや区別することが重要であるとする時に、異なるコンテナにおいて、様々なレスポンスをハンドルする必要があります。もし仕様としてこのレスポンスが標準化されれば、クロスコンテナアプリケーション開発は容易になり、異なるコンテナでの様々な振る舞いを学び、知る必要がなくなります。
標準的なレスポンスのために、いくかの可能性があります。以下はいくつかのコンテナでそのような表記法として既に実装されていたものを考慮した提案です。
匿名のViewerに対するレスポンスを標準化するために:

• コンテナは匿名のViewerのIDとして(-1)を返さなければなりません。
• コンテナはユーザフレンドリーな説明としてNAMEやNICKNAMEを返すことを選択するかもしれません（例: Guest、Anonymous、Unauthenticatedなど）。これはDisplayNameが空になるのを防ぎます。
• コンテナはまた、匿名ユーザのための標準的な代理画像へのポイントをTHUMBNAIL_URLとして返すかもしれません。

という振る舞いをコンテナは実装します。

Posted:

05.11.2009

Category:

OpenSocial

Align Portable Contacts and REST (0.9)

OpenSocial v0.9において追加された仕様「Align Portable Contacts and REST」について紹介しましょう。この仕様は、OpenSocialとPortable Contactsの互換性について語られたものです。
—
[Align Portable Contacts and REST]
Portable Contactsは、アドレス帳やフレンドリストなどにアクセスするための安全な方法をユーザに提供することを開発者が容易に行えるように、とデザインされた仕様です。特に、いかなるサイトで提供可能な、共通のアクセスパターンやコンタクトスキーマ、よく知られた認証やアクセスルール、いかなるサイトでも対応可能な標準ライブラリ、そして絶対的な最小複雑性などを、最も軽量な形で可能とするツールチェインを開発者に要求する形でもたらします。
OpenSocial v0.9では、Portable Contacts仕様とOpenSocial RESTful API仕様において、それらの互換性を確立するための調整が行われました。本仕様追加において、RESTful APIに以下の章が追加されます。これと同時に、Portable Contacts仕様側でも、OpenSocialとの互換性に関する記述が追加されています。
—
Compatibility with Portable Contacts
This version of the OpenSocial RESTful protocol specification is currently wire-compatible with the Portable Contacts version 1.0 overlapping portion of OpenSocial. Specifically, any compliant OpenSocial 0.9 People Provider is also a compliante Portable Contacts 1.0 Provider, because they are specified to use the same Authorization methods (OAuth), Additional Path Information, Query Parameters, and Contact Schema. The OpenSocial and Portable Contacts communities chose to wire-align our respective specs in order to maximize widespread adoption of a single API for accessing people data. It is our intention to maintain this compatibility going forward, so long as it is feasible, and so long as the changes required are compatible with the Goals and Approach of this spec. Although Portable Contacts is an independent spec, with a more limited scope than OpenSocial, any proposed changes to either this OpenSocial RESTful Protocol spec or the Portable Contacts spec should be considered in the context of both communities, and we should strive not to break compatibility unless it is truly necessary, e.g. if the goals of the two communities diverge significantly in the future.
—
Portale Contactsとの互換性
OpenSocial RESTful protocol仕様のこのバージョンでは、現在OpenSocialの一部分をオーバーラッピングする形でPortable Contacts version 1.0と硬い互換性があります。特に、いかなるOpenSocial 0.9に準拠したPeople Providerは、Portable Contacts 1.o Providerにもなり得ます。なぜなら、それらは同じ認証メソッド(OAuth)、追加パス情報、クエリパラメータ、そしてコンタクトスキーマを使うように指定されているからです。OpenSocialとPortable Contactsコミュニティは、Peopleデータにアクセスするための単一のAPIが最大限の広さで採用されるために、私たちのそれぞれの仕様を硬く調整することを選択しました。それは、将来的にこれらの仕様をとても長く実現可能にし、そしてこの仕様のゴールやアプローチについて要求される変更を互換とするための、この互換性を維持していくことについての我々の意志です。Portable Contactsは独立した仕様であり、OpenSocialよりもより限定されたスコープではありますが、このOpenSocial RESTful Protocol仕様やPortable Contacts仕様のどちらにいかなる変更の提案がされたとしても、両方のコミュニティにおけるコンテキストにおいて考慮されるべきであり、そして我々は、例えば将来有意に2つのコミュニティのゴールがそれぞれ枝分かれするなどのことが真に必要とされるまでは、互換性が壊されないように努力すべきです。
—
Portable Contacts仕様との互換性を図るために調整された結果のXML Schema文書は、「Resolve schema with Portable Contacts」という別の仕様にて定義されます。

Posted:

05.11.2009

Category:

OpenSocial

Align JS API and REST (0.9)

OpenSocial v0.9において追加された仕様「Align JS API and REST」について紹介しましょう。
—
[Align JS API and REST]
OpenSocial JavaScript APIでは、会員情報を表すためのいくつかのクラスが規定されています。その中で、住所を表すクラスとして、opensocial.Addressクラスがあります。Addressクラスには、緯度経度を表すフィールドや、住所の種別（自宅、勤務先など）のフィールドが定義されています。
opensocial.Address.Field.LATITUDE – 緯度(number型)
opensocial.Address.Field.LONGITUDE – 経度(number型)
opensocial.Address.Field.TYPE – 種別(string型)
JavaScript APIで規定されているフィールドは、基本的にRESTful APIやJSON-RPC APIにおいても同様に定義されている必要があります。しかし、v0.8.1でのRESTful APIには、上記3つのフィールドが規定されていませんでした。v0.8.1にてJavaScript APIは、Portable Contactsへの準拠に伴って調整されましたが、v0.9では本仕様において、上記3つのフィールドを追加します。
REST Specification: 更新内容
11.1.4 address element
追加:
* LATITUDE
* LONGITUDE
* TYPE
これにより、v0.9ではRESTful APIにおいても、住所に関して緯度経度や種別を扱えるようになります。

Posted:

05.10.2009

Category:

OpenSocial

懐かしいデモ

僕の原点とも言えるデモンストレーション。

小学校の時に何度これを実行したことか。。。

Posted:

05.09.2009

Category:

Etc

Album support (0.9)

OpenSocial v0.9から追加になったAlbum APIについて、そのドラフトから日本語訳を起こしてみました。

—

[Album support in OpenSocial]

OpenSocial v0.9では、複数のMediaItem（写真、動画、そして音声クリップ）により構成されるAlbumをサポートするための機能が追加されました。これは「Albums API」と呼ばれています。この仕様には、JavaScript API、RESTful API、そしてJSON-RPC APIのそれぞれに対して定義が行われました。

Albums APIでは、以下の操作が規定されています。

• Albumの作成、更新、削除
• あるAlbumへのMediaItemの追加、更新、削除

■ JavaScript API

Albumサポートは、新しく追加されたopensocial.Albumクラスによって提供されます。Albumは、本質的に、複数のMediaItem（イメージ、動画、音声トラック）の集合です。あるAlbumに対して、opensocial.Album.getField()関数やopensocial.Album.setField()関数を呼び出すことで、各フィールドにアクセスすることが可能です。それらのフィールドは、opensocial.Album.Fieldクラスに定数として定義されています。string型のIDフィールドは、Albumを特定するための文字列であり、必須項目です。その他に、オプションとして以下のフィールドが定義されています。

THUMBNAIL_URL – string型です。Albumのカバー画像のURLです。
CAPTION – string型です。Albumのタイトル文字列です。
DESCRIPTION – string型です。Albumの説明文です。
LOCATION – opensocial.Address型です。Albumに対応する位置情報です。
OWNER_ID – string型です。Albumの所有者のIDです。
MEDIA_TYPE – MediaItem.TYPEの配列です。Album内のMediaItem群の種別です。
MEDIA_ITEM_COUNT – integer型です。Album内のアイテム数です。

あるAlbumは、opensocial.MediaItemクラスのオブジェクトを複数保持することができます。このクラスは従来から提供されていましたが、opensocial.MediaItem.Fieldに定義されるフィールドがいくつか追加されています。string型のIDフィールドは、MediaItemを特定するための文字列であり、必須項目です。その他に、オプションとして以下のフィールドが定義されています。

CAPTION – string型です。MediaItemの説明文です。
CREATED – string型です。MediaItemの作成日時です。UTCでコンテナにより与えられます。
LAST_UPDATED – string型です。MediaItemの更新日時です。UTCでコンテナにより与えられます。
THUMBNAIL_URL – string型です。MediaItemのサムネイル画像のURLです。
DESCRIPTION – string型です。MediaItemの説明文です。
DURATION – integer型です。音声または動画クリップのためのフィールドであり、再生時間の長さを秒で示します。もし長さが不明の場合は、-1がセットされます。
LOCATION – opensocial.Address型です。MediaItemに関連づけられた位置情報です。
LANGUAGE – string型です。ISO 639-3フォーマットで表現される、MediaItemに関連づけられた言語情報です。
ALBUM_ID – string型です。MediaItemが所属するAlbumです。
FILE_SIZE – long型です。バイト数を示します（もしバイト数が不明の場合は-1がセットされます）。
START_TIME – string型です。ストリームまたはライブコンテンツのためのフィールドであり、コンテンツが利用可能な時間を表します。
RATING – integer型です。0〜10のスケールで表現される、MediaItemの平均レートです。
NUM_VOTES – integer型です。投票を受けた投票数です。
NUM_COMMENTS – integer型です。写真へのコメント数です。
NUM_VIEWS – integer型です。MediaItemの閲覧数です。

以下のフィールドも引き続き存在します。

TYPE – MediaItem.TYPE型です。MediaItemの種別です（AUDIO/VIDEO/IMAGE）。
MIME_TYPE – string型です。MediaItemのmime-typeです。
URL – string型です。MediaItemのURLです。

AlbumおよびMediaItemは、以下の関数で生成されます。

opensocial.newAlbum() – opensocial.Albumオブジェクトを生成します。
opensocial.newMediaItem() – opensocial.MediaItemオブジェクトを生成します。

■■ APIs

AlbumやMediaItemを扱うためのAPIは、DataRequestクラスに追加されています。

—

opensocial.DataRequest.newFetchAlbumsRequest(idSpec, opt_params)

newFetchAlbumsRequest()関数は、複数のAlbum情報を要求するためのDataRequestオブジェクトを生成します。opt_params引数には、以下の情報を指定することが可能です。

opensocial.Album.Field.ID – 取得するAlbumのIDの配列です。もし無指定の場合は全てのAlbumの取得要求になりますが、ページングのために結果数は限定されます。
opensocial.Album.Field.MEDIA_TYPE – 取得するAlbumの種別を指定するためのMediaItem.TYPE値の配列です。

—

opensocial.DataRequest.newFetchMediaItemsRequest(idSpec, albumId, opt_params)

newFetchMediaItemsRequest()関数を使うことで、Album内のMediaItemのリストを取得することができます。opt_params引数には、以下の情報を指定することが可能です。

opensocial.MediaItem.Field.ID – 取得するMediaItemのIDの配列です。もし無指定の場合は全てのMediaItemの取得要求になりますが、ページングのために結果数は限定されます。
opensocial.MediaItem.Field.MEDIA_TYPE – 取得するMediaItemの種別を指定するためのMediaItem.TYPE値の配列です。

FilterやFIRST、MAXを使ったテクニックは、FetchAlbumsやFetchMediaItemsにおいて、ページングのために利用することができます。

—

opensocial.DataRequest.newCreateAlbumRequest(idSpec, album)

新しいAlbumを作成し、結果として作られたAlbumのIDを返します。コンテナは、ViewerがViewer自身のためのみAlbumを作成することが許可される、といった制限を実装します。

—

opensocial.DataRequest.newCreateMediaItemRequest(idSpec, albumId, mediaItem)

新しいMediaItemをAlbum内に作成し、作られたAlbumのIDを返します。コンテナは（newCreateAlbumRequest()関数のような）制限を実装します。

—

opensocial.DataRequest.newUpdateAlbumRequest(idSpec, albumId, fields)

パラメータで指定された項目を更新します。結果はvoidです。以下の項目はセットできません: MEDIA_ITEM_COUNT、OWNER_ID、ID。コンテナは（newCreateAlbumRequest()関数のような）制限を実装します。

—

opensocial.DataRequest.newUpdateMediaItemRequest(idSpec, albumId, mediaItemId, fields)

パラメータで指定された項目を更新します。結果はvoidです。以下の項目はセットできません: ID、CREATED、ALBUM_ID、FILE_SIZE、NUM_COMMENTS。コンテナは（newCreateAlbumRequest()関数のような）制限を実装します。

—

opensocial.DataRequest.newDeleteAlbumRequest(idSpec, albumId)

指定されたAlbumを削除します。結果はvoidです。コンテナは（newCreateAlbumRequest()関数のような）制限を実装します。

—

opensocial.DataRequest.newDeleteMediaItemRequest(idSpec, albumId, mediaItemId)

指定されたAlbumに含まれるMediaItemを削除します。結果はvoidです。コンテナは（newCreateAlbumRequest()関数のような）制限を実装します。

■■ Examples

■■■ ユーザのAlbumの取得

<br /> function requestAlbums() {<br /> var idspec_params = {};<br /> idspec_params[opensocial.IdSpec.Field.USER_ID] = opensocial.IdSpec.Field.PersonId.OWNER;<br /> var idspec = opensocial.newIdSpec(idspec_params);<br /> var params = {};<br /> req = new opensocial.newDataRequest();<br /> req.add(req.newFetchAlbumsRequest(idspec, params), ‘albums’);<br /> req.send(onLoadAlbums);<br /> }<br /> /* list albums items */<br /> function onLoadAlbums(dataResponse) {<br /> var html = ‘List of albums: <ul>‘;<br /> var albums = dataResponse.get(‘albums’).getData();<br /> albums.each(function(album) {<br /> html += ‘ <li>‘ + album.getField(opensocial.Album.Field.CAPTION) + ‘</li> <p>‘;<br /> });<br /> html += ‘</ul> <p>‘;<br /> document.getElementById(‘album_container’).innerHTML = html;<br /> };<br />

■■■ Album内のMediaItemの取得

<br /> function listMediaItems(album) {<br /> var albumId = album.getField(opensocial.Album.ID);<br /> var idspec_params = {};<br /> idspec_params[opensocial.IdSpec.Field.USER_ID] = opensocial.IdSpec.Field.PersonId.OWNER;<br /> var idspec = opensocial.newIdSpec(idspec_params);<br /> var req = new opensocial.newDataRequest();<br /> var params = {};<br /> req.add(req.newFetchMediaItemsRequest(idspec, albumId, params), ‘mediaitems’);<br /> req.send(onLoadMediaItems);<br /> }<br /> /** list mediaitem details */<br /> function onLoadMediaItems(dataResponse) {<br /> var html = ‘List of MediaItems: <ul>‘;<br /> var mediaitems = dataResponse.get(‘mediaitems’).getData();<br /> mediaitems.each(function(mediaitem) {<br /> html += ‘ <li>‘ + mediaitem.getField(opensocial.MediaItem.Field.CAPTION);<br /> html += ‘<img src="' + mediaitem.getField(opensocial.MediaItem.Field.THUMBNAIL_URL + '" /></li> <p>‘;<br /> });<br /> html += ‘</ul> <p>‘;<br /> document.getElementById(‘mediaitem_container’).innetHTML = html;<br /> };<br />

■ RESTful API

新しい”album”サービスは、AlbumやMediaItemの要求をハンドルするために追加されました。そのサービスは、ディスカバリXML文書内のエントリを通じて発見されます。

<br /> <Service><br /> <Type>http://ns.opensocial.org/album/0.x</Type><br /> <os:URI-Template>http://api.example.org/album/{userId}/{groupId}/{optionalAlbumId}/mediaitem/{optionalMediaItemId}</os:URI-Template><br /> </Service><br />

userId: ユーザID
groupId:
@self: ユーザ(ユーザID)のAlbum
@friends, @all、またはグループID: ユーザのグループ内の全ての人々が所有するAlbum [これのサポートはオプションです]
optionalAlbumId: 特定のAlbumを参照するためのAlbum ID
optionalMediaItemId: Album内の特定のMediaItemを参照するためのMediaItem ID

操作:
GET /album/@me/@self は、Albumの配列を取得します
POST /album/@me/@self は、新しいAlbumを作成します
GET /album/@me/@self/albumId は、特定のAlbumのみを返します
PUT /album/@me/@self/albumId は、Albumを更新します
DELETE /album/@me/@self/albumId は、Albumを削除します

GET /album/@me/@self/albumId/mediaitem は、Album内のMediaItemを返します
POST /album/@me/@self/albumId/mediaitem は、新しいMediaItemの作成に使われます
GET /album/@me/@self/slbumId/mediaitem/mediaItemId は、MediaItemを返します
PUT /album/@me/@self/slbumId/mediaitem/mediaItemId は、MediaItemを更新します
DELETE /album/@me/@self/slbumId/mediaitem/mediaItemId は、MediaItemを削除します

■■ Examples

IDが44332211のAlbumを得るための GET /album/@me/@self/44332211 は、以下をもたらします。

<br /> {<br /> “id” : “44332211″,<br /> “thumbnail_url” : “http://pages.example.org/albums/4433221-tn.png”,<br /> “caption” : “Example Album”,<br /> “description” : “This is an example album, and this text is an example description”,<br /> “location” : { “latitude”: 0, “longitude”: 0 },<br /> “owner_id” : “example.org:55443322″<br /> }<br />

IDが11223344のMediaItemを得るための GET /album/@me/@self/44332211/mediaitem/11223344 は、以下をもたらします。

<br /> {<br /> “id” : “11223344″,<br /> “thumbnail_url” : “http://pages.example.org/images/11223344-tn.png”,<br /> “mime_type” : “image/png”,<br /> “type” : “image”,<br /> “url” : “http://pages.example.org/images/11223344.png”,<br /> “album_id” : “44332211″<br /> }<br />

■ RPC API

以下のメソッドは、Albumをサポートします:
album.get、album.update、album.create、そしてalbum.delete
mediaitem.get、mediaitem.update、mediaitem.create、そしてmediaitem.delete

以下の例は、album.* の操作のためのものですが、mediaitem.* に関しても流儀は同じです。userid（@me）やgroupid（@self）の初期値は、指定されなかった場合に適用されます。

■■ album.get

リクエスト

<br /> {<br /> “method” : “album.get”,<br /> “id” : “get_all_albums”,<br /> “params” : {<br /> “userid” : “@me”,,<br /> “groupid” : “@self”,<br /> “id” : [ ],<br /> }<br /> }<br />

レスポンス

<br /> {<br /> “id” : “get_all_albums”,<br /> “result” : {<br /> “totalResults” : 1,<br /> “startIndex” : 0,<br /> “itemsPerPage” : 20,<br /> “list” : [<br /> {<br /> "userid" : "@me",<br /> "groupid" : "@self",<br /> "id" : "5544331",<br /> "thumbnail_url" : "http://pages.example.org/albums/4433221-tn.png",<br /> "caption" : "Example Album",<br /> "description" : "This is an example album, and this text is an example description",<br /> "location" : { "latitude": 0, "longitude": 0 },<br /> "owner_id" : "example.org:55443322"<br /> },<br /> {..},<br /> {..},<br /> ]<br /> }<br /> }<br />

■■ album.update

Albumを更新するためのリクエストは、更新されたAlbumの情報を指定します。もし成功した場合は、空の結果を返します。

リクエスト

<br /> {<br /> “method” : “album.update”,<br /> “id” : “my_update_album_request”,<br /> “params” : {<br /> “userid” : “@me”,<br /> “groupid” : “@self”,<br /> “id” : “5544331″,<br /> “fields” : {<br /> “caption” : “my holiday pictures”<br /> }<br /> }<br /> }<br />

レスポンス

<br /> {<br /> “id” : “my_update_album_request”,<br /> “result” : {<br /> }<br /> }<br />

■■ album.create

Owner IDおよびAlbum IDは指定されるべきではありません。Owner IDやAlbum IDは自動的に割り当てられます。Album IDが結果として返却されます。

リクエスト

<br /> {<br /> “method” : “album.create”,<br /> “id” : “my_album_create_request”,<br /> “params”: {<br /> “userid” : “@me”,<br /> “groupid” : “@self”,<br /> “album” : {<br /> “thumbnail_url” : “http://pages.example.org/albums/4433221-tn.png”,<br /> “caption” : “Example Album”,<br /> “description” : “This is an example album, and this text is an example description”,<br /> “location” : { “latitude”: 0, “longitude”: 0 },<br /> }<br /> }<br /> }<br />

レスポンス

<br /> {<br /> “id” : “my_album_create_request”,<br /> “result” : {<br /> “id” : “445544577″<br /> }<br /> }<br />

■■ album.delete

削除のリクエストは、Albumを特定するためにAlbum IDを要求します。正常に完了した際には、空の結果が返されます。

リクエスト

<br /> {<br /> “method” : “album.delete”,<br /> “id” : “my_delete_request”,<br /> “params” : {<br /> “id” : “445544577″<br /> }<br /> }<br />

レスポンス

<br /> {<br /> “id” : “my_delete_request”,<br /> “result” : {<br /> }<br /> }<br />

Posted:

05.08.2009

Category:

OpenSocial