Python ガイド

重要: このドキュメントは 2012 年より前に作成されたものです。このドキュメントで説明する認証オプション（OAuth 1.0、AuthSub、ClientLogin）は、2012 年 4 月 20 日をもって正式に非推奨となり、使用できなくなりました。できるだけ早く OAuth 2.0 に移行することをおすすめします。

Google Sites Data API を使用すると、クライアント アプリケーションは Google サイト内のコンテンツにアクセス、公開、変更を行うことができます。クライアント アプリケーションは、最近のアクティビティのリストをリクエストしたり、リビジョン履歴を取得したり、添付ファイルをダウンロードしたりすることもできます。

このガイドでは、Sites Data API の機能に関する背景情報に加えて、Python クライアント ライブラリを使用して API を操作する例を示します。クライアント ライブラリの設定については、Google Data Python クライアント ライブラリのスタートガイドをご覧ください。Python クライアント ライブラリが従来の Sites API とのやり取りに使用する基盤となるプロトコルについて詳しくは、プロトコル ガイドをご覧ください。

オーディエンス

このドキュメントは、Google Data Python クライアント ライブラリを使用して Google Sites とやり取りするクライアント アプリケーションを作成するデベロッパーを対象としています。

スタートガイド

Python クライアント ライブラリを使用するには、Python 2.2 以降と、DependencyModules ウィキページに記載されているモジュールが必要です。クライアント ライブラリをダウンロードした後、クライアントのインストールと使用方法については、Google Data Python ライブラリ スタートガイドをご覧ください。

サンプルの実行

完全なサンプルは、プロジェクトの 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

また、従来の Sites API へのクライアント接続を表す SitesClient オブジェクトを設定する必要があります。アプリの名前と、サイトのウェブスペース名（URL から取得）を渡します。

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

G Suite ドメインでホストされているサイトを使用するには、domain パラメータを使用してドメインを設定します。

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

上記のスニペットで、source 引数は省略可能ですが、ロギング目的で使用することをおすすめします。形式は company-applicationname-version にする必要があります。

注: 以降のガイドでは、変数 client に SitesClient オブジェクトを作成していることを前提としています。

従来の Sites API に対する認証

Python クライアント ライブラリは、公開フィードまたは非公開フィードのいずれかに対応しています。Sites Data API は、サイトの権限と実行しようとしているオペレーションに応じて、限定公開フィードと公開フィードにアクセスできます。たとえば、公開サイトのコンテンツ フィードを読み取ることはできても、更新することはできない場合があります。更新には認証済みクライアントが必要です。これを行うには、ClientLogin のユーザー名とパスワードによる認証、AuthSub、または OAuth を使用します。

AuthSub、OAuth、ClientLogin の詳細については、Google Data APIs 認証の概要をご覧ください。

ウェブ アプリケーションの AuthSub

ウェブ アプリケーションの AuthSub 認証は、Google アカウントまたは G Suite アカウントのユーザーを認証する必要があるクライアント アプリケーションで使用する必要があります。オペレーターが Google サイト ユーザーのユーザー名とパスワードにアクセスする必要はありません。必要なのは AuthSub トークンだけです。

import gdata.gauth

def GetAuthSubUrl():
  next = 'http://www.example.com/myapp.py'
  scopes = ['https://sites.google.com/feeds/']
  secure = True
  session = True
  return gdata.gauth.generate_auth_sub_url(next, scopes, secure=secure, session=session)

print '<a href="%s">Login to your Google account</a>' % GetAuthSubUrl()

def GetAuthSubUrl():
  domain = 'example.com'
  next = 'http://www.example.com/myapp.py'
  scopes = ['https://sites.google.com/feeds/']
  secure = True
  session = True
  return gdata.gauth.generate_auth_sub_url(next, scopes, secure=secure, session=session, domain=domain)

ウェブ アプリケーション、インストール型アプリケーション、モバイルアプリの OAuth

OAuthOAuth は、ウェブ アプリケーションを対象としたもので、AuthSub の代わりに使用できます。OAuth では、すべてのデータ リクエストにデジタル署名が必要で、ドメインを登録する必要があるという点で、AuthSub のセキュア モードかつ登録済みモードの使用と似ています。

インストール済み / モバイルアプリの ClientLogin

