Guia do Python

Importante: este documento foi escrito antes de 2012. As opções de autenticação descritas neste documento (OAuth 1.0, MRAID e ConstraintLayout) foram oficialmente suspensas desde 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 Google Sites Data permite que os aplicativos clientes acessem, publiquem e modifiquem o conteúdo em um site Google. O 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 alguns antecedentes sobre os recursos da API Sites Data, este guia apresenta exemplos de interação com a API usando a biblioteca de cliente 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 quiser 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 é destinado a desenvolvedores que querem criar aplicativos clientes que interagem com o Google Sites usando a biblioteca de cliente de dados do Google para Python.

Primeiros passos

Para usar a biblioteca de cliente Python, você vai precisar do Python 2.2 ou mais recente e dos módulos listados na página de wiki DependencyModules. Depois de fazer o download da biblioteca de cliente, consulte Como começar a usar a biblioteca de dados Python do Google para receber ajuda com a instalação e o uso do cliente.

Como executar a amostra

Um exemplo completo está localizado no subdiretório samples/sites do repositório Mercurial do projeto (/samples/sites/sites_example.py).

Execute o exemplo desta forma:

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 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ássico. Por isso, você precisa fazer a autenticação para realizar determinadas operações (por exemplo, modificar o conteúdo). O programa também vai solicitar que você faça a autenticação pelo AuthSub, OAuth ou ClientLogin.

Para incluir os exemplos deste guia no seu 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 clássica do Sites. Transmita o nome do seu aplicativo e o nome do espaço web do site (do 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 registro. Ele precisa seguir o 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 do site e da operação que você está tentando executar. Por exemplo, você pode ler o feed de conteúdo de um site público, mas não fazer atualizações, o que exige um cliente autenticado. Isso pode ser feito por autenticação de nome de usuário/senha do ClientLogin, AuthSub ou OAuth.

Consulte a Visão geral da autenticação nas APIs de dados do Google para mais informações sobre AuthSub, OAuth e ClientLogin.

AuthSub para aplicativos da web

A autenticação AuthSub para aplicativos da Web precisa ser usada por aplicativos clientes que precisam autenticar os usuários em contas do Google ou do G Suite. O operador não precisa ter acesso ao nome de usuário e à senha do usuário do Google Sites. É necessário apenas um token AuthSub.

import gdata.gauth

def GetAuthSubUrl():
  next = 'http://www.example.com/myapp.py'
  scopes = ['https://sites.google.com/feeds/']
  secure = True
  session = True
  return gdata.gauth.generate_auth_sub_url(next, scopes, secure=secure, session=session)

print '<a href="%s">Login to your Google account</a>' % GetAuthSubUrl()

def GetAuthSubUrl():
  domain = 'example.com'
  next = 'http://www.example.com/myapp.py'
  scopes = ['https://sites.google.com/feeds/']
  secure = True
  session = True
  return gdata.gauth.generate_auth_sub_url(next, scopes, secure=secure, session=session, domain=domain)

OAuth para aplicativos da Web ou instalados/para dispositivos móveis

O OAuth pode ser usado como uma alternativa ao GroupByKey e destina-se a aplicativos da Web. O OAuth é semelhante ao uso do modo seguro e registrado do AuthSub, em que todas as solicitações de dados precisam ser assinadas digitalmente e você precisa registrar seu domínio.

ClientLogin para aplicativos instalados/para dispositivos móveis

O ClientLogin precisa ser usado por aplicativos instalados ou para dispositivos móveis que precisam autenticar os usuários nas Contas do Google. Na primeira execução, o aplicativo solicita o nome de usuário/senha do usuário. Em solicitações subsequentes, um token de autenticação é referenciado.

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

Voltar ao início

Feed do site

O feed de site pode ser usado para listar os sites do Google de um usuário ou para os quais ele tem permissões de visualização. Também é possível usar esse comando 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.

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 definido no objeto do cliente. Consulte a seção Introdução para mais informações sobre como definir esses valores no objeto de cliente.

Confira 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, nome do site, site do qual foi copiado e URI de feed acl.

Criação de novos sites

Observação: esse recurso está disponível apenas para domínios do G Suite.

É possível provisionar novos sites chamando o método CreateSite() da biblioteca. Assim como o auxiliar GetSiteFeed(), o 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 do definido no objeto SitesClient).

