Guia do Python

Importante:este documento foi escrito antes de 2012. As opções de autenticação descritos neste documento (OAuth 1.0, estrela e ConstraintLayout) foram oficialmente descontinuado desde 20 de abril de 2012 e não estão mais disponíveis. Recomendamos que você migre OAuth 2.0 assim que possível.

A API de dados do Google Sites permite que aplicativos clientes acessem, publiquem e modifiquem o conteúdo de 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 Google Sites, este guia fornece exemplos de interação com a API usando a biblioteca de cliente do Python. Para receber ajuda na configuração da biblioteca de cliente, consulte Introdução à biblioteca de cliente Python de dados do Google. Se você tiver interesse entender mais sobre o protocolo usado pela biblioteca de cliente Python para interagir com a API Sites clássico, consulte o guia de protocolos.

Público-alvo

Este documento se destina aos desenvolvedores que desejam criar 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 wiki DependencyModules. Depois de fazer o download da biblioteca de cliente, consulte Introdução à biblioteca Python de dados do Google para obter ajuda sobre como instalar e usar o cliente.

Como executar a amostra

Um exemplo completo de funcionamento 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 sinalizações necessárias não forem fornecidas, o aplicativo solicitará que você insira esses valores. O exemplo permite que o usuário execute uma série de operações que demonstrar como usar a API Sites clássico. Assim, você precisará se autenticar para executar determinadas operações (por exemplo, modificação de conteúdo). O programa vai também solicita a autenticação via AuthSub, OAuth ou ClientLogin (link em inglês).

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 precisa configurar um objeto SitesClient, que representa uma conexão de cliente com a API Sites clássico. 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 geração de registros. Ele deveria siga 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 recursos feeds, 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, o que exige um cliente autenticado. Isso pode ser feito via 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 mais informações sobre NGINX, OAuth e Systrace.

AuthSub para aplicativos da web

A autenticação Geocoding para aplicativos da Web deve ser usada por aplicativos clientes que precisam autenticam 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 O token vezes é obrigatório.

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 Jinja em que todas as solicitações de dados devem ser assinadas digitalmente, e você deve registrar seu domínio.

Tensor para aplicativos instalados/móveis

O ClientLogin deve ser usado por aplicativos instalados ou para dispositivos móveis que precisam autenticam os usuários nas Contas do Google. Na primeira execução, o aplicativo solicita o nome de usuário/senha do usuário. Nas 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. 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 o 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 toma um parâmetro 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 Vamos 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, nome do site, site do qual foi copiado e URI de feed acl.

Como criar novos 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. Semelhante ao auxiliar GetSiteFeed(), CreateSite() também aceita uma argumento opcional, uri, que pode ser usado 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 seu objeto SitesClient).

Veja um exemplo de criação de um novo site com o tema "barreira" e fornecer uma título e 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 example2.com do G Suite. Assim, o URL do site seria https://sites.google.com/a/example2.com/title-for-my-site.

Se o site for criado corretamente, o servidor responderá com gdata.sites.data.SiteEntry. , preenchido com elementos adicionados pelo servidor: um link para o site, um link para o feed da ACL do site, nome do site, título, resumo e assim por diante.

Copiar um site

Observação: esse recurso só está disponível 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. Todos os sites que tiverem sido copiados terão este link, que pode ser acessado em entry.FindSourceLink(). Este é um exemplo de duplicação do site criado na seção Como 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 sites que o usuário autenticado possui.
• Um modelo de site também pode ser copiado. Um site é um modelo se 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 caso esteja listado como proprietário no site de origem.

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. Isso O 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:

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. Seu cliente deve ser autenticado usando um token noindex, OAuth ou Systrace. Consulte Como autenticar 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 histórico de revisões

Observação: para acessar o feed, você precisa ser um colaborador ou proprietário do site. Seu cliente deve ser autenticado usando um token noindex, OAuth ou Systrace. Consulte Como autenticar 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 GetRevisionFeed() pode ser usado para buscar as revisões de uma determinada entrada de conteúdo. O método usa um 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 naquela 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 exigir ou não autenticação. dependendo das permissões de compartilhamento do site. Se o site não for público, o seu cliente deverá autenticar usando um token MRAID, OAuth ou Systrace. Consulte Como autenticar 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(), que usa um parâmetro de string uri opcional para transmitir uma consulta personalizada.

Aqui está um exemplo de busca de todo o feed de conteúdo e 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/um item diferente site do usuário e tem elementos específicos para o tipo de entrada. Consulte o aplicativo de exemplo para ter uma ideia melhor algumas das propriedades disponíveis em cada tipo de entrada.

Voltar ao início