ClientLogin は、Google アカウントでユーザーを認証する必要があるインストール済みアプリまたはモバイルアプリで使用する必要があります。初回実行時に、ユーザー名とパスワードの入力を求めるメッセージが表示されます。後続のリクエストでは認証トークンが参照されます。

client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1')
client.ClientLogin('user@gmail.com', 'pa$$word', client.source);

トップへ戻る

サイト フィード

サイトフィードを使用すると、ユーザーが所有する Google サイト、または閲覧権限のある Google サイトを一覧表示できます。 既存のサイトの名前を変更することもできます。最後に、G Suite ドメインの場合は、サイト全体の作成やコピーにも使用できます。

サイトの一覧表示

ユーザーがアクセスできるサイトを一覧表示するには、クライアントの GetSiteFeed() メソッドを使用します。このメソッドは、オプションの引数 uri を受け取ります。この引数を使用して、代替のサイトフィード URI を指定できます。デフォルトでは、GetSiteFeed() はクライアント オブジェクトに設定されたサイト名とドメインを使用します。クライアント オブジェクトにこれらの値を設定する方法については、スタートガイドをご覧ください。

認証されたユーザーのサイトリストを取得する例を次に示します。

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 フィード URI を出力します。

新しいサイトを作成する

注: この機能は G Suite ドメインでのみご利用いただけます。

新しいサイトをプロビジョニングするには、ライブラリの CreateSite() メソッドを呼び出します。GetSiteFeed() ヘルパーと同様に、CreateSite() はオプションの引数 uri も受け入れます。この引数は、代替サイトフィード URI の指定に使用できます（SitesClient オブジェクトに設定されているドメインとは異なるドメインでサイトを作成する場合）。

「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

上記のリクエストにより、G Suite ドメイン example2.com の下に新しいサイトが作成されます。つまり、サイトの URL は https://sites.google.com/a/example2.com/title-for-my-site となります。

サイトが正常に作成されると、サーバーは gdata.sites.data.SiteEntry オブジェクトをレスポンスとして返します。このオブジェクトには、サイトへのリンク、サイトの ACL フィードへのリンク、サイト名、タイトル、概要などのサーバーが追加した要素が設定されます。

サイトのコピー

注: この機能は G Suite ドメインでのみご利用いただけます。

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 サイトの設定ページで [このサイトをテンプレートとして公開] がオンになっているサイトは、テンプレートです。
• 移行元サイトで所有者として登録されていれば、別のドメインからサイトをコピーできます。

サイトのメタデータの更新

サイトのタイトルまたは概要を更新するには、該当するサイトを含む 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)

トップへ戻る

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

注: このフィードにアクセスするには、サイトの共同編集者またはオーナーである必要があります。 クライアントは、AuthSub、OAuth、または ClientLogin トークンを使用して認証する必要があります。Google サイトサービスへの認証をご覧ください。

アクティビティ フィードを取得することで、サイトの最近のアクティビティ（変更）を取得できます。ライブラリの 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 オブジェクトが返されます。各アクティビティ エントリには、サイトに加えられた変更に関する情報が含まれます。

トップへ戻る

変更履歴を取得しています

注: このフィードにアクセスするには、サイトのコラボレーターまたはオーナーである必要があります。クライアントは、AuthSub、OAuth、または ClientLogin トークンを使用して認証する必要があります。Google サイトサービスへの認証をご覧ください。

リビジョン フィードは、コンテンツ エントリの変更履歴に関する情報を提供します。GetRevisionFeed() メソッドを使用して、特定のコンテンツ エントリのリビジョンを取得できます。このメソッドは、gdata.sites.data.ContentEntry、コンテンツ エントリの完全な URI、またはコンテンツ エントリ ID を受け入れるオプションの uri パラメータを受け取ります。

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

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 オブジェクトが返されます。各リビジョン エントリには、そのリビジョンのコンテンツ、バージョン番号、新しいバージョンが作成された日時などの情報が含まれます。

トップへ戻る

コンテンツ フィード

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

注: コンテンツ フィードは、サイトの共有権限に応じて、認証を必要とする場合と必要ない場合があります。 サイトが公開されていない場合は、クライアントが AuthSub、OAuth、または ClientLogin トークンを使用して認証する必要があります。Google サイトサービスの認証をご覧ください。