Confira um exemplo de como criar um novo site com o tema "ardósia" 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, o servidor responderá com um objeto gdata.sites.data.SiteEntry, preenchido com os elementos adicionados pelo servidor: um link para o site, um link para o feed da Access Control List do site, o nome do site, o título, o resumo e assim por diante.

Copiar um site

Observação: esse recurso está disponível apenas para 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 copiado terá esse link, que pode ser acessado por entry.FindSourceLink(). Confira um exemplo de duplicação do site criado na seção Criação de 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 sites que o usuário autenticado possui.
• Um modelo de site também pode ser copiado. Um site é um modelo quando a opção "Publicar este site como modelo" está 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 os metadados de um site

Para atualizar o título ou o resumo de um site, você vai precisar de um SiteEntry contendo o site em questão. Este exemplo usa o método GetEntry() para primeiro buscar um SiteEntry e, em seguida, mudar 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)

Voltar ao início

Como buscar o feed de atividades

Observação: para acessar o feed, você precisa ser um colaborador ou proprietário do site. O cliente precisa se autenticar usando um token AuthSub, OAuth ou ClientLogin. Consulte Como fazer a autenticação no serviço Sites.

Você pode buscar as atividades recentes (alterações) de um site buscando o feed de atividades. O método GetActivityFeed() da biblioteca fornece acesso a este 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.

Voltar ao início

Buscando o histórico de revisões

Observação: para acessar esse feed, você precisa ser um colaborador ou proprietário do site. O cliente precisa se autenticar usando um token AuthSub, OAuth ou ClientLogin. Consulte Como fazer a autenticação no serviço 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 recebe 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 contendo 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.

Voltar ao início

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 cliente vai precisar fazer a autenticação usando um token AuthSub, OAuth ou ClientLogin. Consulte Como fazer a autenticação no serviço Sites.

O feed de conteúdo retorna o conteúdo mais recente de um site. Ele pode ser acessado chamando o método GetContentFeed() da biblioteca, que usa um parâmetro de string uri opcional para transmitir uma consulta personalizada.

Confira um exemplo de como buscar o feed de conteúdo inteiro 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 para o tipo de entrada em questão. Consulte o exemplo de aplicativo para ter uma ideia melhor de algumas das propriedades disponíveis em cada tipo de entrada.

Voltar ao início

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 Data do Google e aqueles específicos da API Sites clássica. Para informações mais detalhadas e uma lista completa de parâmetros aceitos, 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. 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 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. Esse 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 mãe

Se você souber o ID de 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 mais parâmetros, consulte o guia de referência.

Voltar ao início

Criação de conteúdo

Observação: antes de criar conteúdo para um site, configure o site no cliente.
client.site = "siteName"

É possível criar novos conteúdos (páginas da Web, páginas de listas, pastas de arquivos, páginas de avisos etc.) usando 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 conferir uma lista de tipos de nós aceitos, consulte o parâmetro kind no Guia de referência.

Criação de novos itens / páginas

Este exemplo cria um novo webpage no nível superior, inclui alguns 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, a entry vai conter uma cópia da entrada criada no servidor, como uma gdata.sites.gdata.ContentEntry.

Para criar um tipo de entrada mais complexo que é preenchido na criação (por exemplo, um listpage com títulos de coluna), é necessário criar o gdata.sites.data.ContentEntry manualmente, preencher as propriedades de interesse e chamar client.Post().

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 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 de conteúdo. O auxiliar CreatePage() fornece isso como um argumento de palavra-chave opcional.

