ホーム‎ > ‎私の開発環境‎ > ‎

Google Sites API Python Language Guide (v1.4)

http://d.hatena.ne.jp/kaorumori/20110703/1309690973

Google Sites Data APIは、クライアントアプリケーションからGoogle Siteのコンテンツにアクセスして公開し、修正することができます。クライアントアプリケーションは最近の活動状況や更新履歴を取得したり、添付ファイルをダウンロードすることもできます。

Sites Data APIの機能の背景に加えて、このガイドはPythonクライアントライブラリの利用例も提供します。クライアントライブラリのセットアップには、Getting Started with the Google Data Python Client Libraryを参照してください。もしSites APIと連携するPythonクライアントライブラリで利用されている基本的なプロトコルをさらに理解することに興味がありましたら、プロトコルガイドを参照してください。

対象読者

このドキュメントはGoogle GDataのPythonクライアントライブラリを利用して、Google Sitesと連携するクライアントアプリケーションを作成したい開発者に向けたものです。

はじめよう

Pythonクライアントライブラリを利用するためには、Python 2.2以上とWikiページのDependencyModulesにリストされたモジュールが必要です。クライアントライブラリをダウンロードしたら、インストールと利用のためにGetting Started with the Google Data Python Libraryを参照してください。

サンプルの実行

動作する完全なサンプルはプロジェクトのMercurialリポジトリのサブディレクトリのsamples/sitesにあります(/samples/sites/sites_example.py)。

以下のように実行します：

python sites_example.py
# or
python sites_example.py --site [sitename] --domain [domain or "site"] --debug [prints debug info if set]

もし必要な項目が入力されなければ、アプリケーションはそれらの値を入力するプロンプトを表示します。このサンプルによってユーザが多数の操作を実行するために、Sites APIをどのように利用するかを示しています。例えば、特定の操作(例：コンテンツの編集)のためには、認証が必要となります。プログラムはAuthSubやOAuthまたはClientLoginを利用した認証のプロンプトも表示します。

このガイドの例をあなた自身のコードに組み込む際は、以下のimport文が必要になります。

import atom.data
import gdata.sites.client
import gdata.sites.data

Site APIへのクライアント接続を示すSiteClientオブジェクトのセットアップも必要になります。サイトのアプリケーション名とウェブスペース名を(そのURLから)渡します。

client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName')

Google Appsでホストされたドメインのサイトで動作させるためには、domainパラメータを利用してドメインを指定します。

client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName', domain='example.com')

この部分でsource引数はオプションですが、ログのために推奨されています。以下のようなフォーマットにするとよいでしょう：company-applicationname-version

Note: 以下のガイドではSiteClientオブジェクトはclientという変数で作成されているものとします。

Sites APIへの認証

Pythonクライアントライブラリは公開と非公開のフィードの両方で動作させることができます。Sites Data APIはサイトの権限と実行しようとする操作に応じて、非公開・公開のフィードへのアクセスを提供します。例えば、公開サイトのコンテンツフィードを読むことはできますが、更新することはできず、認証されたクライアントが要求されます。これはClientLoginのユーザ名/パスワードの認証やAuthSubかOAuthで実行されます。

AuthSubやOAuth、ClientLoginについての詳細な情報はGoogle Data APIs Authentication Overviewを参照してください。

WebアプリケーションのためのAuthSub

WebアプリケーションのためのAuthSub認証は、GoogleやGoogle Appsアカウントの認証が必要となるクライアントアプリケーションで利用されます。操作実行者はGoogle Sitesのユーザ名とパスワードにアクセスする必要はなく、AuthSubトークンのみが要求されます。

Webやインストール/モバイルアプリケションのためのOAuth

OAuthはAuthSubの代替として利用され、Webアプリケーション向きのものです。OAuthは安全な登録モードのAuthSubと似ていて、すべてのデータリクエストは電子的に署名され、ドメインに登録しなければなりません。

インストール/モバイルアプリケーションのためのClientLogin

ClientLoginはGoogleアカウント認証が必要なインストールまたはモバイルアプリケーションで利用するとよいでしょう。最初に実行した際、アプリケーションはユーザにユーザ名とパスワードの入力を求めます。その後のリクエストでは、認証トークンが参照されます。

