Руководство по Python

Важно! Этот документ был написан до 2012 г. Варианты аутентификации, описанные в этом документе (OAuth 1.0, AuthSub и ClientLogin), официально устарели с 20 апреля 2012 г. и больше не поддерживаются. Мы рекомендуем вам как можно скорее перейти на OAuth 2.0.

Google Sites Data API позволяет клиентским приложениям получать доступ к контенту на сайте Google, публиковать его и изменять. Клиентское приложение также может запрашивать список недавних действий, получать историю изменений и скачивать прикрепленные файлы.

В этом руководстве рассказывается о возможностях Sites Data API и приводятся примеры взаимодействия с API с помощью клиентской библиотеки Python. Инструкции по настройке клиентской библиотеки приведены в статье Как начать работу с клиентской библиотекой Google Data Python. Если вы хотите узнать больше о протоколе, который использует клиентская библиотека Python для взаимодействия с классическим Sites API, ознакомьтесь с руководством по протоколу.

Аудитория

Этот документ предназначен для разработчиков, которые хотят создавать клиентские приложения, взаимодействующие с Google Сайтами с помощью клиентской библиотеки Google Data для Python.

Начало работы

Чтобы использовать клиентскую библиотеку Python, вам понадобится Python 2.2+ и модули, перечисленные на странице вики-сайта DependencyModules. После скачивания клиентской библиотеки ознакомьтесь с руководством по началу работы с библиотекой Google Data для Python, чтобы узнать, как установить и использовать клиент.

Как запустить пример

Полный рабочий пример находится в подкаталоге samples/sites репозитория Mercurial проекта (/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]

Если обязательные флаги не указаны, приложение предложит вам ввести их значения. Пример позволяет пользователю выполнять ряд операций, которые демонстрируют, как использовать классический API Сайтов. Поэтому для выполнения некоторых операций, например изменения контента, вам потребуется пройти аутентификацию. Вам также будет предложено пройти аутентификацию с помощью AuthSub, OAuth или ClientLogin.

Чтобы включить примеры из этого руководства в свой код, вам понадобятся следующие операторы import:

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

Вам также потребуется настроить объект SitesClient, который представляет собой клиентское подключение к Sites API. Передайте название приложения и название веб-пространства сайта (из его 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

Примечание. В остальной части руководства предполагается, что вы создали объект SitesClient в переменной client.

Как выполнять аутентификацию для Sites API

Клиентскую библиотеку Python можно использовать для работы с общедоступными и частными фидами. Sites Data API предоставляет доступ к частным и общедоступным фидам в зависимости от разрешений сайта и операции, которую вы пытаетесь выполнить. Например, вы можете читать фид контента общедоступного сайта, но не сможете его изменить, так как для этого требуется аутентифицированный клиент. Это можно сделать с помощью аутентификации по имени пользователя и паролю ClientLogin, AuthSub или OAuth.

Подробнее об аутентификации в API данных Google…

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 для веб-приложений или установленных/мобильных приложений

OAuth можно использовать вместо 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, которыми владеет пользователь или которые ему разрешено просматривать. Его также можно использовать, чтобы изменить название существующего сайта. Наконец, в доменах 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

Приведенный выше фрагмент кода выводит заголовок сайта, название сайта, сайт, с которого он был скопирован, и URI фида ACL.

Создание новых сайтов

Примечание. Эта функция доступна только в доменах 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. Подробнее о том, как пройти аутентификацию в сервисе "Сайты"…

Чтобы получить информацию о недавних действиях на сайте (изменениях), запросите фид действий. Доступ к этому фиду можно получить с помощью метода 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.ActivityFeed, содержащий список объектов gdata.sites.data.ActivityEntry. Каждая запись содержит информацию об изменении, внесенном на сайт.

К началу

Получение истории изменений

Примечание. Чтобы получить доступ к этому фиду, вы должны быть соавтором или владельцем сайта. Клиент должен пройти аутентификацию с помощью токена AuthSub, OAuth или ClientLogin. Подробнее о том, как пройти аутентификацию в сервисе "Сайты"…

Фид изменений содержит информацию об истории изменений для каждой записи контента. Метод GetRevisionFeed() позволяет получить список версий для определенной записи контента. Метод принимает необязательный параметр uri, который может быть gdata.sites.data.ContentEntry, полным 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.RevisionFeed, содержащий список gdata.sites.data.RevisionEntry. Каждая запись о версии содержит информацию о контенте, номере версии и дате ее создания.

К началу

Фид контента

Получение фида контента

Примечание. Для доступа к фиду контента может требоваться аутентификация. Это зависит от настроек доступа к сайту. Если сайт не является общедоступным, клиент должен пройти аутентификацию с помощью токена AuthSub, OAuth или ClientLogin. Подробная информация доступна в разделе Аутентификация в сервисе "Сайты".

Фид контента возвращает новейший контент сайта. Его можно получить, вызвав метод 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.ContentFeed, содержащий список gdata.sites.data.ContentEntry. Каждая запись представляет собой отдельную страницу или объект на сайте пользователя и содержит элементы, характерные для определенного типа записи. Чтобы лучше понять, какие свойства доступны для каждого типа записи, ознакомьтесь с примером приложения.

К началу

Примеры запросов к фиду контента

Вы можете искать контент в фиде, используя некоторые стандартные параметры запроса Google Data API и параметры, относящиеся к классическому Sites 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)

Получение всех записей на родительской странице