Este exemplo cria uma nova página filecabinet com o título "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:

1. page_name, se presente. Precisa ser a-z, A-Z, 0-9, -, _.
2. title, não pode ser nulo se o nome da página não estiver presente. A normalização é para recortar + reduzir espaços em branco para '-' e remover caracteres que não correspondem a a-z, A-Z, 0-9, -, _.

Como criar subpáginas

Para criar subpáginas (filhas) 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 ID completo da entrada do conteúdo.

Este exemplo consulta o feed de conteúdo em busca de 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!'

Fazer upload de arquivos

Assim como no Google Sites, a API oferece suporte a uploads de anexos para uma página de arquivo ou página principal. Os anexos devem ser enviados para uma página principal. Portanto, você precisa definir um link pai no ContentEntry que 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 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 "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 for bem-sucedido, attachment vai conter 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 pastas. O UploadAttachment() fornece um argumento de palavra-chave adicional, folder_name, que pode ser usado 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 passa 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. Essencialmente, são links para outros arquivos na Web que você pode adicionar às suas listagens filecabinet. Esse recurso é análogo ao método de upload Adicionar arquivo por URL na interface do Google Sites.

Observação: os anexos da Web só podem ser criados em um filecabinet. Não é possível fazer upload delas para outros tipos de páginas.

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) são definidos como "GoogleLogo" e "nice colors", 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.

Voltar ao início

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 é atualizado para "Conteúdo HTML atualizado".
• O cabeçalho 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!'

Como substituir o conteúdo e os metadados de um anexo

É possível substituir o conteúdo de um arquivo de anexo criando um novo objeto MediaSource com o novo conteúdo de arquivo e chamando o método Update() do cliente. Os metadados do anexo (como título e descrição) também podem ser atualizados ou apenas 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)

Voltar ao início

Como excluir conteúdo

Para remover uma página ou um item de um site do 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 o método Delete() ao 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 das APIs de dados do Google.

Voltar ao início

Como fazer 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 Sites contém um método auxiliar para acessar e fazer o download do arquivo neste link: DownloadAttachment(). Ela aceita um gdata.sites.data.ContentEntry ou um URI de download como 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 dela) 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, não é possível fazer o download do arquivo para o disco (por exemplo, se o app 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 de download é 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

Voltar ao início

Feed de 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, seja um usuário, um grupo de usuários, um domínio ou o acesso padrão (que é um site público). As entradas só vão aparecer 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 vão aparecer, mesmo que tenham acesso implícito a um site.

Papéis

O elemento do papel representa o 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).
• Escritor: um colaborador (equivalente ao acesso de leitura/gravação).
• proprietário: geralmente 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".
• grupo: um endereço de e-mail do Grupo do Google, por exemplo, "grupo@dominio.com".
• domain: um nome de domínio do G Suite, por exemplo, "domain.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 "proprietário", eles só podem ser leitores ou escritores.

Como recuperar o feed de ACL

O feed de 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 definido atualmente 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 lista 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 recupera o primeiro site no feed de sites do usuário e consulta o feed de ACL dele:

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ó 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 Google Site 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 de ACL para conferir os possíveis valores de AclScope e AclRoles.

Este exemplo concede permissões de leitura no site ao 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 em nível de grupo e domínio

Assim como compartilhar um site com um único usuário, você pode compartilhar um site 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 para 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 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 domain1.com, não com domain2.com. Sites que não são 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 o AclEntry em questão, modifique a permissão conforme desejado e chame o método Update() do cliente para modificar a ACL no servidor.

Este exemplo modifica nossa acl_entry anterior da seção Compartilhar um site, atualiza "user@example.com" para ser um redator (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() ao link edit da entrada de 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.

Voltar ao início

Temas especiais

Como recuperar um feed ou registro novamente

Se você quiser recuperar um feed ou uma entrada que recuperou antes, melhore a eficiência informando ao servidor para enviar a lista ou a 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ê 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.

Voltar ao início