コンテンツ フィードは、サイトの最新のコンテンツを返します。このライブラリにアクセスするには、lib の 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

ヒント: entry.Kind() を使用して、エントリのタイプを特定できます。

結果の feed オブジェクトは、gdata.sites.data.ContentEntry のリストを含む gdata.sites.data.ContentFeed です。各エントリは、ユーザーのサイト内の異なるページまたはアイテムを表し、エントリの種類に固有の要素があります。各エントリの種類で使用可能なプロパティについては、サンプル アプリケーションをご覧ください。

トップへ戻る

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

コンテンツ フィードを検索するには、標準の Google Data API クエリ パラメータの一部と、従来の Sites API に固有のパラメータを使用します。詳細とサポートされているパラメータの一覧については、リファレンス ガイドをご覧ください。

注: このセクションの例では、コンテンツ フィードのベース URI を作成するために gdata.sites.client.MakeContentFeedUri() ヘルパー メソッドを使用しています。

特定のエントリの種類の取得

特定のタイプのエントリのみを取得するには、kind パラメータを使用します。たとえば、次のスニペットは attachment エントリのみを返します。

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 サイト内のページの相対パスがわかっている場合は、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)

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

トップへ戻る

コンテンツの作成

注: サイトのコンテンツを作成する前に、クライアントでサイトが設定されていることを確認してください。
client.site = "siteName"

CreatePage() を使用して、新しいコンテンツ（ウェブページ、リストページ、ファイル キャビネット、お知らせページなど）を作成できます。このメソッドの最初の引数は作成するページの種類を指定し、その後に title、その 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 として entry に格納されます。

作成時に入力されるより複雑なエントリ タイプ（列見出し付きの listpage など）を作成するには、gdata.sites.data.ContentEntry を手動で作成し、目的のプロパティに入力して client.Post() を呼び出す必要があります。

カスタム URL パスでアイテムやページを作成する

デフォルトでは、上記の例は URL http://sites.google.com/domainName/siteName/new-webpage-title の下に作成され、ページの見出しは「新しいウェブページのタイトル」になります。つまり、タイトルは URL の new-webpage-title に正規化されます。ページの URL パスをカスタマイズするには、コンテンツ エントリに page_name プロパティを設定します。CreatePage() ヘルパーは、これをオプションのキーワード引数として提供します。

この例では、ヘッダーが「ファイル ストレージ」の新しい 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. title。ページ名が存在しない場合は null にすることはできません。正規化では、空白文字を「-」にカットして折りたたみ、a-z, A-Z, 0-9, -, _ に一致しない文字を削除します。

サブページの作成

親ページの下にサブページ（子）を作成するには、CreatePage() の parent キーワード引数を使用します。parent は、gdata.sites.gdata.ContentEntry またはコンテンツのエントリの完全なセルフ ID を表す文字列のいずれかです。

この例では、コンテンツ フィードで announcementpage をクエリし、最初に見つかった announcementpage の下に新しい announcement を作成します。

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 サイトと同様に、API はファイル キャビネット ページまたは親ページへの添付ファイルのアップロードをサポートしています。添付ファイルは親ページにアップロードする必要があります。そのため、アップロードしようとしている ContentEntry に親リンクを設定する必要があります。詳細については、サブページの作成をご覧ください。

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

添付ファイルをアップロードしています

この例では、ユーザーのコンテンツ フィードで見つかった最初の filecabinet に PDF ファイルをアップロードします。アタッチメントは、タイトルが「新入社員ハンドブック」、説明が「人事パッケージ」（省略可）で作成されます。

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 サイトのファイルキャビネットはフォルダをサポートしています。UploadAttachment() には、filecabinet フォルダに添付ファイルをアップロードするために使用できる追加のキーワード引数 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')

この例では、ファイルパスの代わりに gdata.data.MediaSource オブジェクトを UploadAttachment() に渡しています。また、コンテンツ タイプも渡されません。コンテンツ タイプは MediaSource オブジェクトで指定されます。

ウェブ アタッチメント

ウェブ アタッチメントは特別な種類の添付ファイルです。基本的に、filecabinet リスティングに追加できる、ウェブ上の他のファイルへのリンクです。この機能は、Google サイトの管理画面の [URL でファイルを追加] アップロード方法に似ています。

