Importante:este documento foi escrito antes de 2012. As opções de autenticação descritas neste documento (OAuth 1.0, Twilio e gclid) foram oficialmente descontinuadas em 20 de abril de 2012 e não estão mais disponíveis. Recomendamos que você migre para o OAuth 2.0 assim que possível.
A API de dados do Google Sites permite que aplicativos clientes acessem, publiquem e modifiquem conteúdo em um site Google. Seu aplicativo cliente também pode solicitar uma lista das atividades recentes, buscar o histórico de revisões e fazer o download de anexos.
Além de fornecer informações sobre os recursos da API Sites Data, este guia fornece exemplos para interagir com a API usando a biblioteca de cliente Python. Para receber ajuda ao configurar a biblioteca de cliente, consulte Primeiros passos com a biblioteca de cliente Python de dados do Google. Para saber mais sobre o protocolo subjacente usado pela biblioteca de cliente Python para interagir com a API Sites clássica, consulte o guia de protocolos.
Público-alvo
Este documento é para desenvolvedores que gostariam de criar aplicativos clientes que interagem com o Google Sites usando a biblioteca de cliente Python de dados do Google.
Como começar
Para usar a biblioteca de cliente Python, você precisa do Python 2.2+ e dos módulos listados na página wiki DependencyModules. Depois de fazer o download da biblioteca de cliente, consulte Primeiros passos com a biblioteca de dados do Google para Python para receber ajuda com a instalação e o uso do cliente.
Como executar a amostra
Uma amostra completa de trabalho está localizada no subdiretório samples/sites do repositório Mercurial do projeto (/samples/sites/sites_example.py).
Execute o exemplo da seguinte maneira:
python sites_example.py # or python sites_example.py --site [sitename] --domain [domain or "site"] --debug [prints debug info if set]
Se as flags necessárias não forem fornecidas, o app vai pedir para você inserir esses valores. No exemplo, o usuário pode realizar várias operações que demonstram como usar a API Sites clássico. Dessa forma, é preciso fazer a autenticação para realizar determinadas operações (por exemplo, modificar conteúdo). O programa também solicitará que você faça a autenticação via AuthSub, OAuth ou ClientLogin.
Para incluir os exemplos neste guia no seu próprio código, você vai precisar das seguintes instruções import:
import atom.data import gdata.sites.client import gdata.sites.data
Também será necessário configurar um objeto SitesClient, que representa uma conexão de cliente com a API Sites clássico.
Informe o nome do seu aplicativo e o nome do espaço web do site (do seu URL):
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName')
Para trabalhar com um site hospedado em um domínio do G Suite, defina o domínio usando o parâmetro domain:
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName', domain='example.com')
Nos snippets acima, o argumento source é opcional, mas é recomendado para fins de geração de registros. Ele precisa
seguir este formato: company-applicationname-version
Observação: o restante do guia pressupõe que você criou um objeto SitesClient na variável client.
Como autenticar na API Sites clássico
A biblioteca de cliente Python pode ser usada para trabalhar com feeds públicos ou privados. A API Sites Data fornece acesso a feeds privados e públicos, dependendo das permissões de um site e da operação que você está tentando realizar. Por exemplo, você pode ler o feed de conteúdo de um site público, mas não fazer atualizações nele, algo que requer um cliente autenticado. Isso pode ser feito por meio da autenticação de nome de usuário/senha do ClientLogin, AuthSub ou OAuth.
Consulte a Visão geral da autenticação das APIs de dados do Google para obter mais informações sobre Twilio, OAuth e ChromeVox.
AuthSub para aplicativos da web
A autenticação Kerberos para aplicativos da Web (em inglês) deve ser usada por aplicativos clientes que precisam autenticar os usuários em contas do Google ou do G Suite. O operador não precisa de acesso ao nome de usuário e senha do usuário do Google Sites, apenas um token gclid é necessário.
Veja instruções para incorporar o EDGE ao seu aplicativo da Web
Solicitar um token de uso único
Quando o usuário acessa seu aplicativo pela primeira vez, ele precisa fazer a autenticação. Normalmente, os desenvolvedores imprimem alguns textos e um link que direcionam o usuário para a página de aprovação do Velostrata para autenticar o usuário e solicitar acesso aos documentos. A biblioteca de cliente Python de dados do Google fornece uma função, generate_auth_sub_url(), para gerar esse URL. O código abaixo configura um link para a página 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()
Se você quiser autenticar usuários em um domínio hospedado do G Suite, transmita o nome do domínio para 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)
O método generate_auth_sub_url() usa vários parâmetros, que correspondem aos parâmetros de consulta usados pelo gerenciador AuthSubRequest:
- O próximo URL: URL para o qual o Google irá redirecionar
depois que o usuário fizer login na conta e conceder acesso.
http://www.example.com/myapp.pyno exemplo acima - do escopo:
https://sites.google.com/feeds/ - secure: é um booleano para indicar se o token vai ser usado no modo seguro e registrado (link em inglês).
Trueno exemplo acima. - session, um segundo booleano para indicar se o token de uso único será trocado posteriormente por um token de sessão ou não.
Trueno exemplo acima
Como fazer upgrade para um token de sessão
Consulte Como usar o Velostrata com as bibliotecas de cliente da API de dados do Google.
Como recuperar informações sobre um token de sessão
Consulte Como usar o Velostrata com as bibliotecas de cliente da API de dados do Google.
Como revogar um token de sessão
Consulte Como usar o Velostrata com as bibliotecas de cliente da API de dados do Google.
Dica: depois que seu aplicativo adquirir um token de sessões de longa duração,
armazene-o no banco de dados e lembre-o para uso posterior. Não é necessário enviar o usuário de volta para PERMISSION sempre que o aplicativo for executado.
Use client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR) para definir um token atual no cliente.
OAuth para aplicativos da Web ou instalados/dispositivos móveis
OAuth pode ser usado como uma alternativa para EDGE e se destina a aplicativos da Web. O OAuth é semelhante ao uso do modo seguro e registrado (link em inglês) de Twilio, em que todas as solicitações de dados precisam ser assinadas digitalmente, e você precisa registrar seu domínio.
Veja instruções para incorporar o OAuth ao aplicativo instalado
Como buscar um token de solicitação
Consulte Como usar o OAuth com as bibliotecas de cliente da API Google Data.
Como autorizar um token de solicitação
Consulte Como usar o OAuth com as bibliotecas de cliente da API Google Data.
Como fazer upgrade para um token de acesso
Consulte Como usar o OAuth com as bibliotecas de cliente da API Google Data.
Dica: depois que o aplicativo adquirir um token de acesso OAuth, armazene-o no seu banco de dados para recuperar para uso posterior. Não é necessário enviar o usuário de volta por meio do OAuth em cada execução do seu aplicativo.
Use client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET) para definir um token atual no cliente.
GCLID para aplicativos instalados/móveis
ClientLogin é usado por aplicativos instalados ou móveis que precisam autenticar seus usuários nas Contas do Google. Na primeira execução, o aplicativo solicita ao usuário o nome de usuário e a senha. Nas solicitações subsequentes, um token de autenticação será referenciado.
Veja instruções para incorporar o GCLID a seu aplicativo instalado
Para usar o ClientLogin, invoque o método
ClientLogin()
do objeto SitesClient, que é herdado de
GDClient. Especifique o endereço de e-mail e
a senha do usuário em nome de quem o cliente está fazendo solicitações. Exemplo:
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1') client.ClientLogin('user@gmail.com', 'pa$$word', client.source);
Dica: depois que seu aplicativo autenticar o usuário pela primeira vez, armazene o token de autenticação no banco de dados para consultar depois. Não é necessário solicitar a senha do usuário sempre que o aplicativo for executado. Consulte Como chamar um token de autenticação para mais informações.
Para obter mais informações sobre o uso de gclid em seus aplicativos em Python, consulte Como usar vet com as bibliotecas de cliente da API de dados do Google.
Feed do site
O feed de site pode ser usado para listar os Google Sites de que um usuário é proprietário ou tem permissões de visualização. Ela também pode ser usada para modificar o nome de um site existente. Por fim, para domínios do G Suite, ele também pode ser usado para criar e/ou copiar um site inteiro.
Sites de listagem
Para listar os sites a que o usuário tem acesso, use o método GetSiteFeed() do cliente. O método usa um argumento opcional, uri, que você pode usar para especificar um URI de feed de site alternativo. Por padrão, o GetSiteFeed() usa o nome do site e o domínio definidos no objeto cliente. Consulte a seção Como começar para mais informações sobre como definir esses valores no objeto do cliente.
Veja um exemplo de como buscar a lista de sites do usuário autenticado:
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
O snippet acima imprime o título e o nome do site, o site do qual foi copiado e o URI de feed da ACL do site.
Criação de sites
Observação: esse recurso só está disponível para domínios do G Suite.
Novos sites podem ser provisionados chamando o método CreateSite() da biblioteca.
Assim como o auxiliar GetSiteFeed(), CreateSite() também aceita um argumento opcional, uri, que pode ser usado para especificar um URI de feed de site alternativo, no caso de criação do site em um domínio diferente daquele definido no objeto SitesClient.
Veja um exemplo de como criar um novo site com o tema "barreira" e fornecer um título e uma descrição (opcional):
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
A solicitação acima criaria um novo site com o domínio do G Suite example2.com.
Assim, o URL do site seria https://sites.google.com/a/exemplo2.com/título-para-meu-site.
Se o site for criado, o servidor responderá com um objeto gdata.sites.data.SiteEntry, preenchido com elementos adicionados pelo servidor: um link para o site, um link para o feed da ACL do site, o nome do site, o título, o resumo e assim por diante.
Como copiar um site
Observação: esse recurso só está disponível para domínios do G Suite.
CreateSite() também pode ser usado para copiar um site existente. Para fazer isso, transmita o argumento de palavra-chave source_site.
Todos os sites copiados terão esse link, que pode ser acessado em entry.FindSourceLink(). Veja um exemplo de duplicação do site criado na seção Criar novos sites:
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
Pontos importantes:
- Somente sites e modelos de sites que pertencem ao usuário autenticado podem ser copiados.
- Também é possível copiar um modelo de site. Um site é um modelo se a configuração "Publicar este site como um modelo" estiver marcada na página de configurações do Google Sites.
- Você pode copiar um site de outro domínio enquanto não estiver listado como proprietário no site de origem.
Como atualizar os metadados de um site
Para atualizar o título ou o resumo de um site, você precisa de um SiteEntry com o site em questão. Este
exemplo usa o método GetEntry() para buscar um SiteEntry e, em seguida, mudar o título, a descrição e a tag de categoria dele:
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)
Como buscar o feed de atividades
Observação: o acesso a esse feed requer que você seja um colaborador ou proprietário do site. Seu cliente deve autenticar usando um token gclid, OAuth ou ChromeVox. Consulte Como autenticar no serviço do Google Sites.
Você pode buscar as atividades recentes de um site (alterações) buscando o feed de atividades.
O método GetActivityFeed() da biblioteca fornece acesso a esse feed:
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)
Chamar GetActivityFeed() retorna um objeto gdata.sites.data.ActivityFeed que contém uma lista de
gdata.sites.data.ActivityEntry. Cada entrada de atividade contém
informações sobre uma mudança feita no site.
Buscando histórico de revisões
Observação: o acesso a esse feed requer que você seja um colaborador ou proprietário do site. Seu cliente deve autenticar usando um token gclid, OAuth ou ChromeVox. Consulte Como autenticar no serviço do Google Sites.
O feed de revisões fornece informações sobre o histórico de revisões de qualquer entrada de conteúdo. O método
GetRevisionFeed() pode ser usado para buscar as revisões de uma determinada entrada de conteúdo. O método usa um parâmetro uri
opcional que aceita um gdata.sites.data.ContentEntry, um URI completo de uma entrada de conteúdo ou um ID de entrada de conteúdo.
Este exemplo consulta o feed de conteúdo e busca o feed de revisão para a primeira entrada de conteúdo:
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]
Chamar GetRevisionFeed() retorna um objeto gdata.sites.data.RevisionFeed que contém uma lista de
gdata.sites.data.RevisionEntry. Cada entrada de revisão contém informações como o conteúdo
dessa revisão, o número da versão e quando a nova versão foi criada.
Feed de conteúdo
Como recuperar o feed de conteúdo
Observação: o feed de conteúdo pode ou não exigir autenticação, dependendo das permissões de compartilhamento do site. Se o site não for público, o seu cliente deverá fazer a autenticação usando um token EDGE, OAuth ou gclid. Consulte Como autenticar no serviço do Google Sites.
O feed de conteúdo retorna o conteúdo mais recente de um site. Ela pode ser acessada chamando o método
GetContentFeed() da biblioteca, que usa um parâmetro de string uri opcional para transmitir
uma consulta personalizada.
Veja um exemplo de busca de todo o feed de conteúdo e de impressão de alguns elementos interessantes:
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
Dica: o entry.Kind() pode ser usado para determinar o tipo de uma entrada.
O objeto feed resultante é um gdata.sites.data.ContentFeed que contém uma lista
de gdata.sites.data.ContentEntry. Cada entrada representa uma página/item diferente no site do usuário e tem elementos específicos para o tipo de entrada. Consulte o aplicativo de exemplo para ter uma ideia melhor de algumas das propriedades disponíveis em cada tipo de entrada.
Exemplos de consulta de feed de conteúdo
Você pode pesquisar o feed de conteúdo usando alguns dos parâmetros de consulta padrão da API Google Data e alguns específicos da API Sites clássica. Para informações mais detalhadas e uma lista completa de parâmetros compatíveis, consulte o Guia de referência.
Observação: os exemplos nesta seção usam o método auxiliar gdata.sites.client.MakeContentFeedUri()
para criar o URI de base do feed de conteúdo.
Como recuperar tipos de entrada específicos
Para buscar apenas um tipo específico de entrada, use o parâmetro kind. Como exemplo, este snippet retorna apenas entradas attachment:
kind = 'webpage' print 'Fetching only %s entries' % kind uri = '%s?kind=%s' % (client.MakeContentFeedUri(), kind) feed = client.GetContentFeed(uri=uri)
Para retornar mais de um tipo, separe cada kind com uma vírgula. Por exemplo, este snippet retorna entradas filecabinet e listpage:
kind = ','.join(['filecabinet', 'listpage']) print 'Fetching only %s entries' % kind uri = '%s?kind=%s' % (client.MakeContentFeedUri(), kind) feed = client.GetContentFeed(uri=uri)
Como recuperar uma página por caminho
Se você souber o caminho relativo de uma página no site Google, poderá usar o parâmetro path para buscar essa página específica.
Este exemplo retornaria a página localizada em
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)
Como recuperar todas as entradas em uma página pai
Se você conhece o ID de entrada de conteúdo de uma página (por exemplo, "1234567890" no exemplo abaixo), é possível usar o parâmetro parent para buscar todas as entradas filhas (se houver):
parent = '1234567890' print 'Fetching all children of parent entry: ' + parent uri = '%s?parent=%s' % (client.MakeContentFeedUri(), parent) feed = client.GetContentFeed(uri=uri)
Para parâmetros adicionais, consulte o Guia de referência.
Criação de conteúdo
Observação:antes de criar conteúdo para um site, verifique se você configurou o site no cliente.client.site = "siteName"
É possível criar conteúdo novo (páginas da Web, listas, arquivos, páginas de avisos etc.) usando o CreatePage().
O primeiro argumento para esse método deve ser o tipo de página a ser criada, seguido pelo título e seu conteúdo HTML.
Para ver uma lista de tipos de nós compatíveis, consulte o parâmetro kind no Guia de referência.
Criar novos itens / páginas
Este exemplo cria um novo webpage no nível superior, inclui um código HTML para o corpo da página
e define o título do cabeçalho como "New WebPage Title":
entry = client.CreatePage('webpage', 'New WebPage Title', html='<b>HTML content</b>')
print 'Created. View it at: %s' % entry.GetAlternateLink().href
Se a solicitação for bem-sucedida, entry terá uma cópia da entrada criada no servidor, como um gdata.sites.gdata.ContentEntry.
Para criar um tipo de entrada mais complexo que seja preenchido na criação (por exemplo, um listpage com cabeçalhos de coluna), crie
o gdata.sites.data.ContentEntry manualmente, preencha as propriedades de interesse e chame client.Post().
Como criar itens/páginas em caminhos de URL personalizados
Por padrão, o exemplo anterior seria criado sob o URL
http://sites.google.com/domainName/siteName/new-webpage-title e
teria o cabeçalho "Novo título da página da Web". Ou seja, o título é normalizado para new-webpage-title no URL.
Para personalizar o caminho do URL de uma página, defina a propriedade page_name na entrada do conteúdo. O auxiliar CreatePage()
fornece esse argumento como um argumento de palavra-chave opcional.
Este exemplo cria uma nova página filecabinet com o cabeçalho "Armazenamento de arquivos", mas cria a página no URL http://sites.google.com/domainName/siteName/files (em vez de http://sites.google.com/domainName/siteName/file-storage) especificando a propriedade page_name.
entry = client.CreatePage('filecabinet', 'File Storage', html='<b>HTML content</b>', page_name='files')
print 'Created. View it at: ' + entry.GetAlternateLink().href
O servidor usa as seguintes regras de precedência para nomear o caminho do URL de uma página:
page_name, se presente. Precisa atender aa-z, A-Z, 0-9, -, _.titlenão poderá ser nulo se o nome da página não estiver presente. A normalização consiste em cortar e recolher o espaço em branco para "-" e remover os caracteres que não correspondem aa-z, A-Z, 0-9, -, _.
Como criar subpáginas
Para criar subpáginas (filhos) em uma página mãe, use o argumento de palavra-chave parent de CreatePage().
O parent pode ser um gdata.sites.gdata.ContentEntry ou uma string que representa o
self id completo da entrada do conteúdo.
Este exemplo consulta o feed de conteúdo para announcementpages e cria um novo announcement abaixo do primeiro que for encontrado:
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!'
Como fazer upload de arquivos
Assim como no Google Sites, a API é compatível com uploads de anexos para uma página de arquivo ou uma página principal. É necessário fazer o upload dos anexos para uma página pai. Portanto, defina um link pai no ContentEntry que você está tentando enviar. Consulte Como criar subpáginas para mais informações.
O método UploadAttachment() da biblioteca de cliente fornece a interface para fazer upload de anexos.
Fazendo upload dos anexos
Este exemplo faz o upload de um arquivo PDF para a primeira filecabinet encontrada no feed de conteúdo do usuário.
O anexo é criado com o título "Manual do novo funcionário" e uma descrição (opcional), "Pacote de RH".
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
Se o upload der certo, attachment terá uma cópia do anexo criado no servidor.
Fazer upload de um anexo para uma pasta
Os arquivos no Google Sites são compatíveis com as pastas. O UploadAttachment() fornece um argumento de palavra-chave
extra, folder_name, que você pode usar para fazer upload de um anexo em uma pasta filecabinet. Basta especificar o nome da pasta:
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')
Este exemplo transmite um objeto gdata.data.MediaSource para UploadAttachment() em vez
de um caminho de arquivo. Ele também não transmite um tipo de conteúdo. Em vez disso, o tipo de conteúdo é especificado no objeto MediaSource.
Anexos da Web
Anexos da Web são tipos especiais de anexos. Basicamente, eles são links para outros arquivos na Web
que você pode adicionar às listagens filecabinet. Esse recurso é análogo ao método de upload "Adicione arquivo por URL" na interface do Google Sites.
Observação: anexos da Web só podem ser criados em filecabinet. Eles não podem ser enviados para outros tipos de página.
Este exemplo cria um anexo da Web na primeira filecabinet encontrada no feed de conteúdo do usuário.
O título e a descrição (opcional) são definidos como "GoogleLogo" e "nice cores", respectivamente.
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!'
A chamada cria um link que aponta para a imagem em "http://www.google.com/images/logo.gif" no filecabinet.
Atualizar conteúdo
Atualizar os metadados e/ou o conteúdo HTML de uma página
Os metadados (título, pageName etc.) e o conteúdo da página de qualquer tipo de entrada podem ser editados usando o método Update() do cliente.
Confira abaixo um exemplo de atualização de um listpage com as seguintes mudanças:
- O título é modificado para "Título atualizado"
- O conteúdo HTML da página foi atualizado para "Conteúdo HTML atualizado"
- O primeiro cabeçalho de coluna da lista é alterado para "Proprietário"
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!'
Substituir o conteúdo e os metadados de um anexo
Para substituir o conteúdo do arquivo de um anexo, crie um novo objeto MediaSource
com o novo conteúdo do arquivo e chame o método Update() do cliente. Os metadados
do anexo (como título e descrição) também podem ser atualizados ou simplesmente os metadados.
Este exemplo demonstra a atualização do conteúdo do arquivo e dos metadados ao mesmo tempo:
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)
Exclusão de conteúdo
Para remover uma página ou um item de um site Google, primeiro recupere a entrada de conteúdo e chame o método Delete() do cliente.
client.Delete(content_entry)
Também é possível transmitir ao método Delete() o link edit da entrada do conteúdo e/ou forçar a exclusão:
# force=True sets the If-Match: * header instead of using the entry's ETag. client.Delete(content_entry.GetEditLink().href, force=True)
Para mais informações sobre ETags, consulte o Guia de referência das APIs de dados do Google.
Fazendo o download de anexos
Cada entrada attachment contém um link src de conteúdo, que pode ser usado para fazer o download do arquivo.
O cliente do Google Sites contém um método auxiliar para acessar e fazer o download do arquivo por este link: DownloadAttachment().
Ele aceita um URI de download ou gdata.sites.data.ContentEntry para o primeiro argumento e um caminho de arquivo para salvar o anexo
como o segundo.
Este exemplo busca uma entrada de anexo específica (consultando o link self) e faz o download do arquivo para o caminho especificado:
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!'
Cabe ao desenvolvedor do aplicativo especificar uma extensão de arquivo que faça sentido para o tipo de conteúdo do anexo. O tipo de conteúdo pode ser encontrado em entry.content.type.
Em alguns casos, pode não ser possível fazer o download do arquivo para o disco (por exemplo, se o aplicativo estiver sendo executado no Google App Engine).
Nessas situações, use _GetFileContent() para buscar e armazenar o conteúdo do arquivo na memória.
Este download de exemplo é um anexo à memória.
try: file_contents = client._GetFileContent(attachment.content.src) # TODO: Do something with the file contents except gdata.client.RequestError, e: raise e
Feed da ACL
Visão geral das permissões de compartilhamento (ACLs)
Cada entrada no feed da ACL representa uma função de acesso de uma entidade específica, seja um usuário, um grupo de usuários, um domínio ou o acesso padrão (que é um site público). As entradas serão exibidas apenas para entidades com acesso explícito: uma entrada será mostrada para cada endereço de e-mail no painel "Pessoas com acesso" na tela de compartilhamento da interface do Google Sites. Assim, os administradores de domínio não serão mostrados, mesmo que tenham acesso implícito a um site.
Papéis
O elemento role representa um nível de acesso que uma entidade pode ter. Há quatro valores possíveis para o elemento gAcl:role:
- reader: um visualizador (equivalente ao acesso somente leitura).
- writer: um colaborador (equivalente ao acesso de leitura/gravação).
- owner: normalmente, o administrador do site (equivalente ao acesso de leitura/gravação).
Escopos
O elemento de escopo representa a entidade que tem esse nível de acesso. Há quatro tipos possíveis do elemento gAcl:scope:
- user: um valor de endereço de e-mail, por exemplo, "user@gmail.com".
- group: um endereço de e-mail do Grupo do Google, por exemplo, "grupo@dominio.com".
- domínio: um nome de domínio do G Suite, por exemplo, "domínio.com".
- default: há apenas um escopo possível do tipo "default", que não tem valor (por exemplo,
<gAcl:scope type="default">). Esse escopo específico controla o acesso que qualquer usuário tem por padrão em um site público.
Observação: os domínios não podem ter um valor gAcl:role
definido como acesso de "proprietário". Eles só podem ser leitores ou gravadores.
Como recuperar o feed da ACL
O feed da ACL pode ser usado para controlar as permissões de compartilhamento de um site e pode ser buscado usando o método GetAclFeed().
O exemplo a seguir busca o feed de ACL do site atualmente definido no objeto SitesClient e imprime as entradas de permissão:
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)
Após uma consulta bem-sucedida, feed será um objeto gdata.sites.data.AclFeed contendo uma listagem de gdata.sites.data.AclEntry.
Se você estiver trabalhando com entradas no SiteFeed, cada SiteEntry conterá um link para seu feed da ACL.
Por exemplo, este snippet busca o primeiro site no feed do site do usuário e consulta o feed da 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())
Como compartilhar um site
Observação: algumas ACLs de compartilhamento só serão possíveis se o domínio estiver configurado para conceder essas permissões. Por exemplo, se o compartilhamento fora do domínio para domínios do G Suite estiver ativado etc.
Para compartilhar um site Google usando a API, crie um gdata.sites.gdata.AclEntry com os valores gdata.acl.data.AclScope e gdata.acl.data.AclRole desejados. Consulte a seção Visão geral do feed da ACL para ver os possíveis valores AclScope e AclRoles.
Este exemplo concede permissões de leitura no site para o usuário "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)
Compartilhamento no nível do grupo e do domínio
De forma semelhante ao compartilhamento de um site com um único usuário, o compartilhamento pode ser feito em um grupo do Google ou domínio do G Suite. Os valores scope necessários estão listados abaixo.
Como compartilhar com um endereço de e-mail de grupo:
scope = gdata.acl.data.AclScope(value='group_name@example.com', type='group')
Compartilhamento com um domínio inteiro:
scope = gdata.acl.data.AclScope(value='example.com', type='domain')
O compartilhamento no nível do domínio só é compatível com domínios do G Suite e apenas com o domínio em que o site está hospedado. Por exemplo, http://sites.google.com/a/domain1.com/siteA só pode compartilhar o site inteiro com dominio1.com, não com dominio2.com. Sites que não estejam hospedados em um domínio do G Suite (por exemplo, http://sites.google.com/site/siteB) não podem convidar domínios.
Modificar permissões de compartilhamento
Para uma permissão de compartilhamento em um site, primeiro busque a AclEntry em questão, modifique a permissão como quiser e chame o método Update() do cliente para modificar a ACL no servidor.
Este exemplo modifica nosso acl_entry anterior da seção Como compartilhar um site, atualizando "user@example.com" para ser um escritor (colaborador):
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)
Para mais informações sobre ETags, consulte o Guia de referência das APIs de dados do Google.
Removendo permissões de compartilhamento
Para remover uma permissão de compartilhamento, primeiro recupere o AclEntry e, em seguida, chame o método Delete() do cliente.
client.Delete(acl_entry)
Também é possível transmitir o método Delete() do link edit da entrada da ACL e/ou forçar a exclusão:
# force=True sets the If-Match: * header instead of using the entry's ETag. client.Delete(acl_entry.GetEditLink().href, force=True)
Para mais informações sobre ETags, consulte o Guia de referência das APIs de dados do Google.
Temas especiais
Como recuperar um feed ou uma entrada novamente
Se você quiser recuperar um feed ou uma entrada recuperada anteriormente, poderá melhorar a eficiência solicitando que o servidor envie a lista ou a entrada somente se ela tiver sido alterada desde a última vez em que você a recuperou.
Para fazer esse tipo de recuperação condicional, transmita um valor de ETag para o GetEntry(). Por exemplo, se você tiver um objeto 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
Se GetEntry() gerar a exceção gdata.client.NotModified, a ETag da entrada vai corresponder à versão no servidor, o que significa que você tem a cópia mais atualizada.
No entanto, se outro cliente/usuário tiver feito modificações, a nova entrada será retornada em entry e nenhuma exceção será gerada.
Para mais informações sobre ETags, consulte o Guia de referência das APIs de dados do Google.