Важно! Этот документ был написан до 2012 года. Параметры аутентификации, описанные в этом документе (OAuth 1.0, AuthSub и ClientLogin), официально признаны устаревшими с 20 апреля 2012 года и больше не доступны. Мы рекомендуем вам как можно скорее перейти на OAuth 2.0 .
API данных Google Sites позволяет клиентским приложениям получать доступ, публиковать и изменять контент на сайте Google . Ваше клиентское приложение также может запрашивать список недавних действий, получать историю изменений и загружать вложения.
Помимо общей информации о возможностях API данных сайтов, в этом руководстве приводятся примеры взаимодействия с API с помощью клиентской библиотеки Python . Информацию о настройке клиентской библиотеки см . в разделе «Начало работы с клиентской библиотекой Google Data Python» . Если вы хотите узнать больше о базовом протоколе, используемом клиентской библиотекой Python для взаимодействия с классическим API Сайтов, ознакомьтесь с руководством по протоколу .
Аудитория
Этот документ предназначен для разработчиков, желающих писать клиентские приложения, взаимодействующие с Сайтами Google с использованием клиентской библиотеки Google Data Python .
Начиная
Чтобы использовать клиентскую библиотеку Python, вам понадобится Python 2.2+ и модули, перечисленные на вики-странице DependencyModules . После загрузки клиентской библиотеки ознакомьтесь с разделом «Начало работы с библиотекой Python для данных Google», чтобы узнать, как установить и использовать клиент.
Запуск образца
Полный рабочий образец находится в подкаталоге 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 , который представляет собой клиентское соединение с классическим 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 .
Аутентификация в классическом API Сайтов
Клиентскую библиотеку Python можно использовать для работы как с общедоступными, так и с частными каналами. API данных Сайтов предоставляет доступ к частным и общедоступным каналам в зависимости от разрешений Сайта и операции, которую вы пытаетесь выполнить. Например, вы можете читать ленту контента общедоступного сайта, но не вносить в него обновления — для этого требуется клиент, прошедший проверку подлинности. Это можно сделать с помощью аутентификации по имени пользователя и паролю ClientLogin , AuthSub или OAuth .
Дополнительную информацию об AuthSub, OAuth и ClientLogin см. в обзоре аутентификации API данных Google .
AuthSub для веб-приложений
Аутентификация AuthSub для веб-приложений должна использоваться клиентскими приложениями, которым необходимо аутентифицировать своих пользователей в учетных записях Google или G Suite. Оператору не требуется доступ к логину и паролю пользователя Google Sites — требуется только токен AuthSub.
Просмотрите инструкции по включению AuthSub в ваше веб-приложение.
Запросить одноразовый токен
Когда пользователь впервые посещает ваше приложение, ему необходимо пройти аутентификацию. Обычно разработчики печатают некоторый текст и ссылку, направляющую пользователя на страницу утверждения AuthSub для аутентификации пользователя и запроса доступа к его документам. Клиентская библиотека Google Data Python предоставляет generate_auth_sub_url() для создания этого 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 — URL, на который Google перенаправит после того, как пользователь войдет в свою учетную запись и предоставит доступ;
http://www.example.com/myapp.pyв примере выше - объем —
https://sites.google.com/feeds/ - secure — логическое значение, указывающее, будет ли токен использоваться в безопасном и зарегистрированном режиме или нет;
Trueв примере выше - session — второе логическое значение, указывающее, будет ли одноразовый токен позже заменен на токен сеанса или нет;
Trueв примере выше
Обновление до токена сеанса
См. Использование AuthSub с клиентскими библиотеками API данных Google .
Получение информации о токене сеанса
См. Использование AuthSub с клиентскими библиотеками API данных Google .
Отзыв токена сеанса
См. Использование AuthSub с клиентскими библиотеками API данных Google .
Совет : как только ваше приложение успешно получит токен долговременного сеанса, сохраните этот токен в своей базе данных, чтобы вызвать его для дальнейшего использования. Нет необходимости отправлять пользователя обратно в AuthSub при каждом запуске вашего приложения. Используйте client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR) чтобы установить существующий токен на клиенте.
OAuth для веб-приложений или установленных/мобильных приложений
OAuth может использоваться как альтернатива AuthSub и предназначен для веб-приложений. OAuth аналогичен использованию безопасного и зарегистрированного режима AuthSub в том смысле, что все запросы данных должны быть подписаны цифровой подписью, и вы должны зарегистрировать свой домен.
Просмотрите инструкции по включению OAuth в установленное приложение.
Получение токена запроса
См. Использование OAuth с клиентскими библиотеками API данных Google .
Авторизация токена запроса
См. Использование OAuth с клиентскими библиотеками API данных Google .
Обновление до токена доступа
См. Использование OAuth с клиентскими библиотеками API данных Google .
Совет . После того как ваше приложение успешно получило токен доступа OAuth, сохраните этот токен в своей базе данных, чтобы вызвать его для дальнейшего использования. Нет необходимости отправлять пользователя обратно через OAuth при каждом запуске вашего приложения. Используйте client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET) чтобы установить существующий токен на клиенте.
ClientLogin для установленных/мобильных приложений
ClientLogin должен использоваться установленными или мобильными приложениями, которым необходимо аутентифицировать своих пользователей в учетных записях Google. При первом запуске ваше приложение запрашивает у пользователя имя пользователя и пароль. При последующих запросах используется токен аутентификации.
Просмотрите инструкции по включению ClientLogin в установленное приложение.
Чтобы использовать ClientLogin , вызовите метод ClientLogin() объекта SitesClient , который унаследован от GDClient . Укажите адрес электронной почты и пароль пользователя, от имени которого ваш клиент делает запросы. Например:
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1') client.ClientLogin('user@gmail.com', 'pa$$word', client.source);
Совет . После того как ваше приложение впервые успешно аутентифицирует пользователя, сохраните токен аутентификации в своей базе данных, чтобы его можно было использовать в дальнейшем. Нет необходимости запрашивать у пользователя пароль при каждом запуске вашего приложения. Дополнительную информацию см. в разделе «Вызов токена аутентификации» .
Дополнительную информацию об использовании ClientLogin в приложениях Python см. в разделе Использование ClientLogin с клиентскими библиотеками API данных 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
В приведенном выше фрагменте выводится заголовок сайта, имя сайта, сайт, с которого он был скопирован, и его 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 Sites установлен флажок «Опубликовать этот сайт как шаблон».
- Вы можете скопировать сайт из другого домена, пока вы не указаны в качестве владельца исходного сайта.
Обновление метаданных сайта
Чтобы обновить заголовок или краткое описание сайта, вам понадобится 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 . Каждая запись представляет собой отдельную страницу/элемент на Сайте пользователя и содержит элементы, специфичные для типа записи. См. пример приложения, чтобы получить лучшее представление о некоторых свойствах, доступных в каждом типе записи.
Примеры запросов к фиду контента
Вы можете выполнять поиск по ленте контента, используя некоторые стандартные параметры запроса 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)
Получение всех записей на родительской странице
Если вы знаете идентификатор записи контента страницы (например, «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 иметь заголовок страницы «Новый заголовок веб-страницы». То есть заголовок нормализуется до new-webpage-title для URL-адреса. Чтобы настроить URL-адрес страницы, вы можете установить свойство page_name в записи содержимого. Помощник CreatePage() предоставляет это как необязательный аргумент ключевого слова.
В этом примере создается новая страница filecabinet с заголовком «Хранилище файлов», но создается страница с URL-адресом http://sites.google.com/ domainName / siteName /files (вместо http://sites.google.com/ domainName / siteName /file-storage . 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-пути страницы:
-
page_name, если присутствует. Должно удовлетворятьaz, AZ, 0-9, -, _. -
titleне должно быть нулевым, если имя страницы отсутствует. Нормализация заключается в обрезке + свертывании пробелов до '-' и удалении символов, не соответствующихaz, AZ, 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 найденный в канале контента пользователя. Вложение создается с заголовком «Справочник нового сотрудника» и (необязательным) описанием «Пакет 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 Sites поддерживают папки. 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 найденным в канале контента пользователя. Для его заголовка и (необязательного) описания установлены значения «Логотип Google» и «приятные цвета» соответственно.
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-контента страницы.
Метаданные (заголовок, имя страницы и т. д.) и содержимое страницы любого типа можно редактировать с помощью клиентского метода 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)
Дополнительную информацию об ETags см. в справочном руководстве по API данных Google .
Загрузка вложений
Каждая запись attachment содержит ссылку src содержимого, которую можно использовать для загрузки содержимого файла. Клиент Сайтов содержит вспомогательный метод для доступа и загрузки файла по этой ссылке: DownloadAttachment() . Он принимает gdata.sites.data.ContentEntry или URI загрузки в качестве первого аргумента и путь к файлу для сохранения вложения в качестве второго.
В этом примере извлекается определенная запись вложения (путем запроса его 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. Таким образом, администраторы домена не будут показаны, даже если они имеют неявный доступ к сайту.
Роли
Элемент role представляет уровень доступа, который может иметь сущность. Существует четыре возможных значения элемента gAcl:role :
- reader — средство просмотра (эквивалентно доступу только для чтения).
- писатель — соавтор (эквивалент доступа на чтение/запись).
- владелец — обычно администратор сайта (эквивалент доступа на чтение/запись).
Области применения
Элемент области представляет объект, имеющий этот уровень доступа. Существует четыре возможных типа элемента gAcl:scope :
- user — значение адреса электронной почты, например «user@gmail.com».
- группа — адрес электронной почты группы Google, например «group@domain.com».
- Домен — доменное имя 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())
Совместное использование сайта
Примечание . Некоторые списки управления доступом могут быть возможны только в том случае, если домен настроен на разрешение таких разрешений (например, если включен общий доступ за пределами домена для доменов 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 может совместно использовать весь сайт только с доменом1.com, а не с доменом2.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)
Дополнительную информацию об ETags см. в справочном руководстве по API данных Google .
Удаление разрешений на общий доступ
Чтобы удалить разрешение на общий доступ, сначала получите 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)
Дополнительную информацию об ETags см. в справочном руководстве по API данных Google .
Специальные темы
Повторное получение ленты или записи
Если вы хотите получить ранее полученный канал или запись, вы можете повысить эффективность, указав серверу отправлять список или запись только в том случае, если они изменились с момента последнего получения.
Чтобы выполнить такой условный поиск, передайте значение 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 , и исключение не будет выдано.
Дополнительную информацию об ETags см. в справочном руководстве по API данных Google .