注: ウェブ添付ファイルを作成できるのは filecabinet の下のみです。他のタイプのページにはアップロードできません。

この例では、ユーザーのコンテンツフィード内で見つかった最初の filecabinet の下にウェブ アタッチメントを作成します。タイトルと（省略可の）説明は、それぞれ「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!'

この呼び出しにより、filecabinet の「http://www.google.com/images/logo.gif」に画像へのリンクが作成されます。

トップへ戻る

コンテンツの更新

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

あらゆる種類のエントリのメタデータ（タイトル、pageName など）とページ コンテンツは、クライアントの Update() メソッドを使用して編集できます。

以下に、listpage を更新して次の変更を加える例を示します。

• タイトルが「更新後のタイトル」に変更されます。
• ページの HTML コンテンツが「更新された HTML コンテンツ」に更新されている
• リストの最初の列の見出しが [オーナー] に変更されます。

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.html = '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 サイトからページまたはアイテムを削除するには、まずコンテンツ エントリを取得してから、クライアントの Delete() メソッドを呼び出します。

client.Delete(content_entry)

Delete() メソッドにコンテンツ エントリの edit リンクを渡すか、削除を強制することもできます。

# 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 APIs リファレンス ガイドをご覧ください。

トップへ戻る

添付ファイルのダウンロード

各 attachment エントリには、ファイル コンテンツのダウンロードに使用できるコンテンツの src リンクが含まれています。Sites クライアントには、このリンク（DownloadAttachment()）からファイルにアクセスしてダウンロードするためのヘルパー メソッドが含まれています。最初の引数には gdata.sites.data.ContentEntry またはダウンロード URI、2 番目の引数には添付ファイルを保存するファイルパスを指定します。

この例では、特定の添付エントリを取得し（self リンクをクエリして）、ファイルを指定されたパスにダウンロードします。

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

トップへ戻る

ACL フィード

共有権限（ACL）の概要

ACL フィード内の各 ACL エントリは、特定のエンティティ（ユーザー、ユーザー グループ、ドメイン、デフォルト アクセス（公開サイト））のアクセスロールを表します。明示的なアクセス権を持つエンティティに対してのみ、エントリが表示されます。Google サイト UI の共有画面にある [アクセス権のあるユーザー] パネルには、メールアドレスごとに 1 つのエントリが表示されます。したがって、サイトへのアクセス権が暗黙的に付与されていても、ドメイン管理者は表示されません。

ロール

role 要素は、エンティティに付与できるアクセスレベルを表します。gAcl:role 要素で使用できる値は次の 4 つです。

• reader - 閲覧者（読み取り専用アクセスと同等）。
• writer - 共同編集者（読み取り / 書き込みアクセスと同等）。
• オーナー - 通常はサイト管理者（読み取り / 書き込みアクセスと同等）。

スコープ

scope 要素は、このアクセスレベルを持つエンティティを表します。gAcl:scope 要素には次の 4 つのタイプがあります。

• user - メールアドレスの値（例: user@gmail.com）。
• group - Google グループのメールアドレス（例: group@domain.com）。
• domain - G Suite ドメイン名（例: domain.com）。
• default - 値を持たない「default」タイプのスコープは 1 つだけです（例: <gAcl:scope type="default">）。このスコープは、一般公開サイトでユーザーがデフォルトで持つアクセスを制御します。

注: ドメインの gAcl:role 値を「オーナー」アクセスに設定することはできません。ドメインは読み取り専用または書き込み専用にする必要があります。

ACL フィードの取得

ACL フィードは、サイトの共有権限を制御するために使用でき、GetAclFeed() メソッドを使用して取得できます。

次の例では、現在 SitesClient オブジェクトに設定されているサイトの ACL フィードを取得し、権限エントリを出力します。

print "Fetching acl permissions of site '%s'...\n" % client.site

feed = client.GetAclFeed()
for entry in feed.entry:
  print '%s (%s) - %s' % (entry.scope.value, entry.scope.type, entry.role.value)

クエリが成功すると、feed は gdata.sites.data.AclEntry のリストを含む gdata.sites.data.AclFeed オブジェクトになります。