翻訳者注：認証の具体的なコードは原文を参照してください。

サイトフィード

サイトフィードはユーザが所有していたり閲覧権限のあるGoogle Sitesをリストすることができます。既存のサイトの名称を変更することもできます。Google Appsドメインでは、サイト全体を作成したりコピーすることもできます。

サイトのリスト

ユーザがアクセスできるサイトをリストするためには、clientのGetSiteFeed()メソッドを使います。このメソッドはオプションの引数のuriを取り、サイトフィードのURLを指定することができます。デフォルトでは、GetSiteFeed()はclientオブジェクトのサイト名とドメインのセットを利用します。clientオブジェクトへのこれらの値の設定についての詳細な情報は、はじめようの節を参照してください。

以下は認証されたユーザのサイトリストを取得する例です。

feed = client.GetSiteFeed()

for entry in feed.entry:
  print '%s (%s)' % (entry.title.text, entry.site_name.text)
  if entry.summary.text:
    print 'description: ' + entry.summary.text
  if entry.FindSourceLink():
    print 'this site was copied from site: ' + entry.FindSourceLink()
  print 'acl feed: %s\n' % entry.FindAclLink()
  print 'theme: ' + entry.theme.text

ここではサイトのタイトルとサイト名、サイトのコピー元、そしてACLフィードのURLを出力しています。

新規サイトの作成
Note: この機能はGoogle Appsドメインでのみ有効です。

新規サイトはライブラリのCreateSite()メソッドを呼び出すことで作成されます。GetSiteFeed()と同様に、CreateSite()はオプションの引数のuriを取り、サイトフィードURLを指定することができます（SiteClientオブジェクトに設定されたのとは異なるドメインでサイトを新規作成する場合）。

以下の例は'slate'テーマでタイトルと（オプションの）説明を指定してサイトを作成しています。

client.domain = 'example2.com'  # demonstrates creating a site under a different domain.

entry = client.CreateSite('Title For My Site', description='Site to hold precious memories', theme='slate')
print 'Site created! View it at: ' + entry.GetAlternateLink().href

このリクエストではGoogle Appsドメインのexample2.com以下に新しいサイトが作成されます。この場合、サイトのURLは https://sites.google.com/a/example2.com/title-for-my-site のようになります。

サイトの作成が成功したら、サイトへのリンク、サイトのACLフィードへのリンク、サイト名、タイトル、サマリーなどの要素を追加して、gdata.sites.data.SiteEntryオブジェクトを返します。

サイトのコピー
Note: この機能はGoogle Appsドメインでのみ有効です。

CreateSite()は既存のサイトのコピーにも利用されます。これをするためには、キーワード引数のsource_siteを渡します。コピーされたすべてのサイトはentry.FindSourceLink()でアクセス可能なリンクを持ちます。以下は新規サイトの作成の節で作成したサイトを複製する例です。

copied_site = client.CreateSite('Copy of Title For My Site', description='My Copy', source_site=entry.FindSourceLink())
print 'Site copied! View it at: ' + copied_site.GetAlternateLink().href

重要な点：

  • 認証されたユーザが所有するサイトとサイトテンプレートのみがコピー可能です。
  • サイトテンプレートもコピー可能です。サイトはGoogle Sitesの設定ページで"Publish this site as a template"にチェックした場合にテンプレートとなります。
  • 元のサイトのオーナーとしてリストされていれば、別のドメインのサイトからもコピーすることができます。
サイトメタデータの更新

サイトのタイトルやサマリーを更新するためには、サイトのSiteEntryが必要になります。この例ではGetEntry()を使って最初にSiteEntryを取得し、そのタイトルと説明とカテゴリータグを更新しています。

uri = 'https://sites.google.com/feeds/site/example2.com/title-for-my-site'
site_entry = client.GetEntry(uri, desired_class=gdata.sites.data.SiteEntry)