Если вам известен идентификатор контента страницы (например, "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 для тела страницы и задается заголовок "Новый заголовок веб-страницы":

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() предоставляет этот аргумент в качестве необязательного ключевого слова.

В этом примере создается новая страница filecabinet с заголовком "Хранение файлов", но страница создается по URL http://sites.google.com/domainName/siteName/files (вместо http://sites.google.com/domainName/siteName/file-storage) путем указания свойства page_name.

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. Если название страницы не указано, значение не может быть нулевым. Нормализация заключается в том, чтобы удалить пробелы и заменить их на дефисы, а также удалить символы, не соответствующие регулярному выражению a-z, A-Z, 0-9, -, _.

Как создавать подстраницы

Чтобы создать подстраницы (дочерние страницы) для родительской страницы, используйте ключевой аргумент parent команды CreatePage(). parent может быть объектом gdata.sites.gdata.ContentEntry или строкой, представляющей полный идентификатор записи контента.

В этом примере выполняется запрос к фиду контента для поиска объектов 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() клиентской библиотеки предоставляет интерфейс для загрузки прикрепленных файлов.

Загрузка прикрепленных файлов…

В этом примере PDF-файл загружается в первый объект filecabinet, найденный в фиде контента пользователя. Прикрепленный файл будет называться "Новое руководство для сотрудников", а его описание (необязательное) – "Пакет документов для отдела кадров".

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

Обратите внимание, что в этом примере в UploadAttachment() передается объект gdata.data.MediaSource, а не путь к файлу. Также не передается тип контента. Вместо этого тип контента указывается в объекте MediaSource.

Веб-приложения

Веб-приложения – это особый тип прикрепленных файлов. По сути, это ссылки на другие файлы в интернете, которые можно добавить в объявления filecabinet. Эта функция аналогична методу загрузки Добавить файл по URL в интерфейсе Google Сайтов.

Примечание. Веб-приложения можно создавать только в разделе 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!'

Этот вызов создает ссылку на изображение по адресу http://www.google.com/images/logo.gif в элементе filecabinet.

К началу

Обновление контента

Изменение метаданных и/или 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…

К началу

Как скачать прикрепленные файлы

Каждая запись attachment содержит ссылку на контент src, по которой можно скачать содержимое файла. Клиент Сайтов содержит вспомогательный метод для доступа к файлу по этой ссылке и его скачивания: DownloadAttachment(). Первый аргумент – это URI для gdata.sites.data.ContentEntry или скачивания, а второй – путь к файлу, в который нужно сохранить прикрепленный файл.

В этом примере извлекается определенный объект прикрепленного файла (путем запроса его ссылки 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 представляет роль доступа определенного объекта: пользователя, группы пользователей, домена или доступа по умолчанию (общедоступного сайта). Записи будут показываться только для объектов с явным доступом – по одной записи для каждого адреса электронной почты на панели "Пользователи с доступом" на экране предоставления доступа в интерфейсе Google Сайтов. Поэтому администраторы домена не будут показаны, даже если у них есть неявный доступ к сайту.

Роли

Элемент role представляет уровень доступа, который может быть у объекта. Элемент gAcl:role может принимать четыре значения:

• Читатель – пользователь с правами просмотра (эквивалент доступа только для чтения).
• writer – соавтор (эквивалент доступа для чтения и записи).
• Владелец – обычно администратор сайта (эквивалентно доступу на чтение и запись).

Области действия

Элемент области действия представляет объект, которому назначен этот уровень доступа. Существует четыре возможных типа элемента gAcl:scope:

• user – значение адреса электронной почты, например user@gmail.com.
• group – адрес электронной почты группы Google, например group@domain.com.
• domain – доменное имя G Suite, например "domain.com".
• default – существует только одна область типа "default", у которой нет значения (например, <gAcl:scope type="default">). Эта область определяет доступ, который по умолчанию есть у любого пользователя на общедоступном сайте.

Примечание. Для доменов нельзя задать значение gAcl:role "владелец". Доступ может быть только для чтения или записи.

Как получить фид ACL

Фид ACL можно использовать для управления разрешениями на предоставление доступа к сайту. Его можно получить с помощью метода GetAclFeed().

В следующем примере извлекается фид ACL для сайта, заданного в объекте SitesClient, и выводятся записи разрешений:

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.AclFeed, содержащим список gdata.sites.data.AclEntry.

Если вы работаете с записями в 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 и т. д.).

Чтобы поделиться сайтом Google с помощью API, создайте gdata.sites.gdata.AclEntry с нужными значениями gdata.acl.data.AclScope и gdata.acl.data.AclRole. Возможные значения 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)

Предоставление доступа на уровне группы и домена

Как и в случае с предоставлением доступа к сайту одному пользователю, вы можете предоставить доступ к сайту группе 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_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…

Как отменить разрешения на доступ

Чтобы удалить разрешение на доступ, сначала получите AclEntry, а затем вызовите метод Delete() клиента.

client.Delete(acl_entry)

Вы также можете передать методу Delete() ссылку edit записи ACL и/или принудительно удалить запись:

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

Подробнее о тегах ETag…

К началу

Специальные темы

повторно получить фид или запись;

Если вы хотите получить фид или запись, которые уже получали ранее, можно повысить эффективность, указав серверу отправлять список или запись только в том случае, если они изменились с момента последнего получения.

Чтобы выполнить условное получение, передайте значение 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…

К началу