このページは Cloud Translation API によって翻訳されました。

Google データガジェットの作成

Google Data API チーム Eric Bidelman
2008 年 10 月

はじめに

対象者

この記事では、Blogger ガジェットを作成する手順について説明します。読者は、Google Data API と JavaScript クライアントライブラリに精通していることを前提としています。また、JavaScript に精通し、ガジェット*を使用して OpenSocial ガジェットを実装した経験が必要です。をご覧ください。

この例では、ガジェットで外部ライブラリを正常に使用する方法を説明します。jQuery（主に UI エフェクト用）と TinyMCE（WYSIWYG のリッチテキストエディタプラグイン）を使用しました。

目的

Google Data API と JSON を使用するガジェットを作成するには、JavaScript をほとんど作成する必要はありません。そのようなツールの大きなわずらわしさは、データが一般公開で読み取り専用であることです。より興味深いガジェットを作成するには、ユーザーの非公開データ（認証が必要なもの）にアクセスする必要があります。これまで、Google Account API の利点を十分に活用することはできませんでした。AuthSub ではブラウザのリダイレクトを必須とし、SafeFrame はクライアント側でユーザーの認証情報を公開します。type="url" ガジェットをハッキングしても不便です。

OAuth プロキシを入力します。

OAuth プロキシ

OAuth に詳しくない場合でも、ユーザーが自分のデータを別のウェブサイトやガジェットと共有できるようにする認証標準です。OAuth 仕様では、すべてのデータリクエストがデジタル署名されている必要があります。これはセキュリティには役立ちますが、JavaScript ガジェットの場合、秘密鍵の管理やデジタル署名の作成は安全ではありません。また、クロスドメインの問題がさらに複雑化しています。

幸いなことに、これらの問題は OAuth プロキシと呼ばれるガジェットプラットフォームの機能を活用することで解決できます。OAuth プロキシは、デベロッパーにとって利便性を高めるように設計されています。OAuth 認証の詳細のほとんどを非表示にし、手間のかかる作業を自動化します。プロキシはガジェットに代わってデータリクエストに署名するため、秘密鍵を管理したり、リクエストに署名したりする必要はありません。問題なくご利用いただけます。

OAuth プロキシは、ガジェット仕様の実装である Shindig というオープンソースプロジェクトに基づいています。

注: OAuth プロキシは、gadgets.* API を利用して OpenSocial コンテナで実行するガジェットでのみサポートされます。以前のガジェット API ではサポートされていません。

スタートガイド

このチュートリアルの残りの部分では、ユーザーの Blogger データにアクセスするためのガジェットの作成に焦点を当てます。認証（OAuth プロキシを使用）して JavaScript クライアントライブラリを使用し、最後に Blogger にエントリを投稿します。

認証

まず、ガジェットで OAuth を使用するように指示します。そのためには、ガジェットの <ModulePrefs> セクションに <OAuth> 要素を追加します。

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" /> 
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?scope=http://www.blogger.com/feeds/" method="GET" /> 
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" /> 
  </Service>
</OAuth>
...
</ModulePrefs>

<Service> 要素内の 3 つの URL エンドポイントは、Google の OAuth トークンエンドポイントに対応しています。クエリパラメータは次のとおりです。

scope
このパラメータはリクエスト URL に必要です。ガジェットでアクセスできるのは、このパラメータで使用されている scope のデータのみです。この例では、ガジェットから Blogger にアクセスします。ガジェットから複数の Google Data API にアクセスする場合は、追加の scope を %20 と連結します。たとえば、カレンダーと Blogger の両方にアクセスする場合は、範囲を http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/ に設定します。
oauth_callback
承認 URL の場合、このパラメータは省略可能です。ユーザーがデータへのアクセスを承認すると、OAuth 承認ページがこの URL にリダイレクトされます。このパラメータを省略することも、独自の「承認済みページ」に設定することも、http://oauth.gmodules.com/gadgets/oauthcallback を使用することもできます。ユーザーが最初にガジェットをインストールしたときに、最良のユーザーエクスペリエンスが提供されます。このページには、ポップアップウィンドウを自動的に閉じる JavaScript スニペットが表示されます。

OAuth を使用するガジェットが作成されたので、ユーザーはデータへのアクセスを承認する必要があります。認証フローは次のとおりです。