SiteFeed のエントリを操作する場合、各 SiteEntry には ACL フィードへのリンクが含まれています。たとえば、次のスニペットは、ユーザーのサイトフィード内の最初のサイトを取得し、その ACL フィードをクエリします。

feed = client.GetSiteFeed()
site_entry = feed.entry[0]

print "Fetching acl permissions of site '%s'...\n" % site_entry.site_name.text
feed = client.GetAclFeed(uri=site_entry.FindAclLink())

サイトを共有する

注: 特定の共有 ACL は、ドメインでそのような権限が許可されるように構成されている場合にのみ使用できます（G Suite ドメインのドメイン外での共有が有効になっている場合など）。

API を使用して Google サイトを共有するには、必要な gdata.acl.data.AclScope と gdata.acl.data.AclRole の値を使用して gdata.sites.gdata.AclEntry を作成します。使用可能な AclScope 値と AclRoles 値については、ACL フィード概要のセクションをご覧ください。

次の例では、サイトの読み取り権限をユーザー「user@example.com」に付与します。

import gdata.acl.data

scope = gdata.acl.data.AclScope(value='user@example.com', type='user')
role = gdata.acl.data.AclRole(value='reader')
acl = gdata.sites.gdata.AclEntry(scope=scope, role=role)

acl_entry = client.Post(acl, client.MakeAclFeedUri())
print "%s %s added as a %s" % (acl_entry.scope.type, acl_entry.scope.value, acl_entry.role.value)

グループレベルとドメインレベルの共有

サイトを 1 人のユーザーと共有する場合と同様に、Google グループまたは G Suite ドメイン間でサイトを共有できます。必要な scope 値は次のとおりです。

グループのメールアドレスへの共有:

scope = gdata.acl.data.AclScope(value='group_name@example.com', type='group')

ドメイン全体と共有する:

scope = gdata.acl.data.AclScope(value='example.com', type='domain')

ドメイン単位での共有は、G Suite ドメインでのみサポートされ、サイトがホストされているドメインでのみ使用できます。たとえば、http://sites.google.com/a/domain1.com/siteA はサイト全体を domain1.com とのみ共有でき、domain2.com とは共有できません。G Suite ドメインでホストされていないサイト（http://sites.google.com/site/siteB など）はドメインを招待できません。

共有権限の変更

サイトの既存の共有権限に変更を加える場合は、まず該当する AclEntry を取得し、必要に応じて権限を変更してから、クライアントの Update() メソッドを呼び出してサーバーの ACL を変更します。

この例では、サイトの共有セクションの以前の acl_entry を変更し、「user@example.com」を書き込みユーザー（共同編集者）に更新します。

acl_entry.role.value = 'writer'
updated_acl = client.Update(acl_entry)

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

ETag の詳細については、Google Data API リファレンス ガイドをご覧ください。

共有権限の削除

共有権限を削除するには、まず AclEntry を取得してから、クライアントの Delete() メソッドを呼び出します。

client.Delete(acl_entry)

Delete() メソッドに ACL エントリの edit リンクを渡すか、削除を強制することもできます。

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

ETag について詳しくは、Google Data APIs リファレンス ガイドをご覧ください。

トップへ戻る

特別なトピック

フィードまたはエントリの再取得

以前に取得したフィードまたはエントリを取得する場合は、前回取得したときとリストまたはエントリが変更されている場合にのみ送信するようにサーバーに指示することで、効率を高めることができます。

このような条件付き取得を行うには、ETag 値を GetEntry() に渡します。たとえば、既存の entry オブジェクトがあるとします。

import gdata.client

try:
  entry = client.GetEntry(entry.GetSelfLink().href, desired_class=gdata.sites.data.ContentEntry, etag=entry.etag)
except gdata.client.NotModified, error:
  print 'You have the latest copy of this entry'
  print error

GetEntry() が gdata.client.NotModified 例外をスローした場合、エントリの ETag はサーバー上のバージョンと一致します。つまり、最新のコピーが存在することを意味します。ただし、別のクライアントまたはユーザーが変更を加えた場合は、新しいエントリが entry に返され、例外はスローされません。

ETag の詳細については、Google Data API リファレンス ガイドをご覧ください。

トップへ戻る