site_entry.title.text = 'Better Title'
site_entry.summary.text = 'Better Description'
category_name = 'My Category'
category = atom.data.Category(
    scheme=gdata.sites.data.TAG_KIND_TERM,
    term=category_name)
site_entry.category.append(category)
updated_site_entry = client.Update(site_entry)

# To force the update, even if you do not have the latest changes to the entry:
# updated_site_entry = client.Update(site_entry, force=True)

アクティビティフィードの取得

Note: このフィードにアクセスするためには、サイトのオーナーか共同編集者である必要があります。クライアントはAuthSubかOAuthかClientLoginのトークンで認証されていなければなりません。 Authenticating to the Sites serviceを参照してください。

アクティビティフィードを取得することによって、サイトの最近の活動(変更)を取得することができます。ライブラリのGetActivityFeed()メソッドが、このフィードへのアクセスを提供します。

print "Fetching activity feed of '%s'...\n" % client.site feed = client.GetActivityFeed() for entry in feed.entry: print '%s [%s on %s]' % (entry.title.text, entry.Kind(), entry.updated.text)

GetActivityFeed()を呼び出すと、gdata.sites.data.ActivityEntryのリストを含むgdata.sites.data.ActivityFeedオブジェクトが返されます。それぞれの活動のエントリは、サイト上で変更された情報を含んでいます。

更新履歴の取得

Note: このフィードにアクセスするためには、サイトのオーナーか共同編集者である必要があります。クライアントはAuthSubかOAuthかClientLoginのトークンで認証されていなければなりません。 Authenticating to the Sites serviceを参照してください。

リビジョンフィードはコンテンツの更新履歴に関する情報を提供します。GetRevisionFeed()メソッドによって、指定したコンテンツの更新状況を取得することができます。このメソッドはオプションの引数のuriを取り、gdata.sites.data.ContentEntryか完全なURLかコンテンツエントリIDが指定可能です。

この例ではコンテンツフィードを取得し、その最初のエントリのリビジョンフィードを取得しています。

print "Fetching content feed of '%s'...\n" % client.site content_feed = client.GetContentFeed() content_entry = content_feed.entry[0] print "Fetching revision feed of '%s'...\n" % content_entry.title.text revision_feed = client.GetRevisionFeed(content_entry) for entry in revision_feed.entry: print entry.title.text print ' new version on:\t%s' % entry.updated.text print ' view changes:\t%s' % entry.GetAlternateLink().href print ' current version:\t%s...\n' % str(entry.content.html)[0:100]

GetRevisionFeed()を呼び出すと、gdata.sites.data.RevisionEntryのリストを含むgdata.sites.data.RevisionFeedオブジェクトが返されます。それぞれのリビジョンエントリはリビジョンごとのコンテンツやバージョン番号、いつ新しいバージョンが作成されたかのような情報を持っています。

コンテンツフィード

コンテンツフィードの取得

Note: コンテンツフィードはサイトの共有権限に応じて、認証を要求したりしなかったりします。サイトが公開でなければ、AuthSubやOAuthやClientLoginトークンによる認証が必要になります。Authenticating to the Sites serviceを参照してください。

コンテンツフィードはサイトの最新のコンテンツを返します。それはライブラリのGetContentFeed()メソッドを呼び出すことでアクセスされ、カスタマイズされたクエリを渡すためにオプションのuriという文字列の引数を取ります。

以下はコンテンツフィード全体を取得して、いくつかの項目を表示する例です。

print "Fetching content feed of '%s'...\n" % client.site feed = client.GetContentFeed() for entry in feed.entry: print '%s [%s]' % (entry.title.text, entry.Kind()) # Common properties of all entry kinds. print ' content entry id: ' + entry.GetNodeId() print ' revision:\t%s' % entry.revision.text print ' updated:\t%s' % entry.updated.text if entry.page_name: print ' page name:\t%s' % entry.page_name.text if entry.content: print ' content\t%s...' % str(entry.content.html)[0:100] # Subpages/items will have a parent link. parent_link = entry.FindParentLink() if parent_link: print ' parent link:\t%s' % parent_link # The alternate link is the URL pointing to Google Sites. if entry.GetAlternateLink(): print ' view in Sites:\t%s' % entry.GetAlternateLink().href # If this entry is a filecabinet, announcementpage, etc., it will have a feed of children. if entry.feed_link: print ' feed of items:\t%s' % entry.feed_link.href print