Exemplos de consulta do feed de conteúdo

Você pode pesquisar o feed de conteúdo usando alguns dos parâmetros de consulta padrão da API de dados do Google e aqueles específicos da API Sites clássico. Para informações mais detalhadas e uma lista completa de parâmetros compatíveis, consulte a 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 filecabinet e listpage entradas:

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 pai

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 parâmetros adicionais, 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"

Novo conteúdo (páginas da Web, páginas de lista, arquivos, páginas de avisos etc.) pode ser criado 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 ver uma lista de tipos de nó compatíveis, consulte o parâmetro kind no Guia de referência.

Criar novos itens / páginas

Esse exemplo cria um novo webpage no nível superior, inclui um pouco de XH no corpo da página, e define o título como "Novo título da página da web":

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 um 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 colunas), você precisa criar o gdata.sites.data.ContentEntry manualmente, preencha as propriedades de interesse e chame 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 tenham 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 assistente 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 atender a a-z, A-Z, 0-9, -, _.
2. title, não poderá ser nulo se o nome da página não estiver presente. A normalização é cortar e recolher o espaço em branco para '-' e remove caracteres não correspondentes a a-z, A-Z, 0-9, -, _.

Como criar subpáginas

Para criar subpáginas (filhos) em uma página pai, use o argumento de palavra-chave parent do CreatePage(). O parent pode ser um gdata.sites.gdata.ContentEntry ou uma string que representa o autoID 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!'

Como fazer upload de arquivos

Assim como no Google Sites, a API permite o upload de anexos para uma página de arquivo ou uma página principal. É necessário fazer upload dos anexos a 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), "HR package".

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, o attachment conterá uma cópia do anexo criado no servidor.

Fazer upload de um anexo para uma pasta

Os arquivos nas pastas de suporte do Google Sites. O UploadAttachment() fornece uma palavra-chave adicional folder_name, que pode ser usado para fazer upload de um anexo para uma pasta filecabinet. Basta especificar o nome dessa 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 esse exemplo transmite um objeto gdata.data.MediaSource para UploadAttachment(). 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. Eles são links para outros arquivos na Web que você pode adicionar a suas fichas do filecabinet. Esse recurso é análogo a 'Add file by URL' de upload na interface do usuário do Google Sites.

Observação: os anexos da Web só podem ser criados em um filecabinet. Eles não podem ser enviados 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) 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.

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 pelo usando o método Update() do cliente.

Confira abaixo um exemplo de como atualizar um listpage com as seguintes mudanças:

• O título será 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!'

Substituir o conteúdo e os metadados de um anexo

Você pode substituir o conteúdo do arquivo de um anexo criando um novo objeto MediaSource. com o novo conteúdo do arquivo e chamando o método Update() do cliente. O URL metadados (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

Excluindo 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 o link edit da entrada de conteúdo ao método Delete() 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 src de conteúdo que pode ser usado para fazer o download do conteúdo do arquivo. O cliente do Google Sites contém um método auxiliar para acessar e fazer o download do arquivo deste 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 a segunda.

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 podem ser encontrados 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 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 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, seja um usuário, um grupo de usuários, um domínio, ou o acesso padrão (um site público). As entradas só serão mostradas para entidades com acesso explícito: uma entrada será mostrada para cada endereço de e-mail na seção "Pessoas com acesso" na tela de compartilhamento da interface do Google Sites. Assim, os administradores de domínio não serão exibidos, 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).
• writer: um colaborador (equivalente ao acesso de leitura/gravação).
• owner: 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".
• group: um endereço de e-mail de um Grupo do Google, por exemplo, "group@domain.com".
• domain: um nome de domínio do G Suite, como "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 "proprietário" acesso, eles só podem ser leitores ou escritores.

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 para o 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 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 de 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 seu 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 o gdata.acl.data.AclScope e gdata.acl.data.AclRole. Consulte a Seção Visão geral do feed da ACL para o possível 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 no nível do grupo e do domínio

Como no compartilhamento de um site com um único usuário, é possível compartilhar um site em uma 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 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 estiverem 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 existente em um site, primeiro busque o AclEntry em questão e modifique a permissão conforme desejado, e depois chamar o método Update() do cliente para modificar a ACL no servidor.

Este exemplo modifica o acl_entry anterior da seção Compartilhamento de um site, atualizando "user@example.com" para ser 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 Access Control List 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

Tópicos especiais

Como recuperar um feed ou uma entrada novamente

Se você quiser recuperar um feed ou uma entrada que recuperou antes, pode melhorar a eficiência informando que o servidor envie 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ê já 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, o evento A ETag corresponde à versão no servidor, ou seja, 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