4 月 17 2008
Top / OpenSocial / OpenSocial API仕様 (v0.7)
※このページは本家GoogleのOpenSocial API Specification (v0.7) - OpenSocial - Google Codeページの翻訳です。
概要 †
OpenSocialはウェブ上で動作するソーシャルアプリケーションを構築するためのAPIセットです。OpenSocialは様々なコンテキスト(SNSサイト)上で仕様できる共通のAPIを提供することで、より多くのユーザーにより多くのアプリケーションを利用可能にすることを目的としています。アプリケーション開発者はOpenSocial APIを実装したソーシャルサイトで動作する、標準的なJavaScript?とHTMLを使ってアプリケーションを開発することができます。これらのウェブサイトはOpenSocialコンテナと呼ばれ、開発者に対し、アプリケーションの提供と引き換えに、ソーシャル情報へのアクセスを可能にしています。
OpenSocial APIはコンテナ環境上の人々、その友達、またそれらの詳細情報にアクセスする手段を提供します。例えばOrkut上でアプリケーションを実行するとOrkutの友達と、MySpace?上ではMySpace?の友達とやり取りをすることになります。OpenSocial APIが提供可能な情報についてはキーコンセプトの項でご紹介します。
このドキュメントではOpenSocial JavaScript? APIのコンセプトと原理について記載しています。これはより詳細な情報を記載したJavaScript APIリファレンスの補完資料となります。このドキュメントではAPIの実装方法について詳細には解説いたしません。
コンプライアンス †
OpenSocialコンテナになるとはどういうことでしょうか？分かりやすく言うと、サイトがOpenSocial APIに基づいて構築されたアプリケーションを実行することができる、ということになります。これは意味を持ちます:
- コンテナはJavaScript APIリファレンスのすべてのメソッドを実装していなければならない
コンテナが特定のリクエストをサポートしていない場合、その実装されていないメソッドに対し、エラーコードであるopensocial.ResponseItem?.NOT_IMPLEMENTEDを返します。名前空間OpenSocialには、どんなレベルであれパブリックなメソッドやクラスを実装してはなりません。必要となるメソッドやフィールドは下記のJavaScript?ファイルに定義されます:
activity.js message.js address.js name.js bodytype.js opensocial.js collection.js organization.js datarequest.js person.js dataresponse.js phone.js email.js responseitem.js enum.js url.js environment.js - コンテナは拡張を行う際、指定された拡張方法に従わなければならない
拡張されたPerson、Activity、その他のオブジェクトフィールドは、コンテナの名前空間上のEnumに定義されなければならず、アプリケーションが環境からこれらのフィールドを検知可能にしなければなりません。例えば、orkut.PersonField?.SPECIAL_FIELDフィールドがorkut.specialPersonField?と定義された場合、opensocial.getEnvironment().supportsField("person", "orkut.specialPersonField?")とopensocial.getEnvironment().supportsField(opensocial.Environment.ObjectType?.PERSON, orkut.PersonField?.SPECIAL_FIELD)の両方が真(true)を返さなければなりません。
拡張されたデータリクエスト型はmyspace.newFetchAlbumRequest?のように、名前空間に収められた呼び出し方法を取らなければなりません。その後、ガジェットはbatchRequest.add(myspace.newFetchAlbumRequest?(...))を使用します。
拡張されたオブジェクトをコンテナ独自の名前空間に追加することができます。これらのオブジェクトはperson.getFieldまたは類似するリクエストから取得することができます。
- コンテナはガジェットAPI仕様に準拠しなければならない
これはガジェットレンダリングリクエスト、ガジェットメタデータリクエスト、JavaScript?リクエストの、3種類のリクエストを扱えることを意味します。
JavaScript? APIについては、ドキュメントに従ってgadgets core JavaScript? APIを実装しなければなりません。
背景 †
この項ではOpenSocial APIのコンセプトと原理について紹介します。なお、この項は情報のみであり、コンプライアンスは前項とAPIリファレンスにのみ基づきます。
キーコンセプト †
ソーシャルアプリケーションは人々とその関係を巡ります。OpenSocialはウェブサイトのソーシャルグラフやそれに類する情報の標準的な開示方法を提供します。他の人のアクティビティを見ることで友達の近況を知り、経歴やビデオに至るまで、ソーシャルグラフ上に広めて行くことができます。OpenSocialはまた、見え方だけでなく、アプリケーションのデータをサイト上に保存することをも可能にします。
People †
ソーシャルグラフは人々によって成り立っています。People(人々)はソーシャルネットワークソフトウェアおよびOpenSocial APIの基本です。Personオブジェクトはユーザーの情報へのアクセスを提供します。この情報の一部はユーザーのプロフィールにあり、サイトによっては「好きなテレビ番組」や「寝室のもの5つ」といったユニークなものがあるかもしれません。もう一つの重要なユーザー情報として、ソーシャルグラフに構築されたコネクションが挙げられますが、これについてはRelationshipsの項で取り上げます。
ダイレクトにリクエスト可能なPersonオブジェクトが2つあります - VIEWER(閲覧者)とOWNER(所有者)です。Orkutで同僚のプロフィールを閲覧しているところを想像してみてください。この場合、あなたはVIEWERであり、同僚はOWNERとなります。
自分のプロフィールを自分で見る場合もあると思います。この場合、あなたはVIEWERであり、OWNERになります。アプリケーションによってはこの場合、通常と異なる動作をするかもしれません。OpenSocialはまた、ガジェットがVIEWERの情報にアクセスできない、匿名による閲覧のケースも想定されています。
Personクラスの詳細についてはAPIリファレンスをご覧ください。
ユーザーIDに関する注意事項 †
Personオブジェクトで常に返される情報としてユーザーIDが挙げられます。ユーザーIDは英数字(A-Za-z0-9)かつ、コンテナ上のユーザーをユニークに指定できるものでなければなりません。これはユーザーIDにドメイン名とセパレータを付記するだけで、グローバルにユニークなIDを構成するために標準化されているものです(例: "orkut.com:34KJDCSKJN2HHF0DW20394")。ユーザーIDのサイズにはデータベース管理上の理由から、上限があることに注意してください。
Relationships †
人間関係が構築可能であるということは、マルチユーザーアプリケーションをソーシャルソフトウェアにすることができる、ということです。友達との情報の共有や、やり取りによってユーザーエクスペリエンスの形態は変化してきます - 開発者はソフトウェアではなく、人を扱うことになるのです。
ダイレクトにリクエスト可能なPersonオブジェクトが2つあります - VIEWER_FRIEND(閲覧者の友達)とOWNER_FRIENDS(所有者の友達)です。同僚のプロフィールを閲覧している場合、VIEWER_FRIENDSはあなたの友達を意味し、OWNER_FRIENDSは同僚の友達を意味します。理論的には、あなたが自分のプロフィールを閲覧している場合、VIEWER_FRIENDSとOWNER_FRIENDSは同じユーザーということになります。コンテナが匿名でのプロフィール閲覧をサポートしている場合、アプリケーションはVIEWER_FRIENDSにアクセスすることはできません。
OpenSocialではVIEWERとOWNERの関係について何の想定も行いません。VIEWERとOWNERは友達かもしれませんが、全くの他人のプロフィールを見た場合、VIEWERであるあなたと、OWNERである他人の間には何の関係もありません。
Activities †
ユーザーは常にオンラインであることはできませんから、友達が望む場合に限り、友達が何をしたかの履歴を残すことが何かの役に立つ場合があります。例えば、他の人がどのようにソーシャルアプリケーションを使っているかを見ることで、新しい機能やアプリケーションの使い方を知ることができます。アクティビティストリームはアプリケーションの有機的成長を担う重要な要素の一つと言えます。
OpenSocialはコンテナ上で行われたユーザーの行動履歴となるアクティビティストリームを提供します。これらの行動履歴は、プロフィールの更新や新しいガジェットの追加といったコンテナ自体とのやりとりだけでなく、友達にバーチャルギフトを贈ったり、ゲームでハイスコアを更新した、といったOpenSocialアプリケーションを使ったアクションも含みます。
行動履歴テンプレート(Activity templates)を使うことで、開発者はアプリケーションやユーザーの情報を載せるプレースホルダ付きのメッセージを定義することができます。このようなデータと表現の分離により、複数の行動履歴を行動履歴サマリ(activity summaries)にまとめることができます - これにより、ユーザーは大量のメッセージに煩わされることなく、友達の近況を知ることができます。
Activityクラスの詳細についてはAPIリファレンスをご覧ください。
Persistence †
アプリケーションがセッション間の状態を保存できれば、よりリッチなユーザーエクスペリエンスを提供することができます。OpenSocialではユーザーごとのデータ読み込み、書き込みが可能な、データ保存機能を定義しています。このデータ保存機能はガジェットが閲覧可能であれば誰でも閲覧できますが、閲覧者の閲覧可能なデータ(VIEWER's user-scoped data)のみが保存可能です。
当然、こういった無料のデータ保存機能はいたずらされやすいため、コンテナはquotaを実装したり、ディスク領域を制限する場合があります。しかし、OpenSocialでは現在のところ、本件についてのポリシーは定義していません。
開発者がこのデータをインデックスするために指定できるキー値に利用できる文字は、英数字(A-Za-z0-9)、アンダーバー(_)、ドット(.)、ハイフン(-)のいずれかです。
アプリケーションデータがユーザーからの入力により生成される場合が多いことを考慮し、OpenSocialコンテナはすべてのアプリケーションデータについて、自動的にHTMLエスケープを行います。詳細についてはOpenSocial 開発者向けガイドのPersistenceの項をご覧ください。
注意: OpenSocial APIのバージョン0.7では、グローバルデータとインスタンスデータを排することで、Persistance APIをシンプルにしています。アプリケーションごとのインスタンスデータはユーザーごとの保存領域に基づいて実装することができ、グローバルデータは開発者による制御の元、外部サーバーからJSONまたはATOMフィードとして取得することで実装することができます。
ビュー †
コンテナはガジェットを表示する場所を複数サポートすることができます。ここで言う場所は、公式にはビューと呼ばれます(以前の仕様ではサーフィスと呼んでいました)。すべてのガジェット(OpenSocialアプリケーション以外も含む)はビューを意識します。ガジェットはコンテナがサポートするビューと、現在どのビュー上で表示されているかを問い合わせることができます。
コンテナは異なる特徴と機能を持ったビューを定義することができます。例えば:
- プロフィール(Profile)
- プロフィール上のガジェットはユーザーのプロフィールに表示されるため小さく、コンテナからガジェットにURLパラメータを渡すことはできません。
- キャンバス(Canvas)
- キャンバスビューでは、ガジェットはそれのみ表示されるため、画面上の多くの領域を確保でき、コンテナページに渡されたURLパラメータをガジェットに渡すこともできます。
ガジェットは現在のビューを問い合わせるリクエストに加え、ユーザーを別のビューに誘導するようリクエストを出すこともできます。普段はプロフィールビューで小さく表示され、ヘッドラインをクリックすることで、キャンバスビューに移動して詳細を表示するニュースガジェットをイメージしてみてください。ガジェットはコンテキストに応じて表示方法を変更できるようになったのです。
APIのパターン †
この項ではOpenSocial APIにおけるいくつかの共通パターンについて記載しています。これらのコンセプトを理解することで、APIリファレンスの閲覧が楽になることと思います。
リクエストを行う †
OpenSocial APIではコンテナへのほとんどの呼び出しを非同期に行いますが、OpenSocialメソッドが直接データを返さないのはそのためで、応答が返ると同時に実行されるコールバック関数を指定することができます。もちろん、たくさんの非同期リクエストを同時に行うことは理想的とは言えませんが、OpenSocial APIでは一度に大量の情報を取得するためのバッチリクエスト機能を提供しています。開発者はopensocial.DataRequest?を生成し、サーバー個別のリクエストオブジェクトを追加することができます。DataRequest?の取得と同時に、コンテナは各処理を最適な状態で処理し、各処理の結果をバッチ応答オブジェクト(batched result object)として返すことができます。ただし、コンテナはリクエスト処理の順番を守らなければなりません。書き込み、その後読み込むようなリクエストの場合は、新しく書き込まれたデータを返し、読み込み、その後書き込むようなクエリの場合は、書き込まれる前のデータを返さなければなりません。
機能の自動検知 †
ガジェットとOpenSocialの仕様ではすべてのコンテナがサポートしなければならない共通のAPIを規定していますが、コンテナによっては特定のメソッドやプロフィールフィールドが拡張として提供される場合があります。開発者にこれらの拡張を生かしたガジェットを書いてもらったり、その機能がないための対応をしてもらうため、APIにはgadgets.util.hasFeatureやopensocial.Environment.supportsFieldといった、動作時にコンテナに問い合わせ、機能が利用可能かを判断するためのメソッドが存在します。
もちろん、OpenSocialではこの機能が実装されているべきであるというコンプライアンスルールが存在しています。
アクションのリクエストと許可 †
ガジェットがユーザーによる認証や、コンテナによる仲介を必要とする動作を行たい場合があります。OpenSocialではコンテナがユーザーとのやり取りをどのように取り扱うかを決定することができる「リクエスト」機能をサポートしています。opensocial.requestCreateActivity?やopensocial.requestPermissionといった関数で、コンテナは独自のポリシーをガジェットの実行フローに差し込んだり、結果をガジェットに伝えることができます。この仕様では、ユーザーに委ねる、常に許可する、常に拒否する、または他の手段を使って決定することができます。加えて、コンテナはUIのフローを安全で統一された方法に誘導することができます。
プロフィールフィールド †
ユーザープロフィールはコンテナによって異なります。コンシューマ向けサービスのコンテナでは、完璧な初デートのアイディアを取得したいアプリケーションがあるかもしれませんが、ビジネス向けサービスのコンテナでは適切とは言えません。そのためOpenSocialでは、コンテナサイトごとのフィールや利用方法に応じて、Personオブジェクトを任意に拡張することを許可しています。プロフィールイールドはそのため、プロパティごとに取得者と設定者をハードコーディングするのではなく、Person.getFieldを呼び出すことで取得することができます。コンテナがどのように拡張APIを追加し、アプリケーションがどうやって利用可能なフィールドを判断するかについては、コンプライアンスの項と機能の自動検知の項を参照してください。
外部サーバーからコンテンツを取得する †
ガジェットはgadgets.io.makeRequestメソッドを使ってHTML、JSON、ATOM形式のデータを外部サーバーから取得することができます。
gadgets.io.makeRequsetを使うことで、ガジェットからアプリケーションサーバーになりすましされることなくデータを渡すことができます。コンテナはガジェットからアプリケーションサーバー(例: ilike.com)への通信を仲介することが期待されています。そのため、信頼できるコンテンツ取得フローには2つのステップがあります: [1] ガジェットがコンテナにコンタクトを取る。 [2] コンテナがアプリケーションサーバーにコンタクトを取る。
ステップ1(ガジェットからコンテナ)では、コンテナは閲覧者ID(viewer id)、所有者ID(ownder id)、アプリケーションIDの、すべてのパラメータについて正当性を確認できなければなりません。これらのパラメータの正当性確認の実装方法はコンテナによって異なる場合があります。例えば、OrkutではガジェットURLの一部に暗号化されたトークンを使っています。
ステップ2(コンテナからアプリケーションサーバー)では、アプリケーションサーバーはパラメータが本当にコンテナから渡されたものなのか(かつ、他から捏造されたものではないか)を確認しなければなりません。OpenSocialではOAuthのパラメータ署名アルゴリズムを使用します。OAuth仕様に規定された、トークン交換を含むほとんどの機能は使用する必要はありません; OpenSocialでは、仕様のパラメータ署名部分(タイムスタンプとノンスも含む)のみを利用します。OpenSocialではHMAC-SHA1メソッド(鍵がOAuth仕様の9.2に規定されたトークンを連結したものではなく、コンテナとアプリケーションで共有された秘密鍵であるという点を除く)とRSA-SHA1メソッドを許可しています。HMAC-SHA1の方が処理も速く簡単に実装できますが、RSA-SHA1よりも調整が必要となります。
APIリファレンスを利用する †
JavaScript? APIリファレンスはOpenSocialで必要とされるメソッドとフィールドの完全なリストですが、理解しにくい部分もあるかと思います。この項ではAPIリファレンスを作成する際に用いられた想定について説明します。
仮想型 †
JavaScript?は型の強い言語ではありませんが、このAPIでは開発しやすいように、JavaScript?の型が強いものであるかのように定義されています。ドキュメント上でパラメータや戻り値が特定の型として定義されている場合は、この型がOpenSocialの互換上提供される、もしくは受け付けられる唯一の型として示されています。このルールに当てはまらないものについては、リファレンスに直接記載してあります。
例えば、getErrorCode?メソッドはopensocial.ResponseItem?.Error型の値を返すものとしてJavaScript? APIリファレンスに定義されていますが、実際は通常のJavaScript?文字列に過ぎません。しかしOpenSocial準拠のコンテナでは、戻り値の文字列がopensocial.ResponseItem?.Errorフィールドのひとつであると断言することができます。
OpenSocial APIではEnumerationsが頻繁に登場します。開発者はenumを参照したり、enumの値を直接利用することが許されています。拡張に関わる衝突を避けるため、コンテナはenumの名前と値が仕様に定義されたものと一致し、カスタム値は適切に名前空間に収められすることを保証しなければなりません。例えばOrkutのMY_PERSON_FIELDというカスタム値はOrkut.PersonField?.MY_PERSON_FIELDという名前で、値はOrkut.myPersonField?とすることができます。詳細はコンプライアンスの項と機能の自動検知の項を参照してください。
パラメータのマッピング †
OpenSocialメソッドの多くはたくさんのオプション値を取ります。JavaScript?が強い型を持たないため、オーバーロードが困難になるだけでなく、関数がパラメータをたくさん持つ場合(特に開発者がIDEを使っていない場合)に至っては、その管理すら難しくなります。OpenSocialではオプションパラメータに対し「オブジェクトバッグ」、パラメータ名と値の組み合わせのマッピングから成るopt_paramsパラメータを取る、というアプローチを利用しています。
仕様で規定されているopt_paramsマッピングを利用している各メソッドでは、すべての正当なフィールドがコンテナによって読み込まれます。これらのフィールドは仮想型の項で説明した通り、予め定義された型を持っています。開発者が不正な値をフィールドに追加した場合、コンテナはエラーコードBAD_REQUESTを返さなければ成りません。