Tip: entry.Kind()はエントリの種類を特定するために使われます。

結果のフィードオブジェクトは gdata.sites.data.ContentEntryのリストを含むgdata.sites.data.ContentFeedです。それぞれの エントリはサイト中の異なるページ/アイテムを示し、エントリの種類を特定する要素を持ちます。それぞれのエントリの種類における利用可能なプロパティについては、サンプルアプリケーションを参照してください

コンテンツフィードのクエリの例

the standard Google Data API query parametersとSites API固有のパラメータを利用して、コンテンツフィードを検索することができます。さらに詳細な情報とサポートされたパラメータのリストについてはリファレンスガイドを参照してください。

Note: この節の例ではコンテンツフィードのbase URIを作成するために gdata.sites.client.MakeContentFeedUri()ヘルパーメソッドを利用しています。

特定のエントリ種類の検索

特定の種類のエントリのみを取得するためには、kindパラメータを利用します。attachmentエントリのみを返す例を示します。

翻訳者注: attachmentではなくwebpage？

kind = 'webpage' print 'Fetching only %s entries' % kind uri = '%s?kind=%s' % (client.MakeContentFeedUri(), kind) feed = client.GetContentFeed(uri=uri)

複数の種類を返すようにするためには、kindをコンマで区切ります。例えば、これはfilecabinetとlistpageのエントリを返すコードです。

kind = ','.join(['filecabinet', 'listpage']) print 'Fetching only %s entries' % kind uri = '%s?kind=%s' % (client.MakeContentFeedUri(), kind) feed = client.GetContentFeed(uri=uri)
パスによるページの検索

Google Siteのページの相対パスを知っていれば、特定のページを取得するpathパラメータが利用できます。この例は http://sites.google.com/domainName/siteName/path/to/the/page にあるページを返します。

path = '/path/to/the/page' print 'Fetching page by its path: ' + path uri = '%s?path=%s' % (client.MakeContentFeedUri(), path) feed = client.GetContentFeed(uri=uri)
親ページ以下にあるすべてのエントリの検索

ページのコンテンツエントリID (以下の例では"1234567890")を知っていれば、parentパラメータを利用して、(もし存在するなら)すべての子エントリを取得することができます。

parent = '1234567890' print 'Fetching all children of parent entry: ' + parent uri = '%s?parent=%s' % (client.MakeContentFeedUri(), parent) feed = client.GetContentFeed(uri=uri)

他のパラメータについては、リファレンスガイドを参照してください。

コンテンツの作成

新規コンテンツ (webpages, listpages, filecabinets, announcementpages など)はCreatePaeg()を利用することによって作成されます。このメソッドの最初の引数は作成するページの種類で、タイトルとHTMLコンテンツが続きます。

サポートされているノードの種類の一覧は、リファレンスガイドのkindパラメータを参照してください。

アイテム/ページの作成

これはトップレベル下に新しいwebpageを作成する例で、ページ本文のXHTMLを含み、'New WebPage Title'というタイトルを設定しています。

entry = client.CreatePage('webpage', 'New WebPage Title', html='<b>HTML content</b>') print 'Created. View it at: %s' % entry.GetAlternateLink().href

リクエストが成功したら、エントリはgdata.sites.gdata.ContentEntryとしてサーバ上にエントリのコピーを持ちます。

さらに複雑なエントリ種類を作成するためには(例：先頭にカラムのあるlistpage)、項目のプロパティを入力してclient.post()を呼び出し、gdata.sites.data.ContentEntryを作成する必要がああります。

カスタムURLパスのアイテム/ページの作成

デフォルトでは、さきほどの例は http://sites.google.com/domainName/siteName/new-webpage-title というURLで作成され、'New Webpage Title'というタイトルを持ちます。ここでは、タイトルがURLのためにnew-webpage-titleと正規化されています。ページのURLパスをカスタマイズするためには、コンテンツエントリのpage_nameプロパティを設定します。CreatePage()ヘルパーはオプションのキーワード引数を提供します。