ガジェットが初めて読み込まれ、ユーザーの Blogger データへのアクセスが試みられます。
ユーザーがガジェットへのアクセスを許可していないため、リクエストは失敗します。幸い、レスポンスで返されたオブジェクトには、ユーザーをログインに誘導する URL（response.oauthApprovalUrl）が含まれています。ガジェットでは「Blogger にログイン」が表示され、その href が oauthApprovalUrl の値に設定されます。
次に、ユーザーが [Blogger にログイン] をクリックすると、OAuth 承認ページが別のウィンドウで開きます。ガジェットは、ユーザーが「アクセスを承認しました」というリンクを表示して、承認プロセスが終了するまで待機します。
ポップアップで、ユーザーは Google のガジェットへのアクセスを許可または拒否します。[アクセスを許可] をクリックすると、http://oauth.gmodules.com/gadgets/oauthcallback が表示され、ウィンドウが閉じます。
ガジェットはウィンドウを閉じ、ユーザーのデータを再度リクエストして、Blogger へのアクセスをもう一度試みます。ウィンドウの終了を検出するため、ポップアップハンドラを使用しました。このコードを使用しない場合、ユーザーは手動で [アクセスを承認] をクリックできます。
ガジェットで通常の UI が表示されるようになりました。このビューは、IssuedAuthSubTokens の下で認証トークンが取り消されない限り保持されます。

上のステップから、ガジェットには 3 つの異なる状態という概念があります。

未認証。ユーザーが承認プロセスを開始する必要がある。
ユーザーがデータへのアクセスを承認するのを待機しています。
認証済みです。ガジェットは通常の状態で表示されます。

ガジェットで <div> コンテナを使用して各ステージを分離しました。

<Content type="html">
<![CDATA[

<!-- Normal state of the gadget. The user is authenticated -->       
<div id="main" style="display:none">
  <form id="postForm" name="postForm" onsubmit="savePost(this); return false;">
     <div id="messages" style="display: none"></div>
     <div class="selectFeed">Publish to:
       <select id="postFeedUri" name="postFeedUri" disabled="disabled"><option>loading blog list...</option></select>
     </div>
     <h4 style="clear:both">Title</h4>
     <input type="text" id="title" name="title"/>
     <h4>Content</h4>
     <textarea id="content" name="content" style="width:100%;height:200px;"></textarea>
     <h4 style="float:left;">Labels (comma separated)</h4><img src="blogger.png" style="float:right"/>
     <input type="text" id="categories" name="categories"/>
     <p><input type="submit" id="submitButton" value="Save"/> 
     <input type="checkbox" id="draft" name="draft" checked="checked"/> <label for="draft">Draft?</label></p>
  </form>
</div>

<div id="approval" style="display: none">
  <a href="#" id="personalize">Sign in to Blogger</a>
</div>

<div id="waiting" style="display: none">
  <a href="#" id="approvalLink">I've approved access</a>
</di

<!-- An errors section is not necessary but great to have -->
<div id="errors" style="display: none"></div>
 
<!-- Also not necessary, but great for informing users -->     
<div id="loading">
  <h3>Loading...</h3>
  <p><img src="ajax-loader.gif"></p>
</div>

]]> 
</Content>

各 <div> は、showOnly() を使用して単独で表示されます。その関数の詳細については、ガジェットの完全な例をご覧ください。

JavaScript クライアントライブラリを使用する

OpenSocial でリモートコンテンツを取得するには、gadgets.* API を使用して gadgets.io.makeRequest メソッドを呼び出します。ただし、今回は Google Data Gadget をビルドするため、gadgets.io.* API に手を加える必要はありません。代わりに、各 Google Data サービスにリクエストを送信する特別なメソッドを含む JavaScript クライアントライブラリを利用します。

注: この記事の執筆時点では、JavaScript ライブラリは Blogger、カレンダー、連絡先、Finance、Google Base のみをサポートしています。他の API を使用するには、ライブラリなしで gadgets.io.makeRequest を使用します。

ライブラリを読み込む

JavaScript ライブラリを読み込むには、ガジェットが初期化されたら、<Content> セクションに共通ローダーを組み込み、ライブラリをインポートします。gadgets.util.registerOnLoadHandler() にコールバックをフィードすることで、ガジェットの準備ができているかどうかを判断できます。

<Content type="html">
<![CDATA[
  ...
  <script src="https://www.google.com/jsapi"></script>
  <script type="text/javascript">
  var blogger = null;  // make our service object global for later
  
  // Load the JS library and try to fetch data once it's ready
  function initGadget() {  
    google.load('gdata', '1.x', {packages: ['blogger']});  // Save overhead, only load the Blogger service
    google.setOnLoadCallback(function () {
      blogger = new google.gdata.blogger.BloggerService('google-BloggerGadget-v1.0');
      blogger.useOAuth('google');
      fetchData();
    });
  }
  gadgets.util.registerOnLoadHandler(initGadget);
  </script>
  ...
]]> 
</Content>

