Python ガイド

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

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

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

対象

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

はじめに

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

サンプルの実行

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

次のようにサンプルを実行します。

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

必須フラグが指定されていない場合は、それらの値の入力を求めるプロンプトが表示されます。サンプルでは、さまざまな操作の実行が可能で、以前の Google サイト API の使用方法を確認できます。そのため、特定の操作（コンテンツの変更など）を実行するには認証が必要になります。また、AuthSub、OAuth、ClientLogin のいずれかによる認証を求められます。

このガイドの例を独自のコードに含めるには、次の import ステートメントが必要です。

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

また、以前の Google サイト 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 オブジェクトが作成されていることを前提としています。

以前の Google サイト API の認証

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

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

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

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

AuthSub をウェブ アプリケーションに組み込む手順を確認する

1 回限りのトークンをリクエストする

ユーザーは、初めてアプリケーションにアクセスしたときに認証を受ける必要があります。通常、デベロッパーは、ユーザーを認証してドキュメントへのアクセスをリクエストするために、ユーザーを AuthSub 承認ページに誘導するテキストとリンクを出力します。Google Data Python クライアント ライブラリには、この URL を生成する関数 generate_auth_sub_url() が用意されています。以下のコードは、AuthSubRequest ページへのリンクをセットアップしています。

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()

G Suite でホストされているドメインでユーザーを認証する場合は、ドメイン名を generate_auth_sub_url() に渡します。

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)

generate_auth_sub_url() メソッドは、いくつかのパラメータ（AuthSubRequest ハンドラで使用されるクエリ パラメータに対応）を受け取ります。

  • 次の URL - ユーザーがアカウントにログインしてアクセスを許可した後に Google がリダイレクトする URL。上記の例では http://www.example.com/myapp.py
  • スコープ - https://sites.google.com/feeds/
  • secure: トークンがセキュアな登録モードで使用されるかどうかを示すブール値（上記の例では True）
  • session: 1 回限りのトークンを後でセッション トークンと交換するかどうかを示す 2 つ目のブール値（上記の例では True）。

セッション トークンへのアップグレード

Google Data API クライアント ライブラリで AuthSub を使用するをご覧ください。

セッション トークンに関する情報の取得

Google Data API クライアント ライブラリで AuthSub を使用するをご覧ください。

セッション トークンの取り消し

Google Data API クライアント ライブラリで AuthSub を使用するをご覧ください。

ヒント: 有効期間の長いセッション トークンをアプリケーションが正常に取得したら、後で使用するためにリコールできるように、そのトークンをデータベースに保存します。アプリケーションを実行するたびにユーザーを AuthSub に戻す必要はありません。client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR) を使用して、クライアントに既存のトークンを設定します。

ウェブ用またはインストール型/モバイルアプリ用の OAuth

OAuth は AuthSub の代替手段として使用できる、ウェブ アプリケーションを対象としています。 OAuth では、すべてのデータ リクエストにデジタル署名され、ドメインを登録する必要がある点で、AuthSub のセキュアな登録モードを使用する場合と類似しています。

インストールしたアプリケーションに OAuth を組み込む手順を表示

リクエスト トークンの取得

Google Data API クライアント ライブラリでの OAuth の使用をご覧ください。

リクエスト トークンを承認する

Google Data API クライアント ライブラリでの OAuth の使用をご覧ください。

アクセス トークンへのアップグレード

Google Data API クライアント ライブラリでの OAuth の使用をご覧ください。

ヒント: アプリケーションが OAuth アクセス トークンを正常に取得したら、そのトークンをデータベースに格納して、後で使用できるようにリコールします。アプリケーションを実行するたびに OAuth を介してユーザーを送り返す必要はありません。client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET) を使用して、クライアントに既存のトークンを設定します。

インストール型アプリケーションまたはモバイル アプリケーション用の ClientLogin

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

ClientLogin をインストールしたアプリケーションに組み込む手順を表示する

ClientLogin を使用するには、GDClient から継承される SitesClient オブジェクトの ClientLogin() メソッドを呼び出します。代わりにクライアントがリクエストを行うユーザーのメールアドレスとパスワードを指定します。例:

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

