Importante:este documento foi escrito antes de 2012. As opções de autenticação descritas neste documento (OAuth 1.0, tmp e ClientLogin) foram suspensas oficialmente 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 os aplicativos cliente acessem, publiquem e modifiquem conteúdo em um site Google. Seu aplicativo cliente também pode solicitar uma lista de atividades recentes, buscar o histórico de revisões e fazer o download de anexos.
Além de fornecer algumas informações sobre os recursos da API de dados do site, este guia fornece exemplos para interagir com a API usando a biblioteca de cliente do Python. Se precisar de ajuda para configurar a biblioteca de cliente, consulte Primeiros passos com a biblioteca de cliente Python de dados do Google. Se você quiser saber mais sobre o protocolo usado pela biblioteca de cliente Python para interagir com a API Sites clássica, consulte o guia de protocolo.
Público-alvo
Este documento é para os desenvolvedores criarem aplicativos clientes que interajam com o Google Sites usando a Biblioteca de cliente Python de dados do Google.
Primeiros passos
Para usar a biblioteca de cliente Python, você precisará do Python 2.2+ e dos módulos listados na página de wiki DependencyModules. Depois de fazer o download da biblioteca de cliente, consulte Primeiros passos com a biblioteca Python de dados do Google 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 sinalizações necessárias não forem fornecidas, o app solicitará que você insira esses valores. O exemplo permite que o usuário realize várias operações que demonstram como usar a API Sites clássica. Por isso, é preciso fazer a autenticação para realizar determinadas operações, como modificar conteúdo. O programa também solicitará que você faça a autenticação via XPN, OAuth ou ClientLogin.
Para incluir os exemplos neste guia no seu próprio código, você precisará das seguintes instruções import:
import atom.data import gdata.sites.client import gdata.sites.data
Você também vai precisar configurar um objeto SitesClient, que representa uma conexão de cliente com a API Sites clássica.
Transmita o nome do seu aplicativo e o nome do espaço Web do site (no URL):
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName')
Para trabalhar em 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 geração de registros. Ele precisa
seguir este formato: company-applicationname-version
Observação: o restante do guia considera que você criou um objeto SitesClient na variável client.
Como autenticar na API Sites clássica
A biblioteca de cliente Python pode ser usada para trabalhar com feeds públicos ou privados. A API Sites Data fornece acesso a feeds públicos e particulares, dependendo das permissões do 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 pode fazer atualizações nele, algo que requer um cliente autenticado. Isso pode ser feito usando a autenticação de nome de usuário/senha do ClientLogin, o tmp ou o OAuth.
Consulte Visão geral da autenticação das APIs de dados do Google para mais informações sobre tmp, OAuth e ClientLogin.
AuthSub para aplicativos da web
A autenticação do tmp para apps da Web deve ser usada por apps cliente que precisem 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 tmp é necessário.
Veja instruções para incorporar o XPN em 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 um texto e um link que direciona o usuário
para a página de aprovação do SMTP, 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 tmpRequest.
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 no G Suite, transmita o nome de 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 (correspondentes aos parâmetros de consulta usados pelo gerenciador tmpRequest):
- o próximo URL: URL ao qual o Google vai redirecionar
depois que o usuário fizer login na conta e conceder acesso;
http://www.example.com/myapp.pyno exemplo acima - o escopo —
https://sites.google.com/feeds/ - secure, um valor booleano que indica se o token será usado no modo seguro e registrado ou não.
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 tmp com as bibliotecas de cliente da API Google Data.
Como recuperar informações sobre um token de sessão
Consulte Como usar tmp com as bibliotecas de cliente da API Google Data.
Revogar um token de sessão
Consulte Como usar tmp com as bibliotecas de cliente da API Google Data.
Dica: depois que o aplicativo adquirir com êxito um token de sessões de longa duração, armazene esse token no seu banco de dados para uso posterior. Não é necessário enviar o usuário de volta para o ConfigMap em cada execução do aplicativo.
Use client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR) para definir um token atual no cliente.
OAuth para aplicativos da Web ou instalados/para dispositivos móveis
O OAuth pode ser usado como uma alternativa para o tmp. Ele é destinado a aplicativos da Web. O OAuth é parecido com o uso do modo seguro e registrado do ISBN, 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 recall para uso posterior. Não é necessário enviar o usuário de volta pelo OAuth em cada execução do aplicativo.
Use client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET) para definir um token atual no cliente.
ClientLogin para aplicativos instalados/móveis
O ClientLogin deve ser usado por aplicativos instalados ou móveis que precisem autenticar seus usuários em Contas do Google. Na primeira execução, seu aplicativo solicita ao usuário seu nome de usuário/senha. Nas próximas solicitações, um token de autenticação será referenciado.
Ver instruções para incorporar ClientLogin no aplicativo instalado
Para usar 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 seu 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 o aplicativo autenticar o usuário pela primeira vez, armazene o token de autenticação no banco de dados para usar novamente. Não é necessário solicitar a senha do usuário em cada execução do aplicativo. Consulte Como recuperar um token de autenticação para mais informações.
Para mais informações sobre como usar o ClientLogin nos seus aplicativos Python, consulte Como usar o ClientLogin com as bibliotecas de cliente da API Google Data.
Feed do site
O feed pode ser usado para listar os sites Google de que um usuário é proprietário ou tem permissões de visualização. Ele também pode ser usado 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.
Como listar sites
Para listar os sites a que um usuário tem acesso, use o método GetSiteFeed() do cliente. O método usa um argumento opcional, uri, que pode ser usado 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 do cliente. Consulte a seção Primeiros passos para
mais informações sobre como definir esses valores no objeto 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 mostra o título, o nome, o site de onde foi copiado e o URI do feed acl.
Criar novos sites
Observação: esse recurso só está disponível nos domínios do G Suite.
Novos sites podem ser provisionados chamando o método CreateSite() da biblioteca.
Semelhante ao auxiliar GetSiteFeed(), o CreateSite() também aceita um
argumento opcional, uri, que você pode usar para especificar um URI de feed de site alternativo (no caso de criar
o site em um domínio diferente daquele que está 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 no domínio do G Suite example2.com.
Assim, o URL do site seria https://sites.google.com/a/example2.com/title-for-my-site.
Se o site for criado com sucesso, o servidor vai responder com um objeto gdata.sites.data.SiteEntry, preenchido com elementos adicionados por ele: um link para o site, um link para o feed acl do site, o nome do site, o título, o resumo e assim por diante.
Copiar um site
Observação: esse recurso só está disponível nos domínios do G Suite.
O CreateSite() também pode ser usado para copiar um site existente. Para fazer isso, transmita o argumento de palavra-chave source_site.
Qualquer site que tenha sido copiado terá esse link, que pode ser acessado por entry.FindSourceLink(). Veja um exemplo de como duplicar o 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:
- Só é possível copiar sites e modelos de site de propriedade do usuário autenticado.
- Também é possível copiar um modelo de site. Um site será um modelo se a configuração "Publicar este site como modelo" estiver marcada na página de configurações do Google Sites.
- Você pode copiar um site de outro domínio, desde que esteja listado como proprietário no site de origem.
Como atualizar metadados de um site
Para atualizar o título ou o resumo de um site, você precisará de uma SiteEntry contendo o site em questão. Este
exemplo usa o método GetEntry() para buscar primeiro um SiteEntry e, em seguida, muda o título, a descrição e a tag de categoria:
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)
Buscando o feed de atividades
Observação: para acessar esse feed, você precisa ser colaborador ou proprietário do site. O cliente precisa fazer a autenticação usando um token tmp, OAuth ou ClientLogin. Consulte Como autenticar no serviço do Google Sites.
Você pode buscar a atividade recente (alterações) de um site 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 o histórico de revisões
Observação: para acessar esse feed, você precisa ser colaborador ou proprietário do site. O cliente precisa fazer a autenticação usando um token tmp, OAuth ou ClientLogin. Consulte Como autenticar no serviço do Google Sites.
O feed de revisão 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
nessa 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 exigir autenticação ou não, dependendo das permissões de compartilhamento do site. Se o site não for público, seu cliente deve autenticar usando um token tmp, OAuth ou ClientLogin. Consulte Como autenticar no serviço do Google Sites.
O feed de conteúdo retorna o conteúdo mais recente de um site. Para acessá-la, chame o método GetContentFeed() da biblioteca, que usa um parâmetro de string uri opcional para transmitir uma consulta personalizada.
Veja um exemplo de como buscar todo o feed de conteúdo e imprimir 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 ao 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
É possível pesquisar o feed de conteúdo usando alguns dos parâmetros de consulta padrão da API Google Data e outros 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 construir o URI 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. Por exemplo, o snippet a seguir 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 as 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ê sabe o caminho relativo de uma página no site Google, pode 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ê souber o ID da entrada de conteúdo de uma página (por exemplo, "1234567890" no exemplo abaixo), poderá 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 ver mais parâmetros, consulte o Guia de referência.
Criação de conteúdo
Observação:antes de criar conteúdo para um site, verifique se você o definiu no cliente.client.site = "siteName"
Novos conteúdos (páginas da Web, páginas de listas, arquivos, páginas de anúncios etc.) podem ser criados usando CreatePage().
O primeiro argumento desse método é o tipo de página a ser criada, seguida pelo título e pelo conteúdo HTML.
Para ver uma lista de tipos de nós compatíveis, consulte o parâmetro kind no Guia de referência.
Como criar novos itens / páginas
Este exemplo cria um novo webpage no nível superior, inclui um XHTML 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 conterá uma cópia da entrada criada no servidor, como gdata.sites.gdata.ContentEntry.
Para criar um tipo de entrada mais complexo que é preenchido na criação (por exemplo, um listpage com cabeçalhos de coluna), você precisa criar
a gdata.sites.data.ContentEntry manualmente, preencher as propriedades de interesse e chamar client.Post().
Como criar itens/páginas em caminhos de URL personalizados
Por padrão, o exemplo anterior seria criado no URL http://sites.google.com/domainName/siteName/new-webpage-title e teria um título de página "Novo título da página da Web". Ou seja, o título é normalizado como 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 isso como um argumento de palavra-chave opcional.
Esse exemplo cria uma nova página filecabinet com um título de "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 houver. Precisa atender aa-z, A-Z, 0-9, -, _.title, não pode ser nulo se o nome da página não estiver presente. A normalização é cortar + recolher o espaço em branco para "-" e remover caracteres que não correspondem aa-z, A-Z, 0-9, -, _.
Como criar subpáginas
Para criar subpáginas (filhos) de 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
autoID completo do conteúdo.
Este exemplo consulta o feed de conteúdo por announcementpages e cria um novo announcement no primeiro 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 página mãe. O upload de anexos precisa ser feito
em uma página mãe. Portanto, defina um link pai no ContentEntry que você está tentando enviar. Consulte Como criar subpáginas para ver mais informações.
O método UploadAttachment() da biblioteca de cliente fornece a interface para o upload de anexos.
Fazendo upload dos anexos
Este exemplo faz upload de um arquivo PDF para o primeiro filecabinet encontrado no feed de conteúdo do usuário.
O anexo é criado com o título "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 for bem-sucedido, attachment conterá uma cópia do anexo criado no servidor.
Como fazer upload de um anexo para uma pasta
Os arquivos em pastas de suporte do Google Sites. O UploadAttachment() fornece outro argumento de palavra-chave, 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')
Observe que 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, elas são links para outros arquivos na Web
que podem ser adicionados às suas listagens do filecabinet. Esse recurso é semelhante ao método de upload "Add file by URL" na IU do Google Sites.
Observação: anexos da Web só podem ser criados em filecabinet. Elas não podem ser enviadas para outros tipos de página.
Este exemplo cria um anexo da Web no primeiro filecabinet encontrado no feed de conteúdo do usuário.
O título e a descrição (opcional) estão definidos como "GoogleLogo" e "cores bonitas", 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.
Atualizando conteúdo
Atualizar metadados e/ou conteúdo HTML de uma página
Os metadados (título, pageName etc.) e o conteúdo das páginas de qualquer tipo de entrada podem ser editados
usando o método Update() do cliente.
Veja abaixo um exemplo de atualização de uma listpage com as seguintes mudanças:
- O título foi modificado para "Título atualizado".
- O conteúdo HTML da página foi atualizado para "Conteúdo HTML atualizado".
- O título da primeira 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
pelo novo 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 item de um site Google, primeiro recupere a entrada de conteúdo e, em seguida, 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 de 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 de APIs de dados do Google.
Como fazer o download de anexos
Cada entrada attachment contém um link de conteúdo src, que pode ser usado para fazer o download do conteúdo do arquivo.
O cliente do Google Sites tem um método auxiliar para acessar e fazer o download do arquivo neste link: DownloadAttachment().
Ele aceita um URI de gdata.sites.data.ContentEntry ou de download 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!'
É responsabilidade do desenvolvedor do app especificar uma extensão de arquivo adequada ao tipo de conteúdo do anexo. O tipo de conteúdo
pode ser encontrado em entry.content.type.
Em alguns casos, pode ser que você não consiga fazer o download do arquivo para o disco (por exemplo, se o aplicativo estiver em execução no Google App Engine).
Nessas situações, use _GetFileContent() para buscar o conteúdo do arquivo e armazená-lo na memória.
Este 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 de ACL no feed de ACL representa um papel de acesso de uma entidade específica: 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 mostradas somente 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 IU do Google Sites. Assim, os administradores do domínio não serão exibidos, mesmo que tenham acesso implícito a um site.
Papéis
O elemento de papel representa um nível de acesso que uma entidade pode ter. Há quatro valores possíveis para o elemento gAcl:role:
- reader: um leitor (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 de elemento gAcl:scope:
- user: um valor de endereço de e-mail, por exemplo, "usuario@gmail.com".
- group: um endereço de e-mail do Grupo do Google, como "grupo@dominio.com".
- domain: um nome de domínio do G Suite, por exemplo, "dominio.com".
- default: há apenas um escopo possível do tipo "padrão", 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 de ACL
O feed da ACL pode ser usado para controlar as permissões de compartilhamento de um site e pode ser buscado com 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 que contém
uma ficha da empresa gdata.sites.data.AclEntry.
Se você estiver trabalhando com entradas no SiteFeed, cada SiteEntry conterá um link para o feed da ACL dele.
Por exemplo, o snippet a seguir busca o primeiro site no feed do site do usuário e consulta seu 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())
Compartilhar um site
Observação: algumas ACLs de compartilhamento só podem ser possíveis se o domínio estiver configurado para permitir 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 valores possíveis de 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 nos níveis do grupo e do domínio
Assim como no compartilhamento de um site com um único usuário, você pode compartilhar um site com um grupo do Google ou um domínio do G Suite. Os valores scope necessários estão listados abaixo.
Compartilhar com um endereço de e-mail de grupo:
scope = gdata.acl.data.AclScope(value='group_name@example.com', type='group')
Compartilhar 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, o domínio http://sites.google.com/a/domain1.com/siteA só pode compartilhar o site inteiro com o domínio1.com, não o domínio2.com. Os sites que não estão hospedados em um domínio do G Suite (por exemplo, http://sites.google.com/site/siteB) não podem convidar domínios.
Modificando as permissões de compartilhamento
Para uma permissão de compartilhamento existente em um site, busque o AclEntry em questão, modifique a permissão conforme desejado e, em seguida, chame o método Update() do cliente para modificar a ACL no servidor.
Este exemplo modifica nossa acl_entry anterior da seção Como compartilhar um site,
atualizando "user@example.com" como gravador (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 de 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 ao método Delete() o 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 de APIs de dados do Google.
Tópicos especiais
Como recuperar um feed ou uma entrada novamente
Se você quer recuperar um feed ou entrada recuperado anteriormente, é possível melhorar a eficiência informando ao servidor para enviar a lista ou entrada somente se ela tiver sido alterada desde a última vez que você a recuperou.
Para fazer esse tipo de recuperação condicional, transmita um valor de ETag para o GetEntry(). Por exemplo, se você tivesse 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 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 de APIs de dados do Google.