blogger.useOAuth('google') の呼び出しは、（通常の認証方法である AuthSubJS の代わりに）OAuth プロキシを使用するようライブラリに指示します。最後に、fetchData() を呼び出して、ユーザーの Blogger データを取得します。その方法を以下に示します。

データを取得しています

設定がすべて終わったところで、実際に GET や POST のデータを Blogger に送信するにはどうすればよいですか。

OpenSocial で一般的なパラダイムは、ガジェットで fetchData() という関数を定義することです。通常、このメソッドは認証のさまざまな段階を処理し、gadgets.io.makeRequest を使用してデータを取得します。ここでは JavaScript クライアントライブラリを使用しているため、gadgets.io.makeRequest は blogger.getBlogFeed() の呼び出しに置き換えられます。

function fetchData() {
  jQuery('#errors').hide();
  
  var callback = function(response) {
    if (response.oauthApprovalUrl) {
      // You can set the sign in link directly:
      // jQuery('#personalize').get(0).href = response.oauthApprovalUrl
      
      // OR use the popup.js handler
      var popup = shindig.oauth.popup({
        destination: response.oauthApprovalUrl,
        windowOptions: 'height=600,width=800',
        onOpen: function() {
          showOnly('waiting');
        },
        onClose: function() {
          showOnly('loading');
          fetchData();
        }
      });
      jQuery('#personalize').get(0).onclick = popup.createOpenerOnClick();
      jQuery('#approvalLink').get(0).onclick = popup.createApprovedOnClick();
      
      showOnly('approval');
    } else if (response.feed) {
      showResults(response);
      showOnly('main');
    } else {
      jQuery('#errors').html('Something went wrong').fadeIn();
      showOnly('errors');
    }
  };
  
  blogger.getBlogFeed('http://www.blogger.com/feeds/default/blogs', callback, callback);
}

この関数が 2 回呼び出されると、response.feed にデータが格納されます。

注: getBlogFeed() は、コールバックとエラーハンドラで同じ関数を使用します。

Blogger にエントリを投稿する

最後に、ブログに新しいエントリを投稿します。以下のコードは、ユーザーが [保存] ボタンをクリックするとどうなるかを示しています。

function savePost(form) { 
  jQuery('#messages').fadeOut();
  jQuery('#submitButton').val('Publishing...').attr('disabled', 'disabled');
  
  // trim whitespace from the input tags
  var input = form.categories.value;
  var categories = jQuery.trim(input) != '' ? input.split(',') : [];   
  jQuery.each(categories, function(i, value) {
    var label = jQuery.trim(value);
    categories[i] = {
      scheme: 'http://www.blogger.com/atom/ns#',
      term: label
    };
  });

  // construct the blog post entry
  var newEntry = new google.gdata.blogger.BlogPostEntry({
    title: {
      type: 'text', 
      text: form.title.value
    },
    content: {
      type: 'text', 
      text: form.content.value
    },
    categories: categories
  });
  
  // publish as draft?
  var isDraft = form.draft.checked;
  if (isDraft) {
    newEntry.setControl({draft: {value: google.gdata.Draft.VALUE_YES}});
  }
  
  // callback for insertEntry()
  var handleInsert = function(entryRoot) {
    var entry = entryRoot.entry;
    var str = isDraft ? '(as draft)' : '<a href="' + entry.getHtmlLink().getHref() + '" target="_blankt">View it</a>';

    jQuery('#messages').html('Post published! ' + str).fadeIn();
    jQuery('#submitButton').val('Save').removeAttr('disabled');
  };
  
  // error handler for insertEntry()
  var handleError = function(e) {
    var msg = e.cause ? e.cause.statusText + ': ' : '';
    msg += e.message;
    alert('Error: ' + msg);
  };
  
  blogger.insertEntry(form.postFeedUri.value, newEntry, handleInsert, handleError);
}

まとめ

ここまでで、Google Data API の上にガジェットのコーディングを開始するためのビルディングブロックについて説明しました。

この記事により、OAuth プロキシでガジェット認証がいかにシンプルになったかについてご理解いただけたかと思います。この強力なツールを Google Data JavaScript クライアントライブラリと組み合わせることで、魅力的でインタラクティブかつ洗練されたガジェットを簡単に構築できます。

この記事に関してご不明な点やコメントがございましたら、Google Accounts API のディスカッションフォーラムをご利用ください。

リソース

OAuth ガジェットを作成する（ガジェットの詳細）
Google Data API での OAuth の使用（Google Data API での OAuth の使用に関する記事）
ウェブアプリケーション用の OAuth 認証（OAuth ドキュメント全体）
JavaScript クライアントライブラリ
Google Accounts API のディスカッションフォーラム

Google データ ガジェットの作成