ヒント: アプリケーションで初めてユーザーの認証に成功したら、後で使用できるように認証トークンをデータベースに保存します。アプリを実行するたびにユーザーにパスワードの入力を求める必要はありません。詳しくは、認証トークンの再現をご覧ください。

Python アプリケーションで ClientLogin を使用する方法について詳しくは、Google Data API クライアント ライブラリでの ClientLogin の使用をご覧ください。

トップへ戻る

サイトフィード

サイトフィードは、ユーザーが所有する、または閲覧権限のある 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 オブジェクトに設定されているドメインとは異なるドメインの下にサイトを作成する場合）。

以下の例では、「スレート」テーマで新しいサイトを作成し、タイトルと説明（省略可）を指定しています。

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 サイトのサービスの認証をご覧ください。

サイトの最近のアクティビティ（変更）を取得するには、アクティビティ フィードを取得します。lib の 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() メソッドを使用して、特定のコンテンツ エントリのリビジョンを取得できます。このメソッドは、オプションの uri パラメータを取ります。このパラメータは、gdata.sites.data.ContentEntry、コンテンツ エントリの完全な URI、またはコンテンツ エントリ 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 オブジェクトが返されます。各リビジョン エントリには、そのリビジョンの内容、バージョン番号、新しいバージョンが作成された日時などの情報が含まれています。

トップへ戻る

コンテンツ フィード

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

注: コンテンツ フィードは、サイトの共有権限に応じて、認証が必要な場合と必要ない場合があります。 サイトが非公開の場合、クライアントは 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 クエリ パラメータと、以前の Google サイト API に固有のパラメータを使用して、コンテンツ フィードを検索できます。サポートされているパラメータの詳細と一覧については、リファレンス ガイドをご覧ください。

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

特定のエントリの種類を取得する

特定のタイプのエントリのみを取得するには、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() を使用して作成できます。このメソッドの最初の引数には、作成するページの種類を指定し、次にタイトル、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

リクエストが成功すると、サーバーで作成されたエントリのコピーが entry に gdata.sites.gdata.ContentEntry として含まれます。

作成時に入力されるより複雑なエントリの種類（列見出しを含む 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() ヘルパーは、これをオプションのキーワード引数として提供します。

この例では、「File Storage」という見出しの新しい filecabinet ページを作成していますが、page_name プロパティを指定することで、http://sites.google.com/domainName/siteName/file-storage ではなく http://sites.google.com/domainName/siteName/files という URL でページを作成しています。

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 をクエリし、最初に見つかったフィードの下に新しい 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 ファイルをアップロードします。「新従業員ハンドブック」というタイトルと、（オプションの）説明「HR パケット」を使用して、添付ファイルが作成されます。

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() には、追加のキーワード引数 folder_name が用意されています。この引数を使用すると、添付ファイルを filecabinet フォルダにアップロードできます。フォルダ名を指定します。

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 コンテンツの更新

メタデータ（title、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 API リファレンス ガイドをご覧ください。

トップへ戻る


添付ファイルをダウンロードしています

各 attachment エントリには、ファイル コンテンツのダウンロードに使用できるコンテンツの src リンクが含まれています。Google サイト クライアントには、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 つのエントリが表示されます。したがって、サイトへの暗黙的なアクセス権がある場合でも、ドメイン管理者は表示されません。

ロール

ロール要素は、エンティティが持つことができるアクセスレベルを表します。gAcl:role 要素で使用できる値は次の 4 つです。

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

スコープ

スコープ要素は、このアクセスレベルを持つエンティティを表します。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 は、ドメイン全体を domain2.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 API リファレンス ガイドをご覧ください。

トップへ戻る

特別なトピック

フィードまたはエントリを再度取得する

以前に取得したフィードやエントリを取得する場合は、前回取得してから変更されている場合にのみリストまたはエントリを送信するようにサーバーに伝えることで、効率を向上できます。

この種の条件付き取得を行うには、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 リファレンス ガイドをご覧ください。

トップへ戻る