この例は、'File Storage'というタイトルでfilecabinetページを作成していますが、page_nameプロパティを指定することによって、ページのURLは (http://sites.google.com/domainName/siteName/file-storage のかわりに) http://sites.google.com/domainName/siteName/filesとなっています。

entry = client.CreatePage('filecabinet', 'File Storage', html='<b>HTML content</b>', page_name='files') print 'Created. View it at: ' + entry.GetAlternateLink().href

サーバはページURLパスの命名の際に以下のルールを使用します。

  1. page_nameはa-z, A-Z, 0-9, -, _で構成される。
  2. page_nameを指定しない際でも、タイトルはnullではいけない。正規化はスペースを'-'にして、a-z, A-Z, 0-9, -, _にマッチしない文字を削除します。
サブページの作成

サブページ(子)を親ページの下に作成するためには、CreatePage()のparentキーワード引数を利用します。parentはgdata.sites.gdata.ContentEntryかコンテンツエントリの完全なIDになります。

この例は、announcementpagesのコンテンツフィードにクエリを発行し、最初に見つかったものの下に新規のアナウンスを作成しています。

uri = '%s?kind=%s' % (client.MakeContentFeedUri(), 'announcementpage') feed = client.GetContentFeed(uri=uri) entry = client.CreatePage('announcement', 'Party!!', html='My place, this weekend', parent=feed.entry[0]) print 'Posted!'
ファイルのアップロード

Google Sitesにおいては、APIはファイルキャビネットページや親ページに添付ファイルをアップロードすることをサポートしています。添付ファイルは親ページにアップロードされなければなりません。アップロードしようとするContentEntryに親リンクを設定しなければいけません。詳細な情報な情報はCreating subpagesを参照してください。

クライアントライブラリのUploadAttachment()メソッドは添付ファイルをアップロードするインターフェースを提供します。

添付ファイルのアップロード

これはコンテンツフィードで最初に見つかったfilecabinetにPDFファイルをアップロードする例です。この添付ファイルは'New Employee Handbook'というタイトルと、'HR packet'という(オプションの)説明で作成されています。

uri = '%s?kind=%s' % (client.MakeContentFeedUri(),'filecabinet') feed = client.GetContentFeed(uri=uri) attachment = client.UploadAttachment('/path/to/file.pdf', feed.entry[0], content_type='application/pdf', title='New Employee Handbook', description='HR Packet') print 'Uploaded. View it at: %s' % attachment.GetAlternateLink().href

もしアップロードが成功したら、attachmentはサーバ上に作成された添付ファイルのコピーを持ちます。

フォルダへの添付ファイルのアップロード

Google Sitesのファイルキャビネットはフォルダをサポートしています。UploadAttachment()は追加のキーワード引数を取り、folder_nameは添付ファイルをアップロードするファイルキャビネットのフォルダです。単純にフォルダの名前を指定します。

import gdata.data ms = gdata.data.MediaSource(file_path='/path/to/file.pdf', content_type='application/pdf') attachment = client.UploadAttachment(ms, feed.entry[0], title='New Employee Handbook', description='HR Packet', folder_name='My Folder')

この例ではUploadAttachment()に対して、ファイルパスのかわりにgdata.data.MediaSourceオブジェクトを渡していることに注意してください。コンテンツタイプも渡していなく、コンテンツタイプはMediaSourceオブジェクトから特定されます。

Web添付

Web添付は添付ファイルの特別な種類です。本質的には、それらはファイルキャビネットに追加されたWeb上のファイルへのリンクです。これはGoogle SitesのUIで"URLを指定してファイルを追加"と似ています。

Note: Web添付はファイルキャビネット下でのみ作成できます。他の種類のページにはアップロードできません。

この例では、ユーザのコンテンツフィードで最初に見つかったファイルキャビネットにWeb添付を作成しています。そのタイトルと(オプションの)説明はそれぞれGoogleLogo'と'nice colors'になっています。

uri = '%s?kind=%s' % (client.MakeContentFeedUri(),'filecabinet') feed = client.GetContentFeed(uri=uri) parent_entry = feed.entry[0] image_url = 'http://www.google.com/images/logo.gif' web_attachment = client.CreateWebAttachment(image_url, 'image/gif', 'GoogleLogo', parent_entry, description='nice colors') print 'Created!'

この呼び出しでファイルキャビネットに'http://www.google.com/images/logo.gif’画像のリンクが作成されます。

コンテンツの更新
ページのメタデータやHTMLコンテンツの更新

どのエントリ種類のメタデータ(タイトルやページ名)とページコンテンツも、クライアントのUpdate()メソッドで編集されます。

次の例はリストページに以下の変更をしています。

  • タイトルを'Updated Title'に修正
  • ページのHTMLコンテンツをUpdated HTML Content'に更新
  • リストの最初のカラムを"Owner"に変更
uri = '%s?kind=%s' % (client.MakeContentFeedUri(),'listpage') feed = client.GetContentFeed(uri=uri) old_entry = feed.entry[0] # Update the listpage's title, html content, and first column's name. old_entry.title.text = 'Updated Title' old_entry.content.text = 'Updated HTML Content' old_entry.data.column[0].name = 'Owner' # You can also change the page's webspace page name on an update. # old_entry.page_name = 'new-page-path' updated_entry = client.Update(old_entry) print 'List page updated!'
添付されたコンテンツとメタデータの置換

新規に新しいファイルを持つMediaSourceオブジェクトを作成し、クライアントでUpdate()メソッドを呼び出すことで、添付ファイルを置換することができます。添付の(タイトルや説明のような)メタデータもアップデートされるか、そのままとなります。この例はファイルコンテンツとメタデータを同時に更新しています。

import gdata.data # Load the replacement content in a MediaSource. Also change the attachment's title and description. ms = gdata.data.MediaSource(file_path='/path/to/replacementContent.doc', content_type='application/msword') existing_attachment.title.text = 'Updated Document Title' existing_attachment.summary.text = 'version 2.0' updated_attachment = client.Update(existing_attachment, media_source=ms) print "Attachment '%s' changed to '%s'" % (existing_attachment.title.text, updated_attachment.title.text)
コンテンツの削除

Google Siteからページやアイテムを削除するためには、まずコンテンツエントリを検索し、クライアントのDelete()メソッドを呼び出します。

client.Delete(content_entry)

Delete()メソッドにコンテンツエントリの編集リンクを渡して、削除を実行することもできます。

# force=True sets the If-Match: * header instead of using the entry's ETag. client.Delete(content_entry.GetEditLink().href, force=True)

ETagについての詳細な情報は、Google Data APIのリファレンスガイドを参照してください。

添付のダウンロード

それぞれの添付エントリはファイルコンテンツをダウンロードするsrcリンクを持ちます。サイトクライアントはこのリンクからファイルをダウンロードするためのヘルパーメソッドDownloadAttachment()を持ちます。これは最初の引数にgdata.sites.data.ContentEntryかダウンロードURIを取り、2番目に添付を保存するファイルパスを取ります。

この例は特定の添付エントリを(自身のリンクのクエリによって)取得し、指定したパスにファイルをダウンロードしています。

uri = 'https://sites.google.com/feeds/content/site/siteName/1234567890' attachment = client.GetEntry(uri, desired_class=gdata.sites.data.ContentEntry) print "Downloading '%s', a %s file" % (attachment.title.text, attachment.content.type) client.DownloadAttachment(attachment, '/path/to/save/test.pdf') print 'Downloaded!'

添付のコンテンツタイプにとってファイルの拡張子の意味があるかは開発者次第です。コンテンツタイプはentry.content.typeにあります。

ディスクにファイルをダウンロードできない場合もあります(アプリケーションがGoogle App Engineで動作している場合など)。このような状況では、ファイルコンテンツの取得に_GetFileContent()を利用し、メモリに格納します。

この例では添付をメモリにダウンロードしています。

try: file_contents = client._GetFileContent(attachment.content.src) # TODO: Do something with the file contents except gdata.client.RequestError, e: raise e


Comments