読者です 読者をやめる 読者になる 読者になる

Google Sites API Python Language Guide (v1.4) 日本語訳 (2/3)

Python

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

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