Guía de Python

Importante: Este documento se redactó antes de 2012. Las opciones de autenticación que se describen en este documento (OAuth 1.0, AuthSub y ClientLogin) se dieron de baja oficialmente a partir del 20 de abril de 2012 y ya no están disponibles. Te recomendamos que migres a OAuth 2.0 lo antes posible.

La API de datos de Google Sites permite que las aplicaciones cliente accedan, publiquen y modifiquen contenido dentro de un sitio de Google. Tu aplicación cliente también puede solicitar una lista de la actividad reciente, recuperar el historial de revisión y descargar archivos adjuntos.

Además de proporcionar información general sobre las capacidades de la API de Sites Data, en esta guía se proporcionan ejemplos de cómo interactuar con la API mediante la biblioteca cliente de Python. Para obtener ayuda con la configuración de la biblioteca cliente, consulta Comienza a usar la biblioteca cliente de Python de datos de Google. Si te interesa conocer más sobre el protocolo subyacente que usa la biblioteca cliente de Python para interactuar con la API de la versión clásica de Sites, consulta la guía de protocolo.

Público

Este documento está dirigido a desarrolladores que deseen escribir aplicaciones cliente que interactúen con Google Sites mediante la biblioteca cliente de Python de datos de Google.

Cómo comenzar

Para usar la biblioteca cliente de Python, necesitarás Python 2.2 o versiones posteriores y los módulos que se enumeran en la página de wiki DependencyModules. Después de descargar la biblioteca cliente, consulta Comienza a usar la biblioteca de datos de Python de Google para obtener ayuda con la instalación y el uso del cliente.

Ejecuta la muestra

Hay una muestra funcional completa en el subdirectorio samples/sites del repositorio de Mercurial del proyecto (/samples/sites/sites_example.py).

Ejecuta el ejemplo de la siguiente manera:

python sites_example.py
# or
python sites_example.py --site [sitename] --domain [domain or "site"] --debug [prints debug info if set]

Si no se proporcionan las marcas necesarias, la app te solicitará que ingreses esos valores. La muestra permite al usuario realizar una serie de operaciones que demuestran cómo usar la API de la versión clásica de Sites. Por lo tanto, deberás autenticarte para realizar ciertas operaciones (p.ej., modificar el contenido). El programa también te pedirá que te autentiques a través de AuthSub, OAuth o ClientLogin.

Para incluir los ejemplos de esta guía en tu propio código, necesitarás las siguientes declaraciones import:

import atom.data
import gdata.sites.client
import gdata.sites.data

También deberás configurar un objeto SitesClient, que representa una conexión de cliente a la API de la versión clásica de Sites. Pasa el nombre de tu aplicación y el nombre del espacio web del sitio (desde su URL):

client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName')

Para trabajar con un sitio alojado en un dominio de G Suite, configura el dominio con el parámetro domain:

client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1', site='yourSiteName', domain='example.com')

En los fragmentos anteriores, el argumento source es opcional, pero se recomienda para fines de registro. Debe tener el siguiente formato: company-applicationname-version

Nota: En el resto de la guía, se da por sentado que creaste un objeto SitesClient en la variable client.

Autentica en la API de la versión clásica de Sites

La biblioteca cliente de Python puede usarse para trabajar con feeds públicos o privados. La API de Sites Data proporciona acceso a feeds privados y públicos, según los permisos del sitio y la operación que intentes realizar. Por ejemplo, es posible que puedas leer el canal de contenido de un sitio público sin actualizarlo, lo que requiere un cliente autenticado. Esto se puede hacer a través de la autenticación de nombre de usuario/contraseña en ClientLogin, AuthSub o OAuth.

Consulta la Descripción general de la autenticación de las API de datos de Google para obtener más información sobre AuthSub, OAuth y ClientLogin.

AuthSub para aplicaciones web

Las aplicaciones cliente que necesitan autenticar a sus usuarios en las cuentas de Google o G Suite deben usar la autenticación AuthSub para aplicaciones web. El operador no necesita acceso al nombre de usuario y la contraseña del usuario de Google Sites; solo se requiere un token de AuthSub.

Consulta las instrucciones para incorporar AuthSub en tu aplicación web

Solicita un token de un solo uso

Cuando el usuario visita tu aplicación por primera vez, debe autenticarse. Por lo general, los desarrolladores imprimen parte del texto y un vínculo que dirige al usuario a la página de aprobación de AuthSub para autenticarlo y solicitar acceso a sus documentos. La biblioteca cliente de Python de datos de Google proporciona una función, generate_auth_sub_url() para generar esta URL. El siguiente código configura un vínculo a la página AuthSubRequest.

import gdata.gauth

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

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

Si quieres autenticar usuarios en un dominio alojado en G Suite, pasa el nombre de dominio a 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)

El método generate_auth_sub_url() usa varios parámetros (correspondientes a los parámetros de consulta que usa el controlador AuthSubRequest):

  • La URL siguiente: Es la URL a la que Google redireccionará después de que el usuario acceda a su cuenta y le otorgue acceso; http://www.example.com/myapp.py en el ejemplo anterior.
  • el alcance: https://sites.google.com/feeds/
  • secure, un valor booleano para indicar si el token se usará en modo seguro y registrado o no; True en el ejemplo anterior
  • session, un segundo valor booleano para indicar si el token de un solo uso se intercambiará por un token de sesión o no; True en el ejemplo anterior

Actualiza a un token de sesión

Consulta Cómo usar AuthSub con las bibliotecas cliente de la API de datos de Google.

Recupera información sobre un token de sesión

Consulta Cómo usar AuthSub con las bibliotecas cliente de la API de datos de Google.

Revocar un token de sesión

Consulta Cómo usar AuthSub con las bibliotecas cliente de la API de datos de Google.

Sugerencia: Una vez que la aplicación haya adquirido correctamente un token de sesiones de larga duración, almacena ese token en tu base de datos para recuperarlo y usarlo más adelante. No es necesario enviar al usuario de vuelta a AuthSub en cada ejecución de tu aplicación. Usa client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR) para configurar un token existente en el cliente.

OAuth para aplicaciones web o instaladas o para dispositivos móviles

OAuth se puede utilizar como alternativa a AuthSub y está diseñado para aplicaciones web. OAuth es similar al uso del modo seguro y registrado de AuthSub en el sentido de que todas las solicitudes de datos deben firmarse de manera digital y debes registrar tu dominio.

Consulta las instrucciones para incorporar OAuth en tu aplicación instalada

Recupera un token de solicitud

Consulta Cómo usar OAuth con las bibliotecas cliente de la API de datos de Google.

Autoriza un token de solicitud

Consulta Cómo usar OAuth con las bibliotecas cliente de la API de datos de Google.

Actualiza a un token de acceso

Consulta Cómo usar OAuth con las bibliotecas cliente de la API de datos de Google.

Sugerencia: Una vez que tu aplicación haya adquirido correctamente un token de acceso de OAuth, almacénalo en tu base de datos para recuperarlo y usarlo más tarde. No es necesario enviar al usuario de vuelta a través de OAuth en cada ejecución de tu aplicación. Usa client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET) para configurar un token existente en el cliente.

ClientLogin en aplicaciones instaladas o para dispositivos móviles

Las aplicaciones instaladas o para dispositivos móviles que necesitan autenticar a sus usuarios en las Cuentas de Google deben usar ClientLogin. En la primera ejecución, tu aplicación solicita al usuario su nombre de usuario/contraseña. En solicitudes posteriores, se hace referencia a un token de autenticación.

Consulta las instrucciones para incorporar ClientLogin en tu aplicación instalada

Para usar ClientLogin, invoca el método ClientLogin() del objeto SitesClient, que se hereda de GDClient. Especifica la dirección de correo electrónico y la contraseña del usuario en cuyo nombre tu cliente realiza solicitudes. Por ejemplo:

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

Sugerencia: Cuando tu aplicación haya autenticado correctamente al usuario por primera vez, almacena el token de autenticación en tu base de datos para recuperarlo y usarlo más adelante. No es necesario solicitarle al usuario su contraseña en cada ejecución de tu aplicación. Consulta Recupera un token de autenticación para obtener más información.

Para obtener más información sobre el uso de ClientLogin en tus aplicaciones de Python, consulta Cómo usar ClientLogin con las bibliotecas cliente de la API de datos de Google.

Volver al principio

Feed del sitio

El feed del sitio se puede usar para mostrar los sitios de Google que un usuario posee o para los que tiene permisos de visualización. También se puede usar para modificar el nombre de un sitio existente. Por último, en el caso de los dominios de G Suite, también se puede usar para crear o copiar un sitio completo.

Enumera sitios

Para mostrar una lista de los sitios a los que un usuario tiene acceso, usa el método GetSiteFeed() del cliente. El método incluye un argumento opcional, uri, que puedes usar para especificar un URI de feed de sitio alternativo. De forma predeterminada, GetSiteFeed() usa el nombre del sitio y el dominio configurados en el objeto de cliente. Consulta la sección Primeros pasos para obtener más información sobre cómo configurar estos valores en tu objeto de cliente.

A continuación, se muestra un ejemplo de cómo recuperar la lista de sitios del usuario 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

El fragmento anterior imprime el título y el nombre del sitio, el sitio desde el que se copió y su URI de feed de LCA.

Creación de sitios nuevos

Nota: Esta función solo está disponible para los dominios de G Suite.

Se pueden aprovisionar sitios nuevos llamando al método CreateSite() de la biblioteca. Al igual que el ayudante GetSiteFeed(), CreateSite() también acepta un argumento opcional, uri, que puedes usar para especificar un URI de feed de sitio alternativo (en el caso de crear el sitio en un dominio diferente del que está configurado en el objeto SitesClient).

A continuación, te mostramos un ejemplo de cómo crear un sitio nuevo con el tema "cortinilla de video" y proporcionar un título y una descripción (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

La solicitud anterior crearía un sitio nuevo con el dominio de G Suite example2.com. Por lo tanto, la URL del sitio sería https://sites.google.com/a/example2.com/título-para-mi-sitio.

Si el sitio se creó correctamente, el servidor responderá con un objeto gdata.sites.data.SiteEntry, propagado con los elementos que agregó el servidor: un vínculo al sitio, un vínculo al feed de la LCA del sitio, el nombre del sitio, el título, el resumen, etcétera.

Copia un sitio

Nota: Esta función solo está disponible para los dominios de G Suite.

CreateSite() también se puede usar para copiar un sitio existente. Para ello, pasa el argumento de palabra clave source_site. Todos los sitios que se hayan copiado tendrán este vínculo, al que se puede acceder a través de entry.FindSourceLink(). A continuación, te mostramos un ejemplo de cómo duplicar el sitio creado en la sección Cómo crear sitios nuevos:

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

Puntos importantes:

  • Solo se pueden copiar los sitios y las plantillas de sitios que pertenecen al usuario autenticado.
  • También se puede copiar una plantilla para sitios. Un sitio es una plantilla si el parámetro de configuración "Publicar este sitio como plantilla" está marcado en la página de configuración de Google Sites.
  • Puedes copiar un sitio de otro dominio, aunque aparezcas como propietario en el sitio de origen.

Actualizar los metadatos de un sitio

Para actualizar el título o resumen de un sitio, necesitarás un elemento SiteEntry que contenga el sitio en cuestión. En este ejemplo, se usa el método GetEntry() para recuperar primero un SiteEntry y, luego, cambiar el título, la descripción y la etiqueta de categoría:

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)

Volver al principio

Cómo recuperar el feed de actividad

Nota: Para acceder a este feed, debes ser colaborador o propietario del sitio. Tu cliente se debe autenticar mediante un token AuthSub, OAuth o ClientLogin. Consulta Cómo realizar la autenticación en el servicio de Sites.

Para recuperar la actividad reciente de un sitio (los cambios), puedes obtener el feed de actividad. El método GetActivityFeed() de la biblioteca proporciona acceso 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)

Si llamas a GetActivityFeed(), se muestra un objeto gdata.sites.data.ActivityFeed que contiene una lista de gdata.sites.data.ActivityEntry. Cada entrada de actividad contiene información sobre un cambio que se hizo en el sitio.

Volver al principio

Recuperando el historial de revisión

Nota: Para acceder a este feed, debes ser colaborador o propietario del sitio. Tu cliente se debe autenticar mediante un token AuthSub, OAuth o ClientLogin. Consulta Cómo realizar la autenticación en el servicio de Sites.

El feed de revisión proporciona información sobre el historial de revisión de todas las entradas de contenido. El método GetRevisionFeed() se puede usar para recuperar las revisiones de una entrada de contenido determinada. El método incluye un parámetro uri opcional que acepta un gdata.sites.data.ContentEntry, un URI completo de una entrada de contenido o un ID de entrada de contenido.

En este ejemplo, se consulta el canal de contenido y se obtiene el feed de revisión de la primera entrada de contenido:

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]

Si llamas a GetRevisionFeed(), se muestra un objeto gdata.sites.data.RevisionFeed que contiene una lista de gdata.sites.data.RevisionEntry. Cada entrada de revisión contiene información como el contenido de esa revisión, el número de versión y cuándo se creó la versión nueva.

Volver al principio

Canal de contenido

Cómo recuperar el canal de contenido

Nota: El feed de contenido puede requerir autenticación o no; dependiendo de los permisos de uso compartido del Sitio. Si el Sitio no es público, tu cliente debe autenticarse con un token AuthSub, OAuth o ClientLogin. Consulta Cómo realizar la autenticación en el servicio de Sites.

El feed de contenido muestra el contenido más reciente de un sitio. Para acceder a ella, llama al método GetContentFeed() de la biblioteca, que toma un parámetro de string opcional uri para pasar una consulta personalizada.

A continuación, se muestra un ejemplo de cómo recuperar todo el canal de contenido e imprimir algunos elementos interesantes:

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

Sugerencia: entry.Kind() se puede usar para determinar el tipo de entrada.

El objeto feed resultante es un gdata.sites.data.ContentFeed que contiene una lista de gdata.sites.data.ContentEntry. Cada entrada representa una página o un elemento diferente dentro del sitio del usuario y tiene elementos específicos para el tipo de entrada que es. Consulta la aplicación de ejemplo para obtener una mejor idea de algunas de las propiedades disponibles en cada tipo de entrada.

Volver al principio

Ejemplos de consultas de feeds de contenido

Puedes buscar en el feed de contenido con algunos de los parámetros de consulta estándar de la API de datos de Google y aquellos específicos de la API de la versión clásica de Sites. Para obtener información más detallada y una lista completa de los parámetros admitidos, consulta la Guía de referencia.

Nota: En los ejemplos de esta sección, se usa el método de ayuda gdata.sites.client.MakeContentFeedUri() para construir el URI base del feed de contenido.

Cómo recuperar tipos de entradas específicos

Para recuperar solo un tipo de entrada en particular, usa el parámetro kind. A modo de ejemplo, este fragmento solo muestra entradas attachment:

kind = 'webpage'

print 'Fetching only %s entries' % kind
uri = '%s?kind=%s' % (client.MakeContentFeedUri(), kind)
feed = client.GetContentFeed(uri=uri)

Para mostrar más de un tipo, separa cada kind con una coma. Por ejemplo, este fragmento muestra entradas filecabinet y listpage:

kind = ','.join(['filecabinet', 'listpage'])

print 'Fetching only %s entries' % kind
uri = '%s?kind=%s' % (client.MakeContentFeedUri(), kind)
feed = client.GetContentFeed(uri=uri)

Cómo recuperar una página por ruta

Si conoces la ruta relativa de una página dentro del sitio de Google, puedes usar el parámetro path para recuperar esa página en particular. En este ejemplo, se mostraría la página ubicada en 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)

Recuperar todas las entradas de una página principal

Si conoces el ID de entrada de contenido de una página (p.ej., "1234567890" en el siguiente ejemplo), puedes usar el parámetro parent para recuperar todas sus entradas secundarias (si las hubiera):

parent = '1234567890'

print 'Fetching all children of parent entry: ' + parent
uri = '%s?parent=%s' % (client.MakeContentFeedUri(), parent)
feed = client.GetContentFeed(uri=uri)

Para ver parámetros adicionales, consulta la guía de referencia.

Volver al principio



Creación de contenido

Nota: Antes de crear contenido para un sitio, asegúrate de configurarlo en el cliente.
client.site = "siteName"

Puedes crear contenido nuevo (páginas web, páginas de listas, gabinetes de archivos, páginas de anuncios, etc.) con CreatePage(). El primer argumento de este método debe ser el tipo de página que se creará, seguido del título y su contenido HTML.

Para obtener una lista de los tipos de nodos admitidos, consulta el parámetro kind en la Guía de referencia.

Creación de páginas o elementos nuevos

En este ejemplo, se crea una webpage nueva en el nivel superior, se incluyen algunos XHTML para el cuerpo de la página y se establece el título del encabezado 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

Si la solicitud se realiza correctamente, entry contendrá una copia de la entrada creada en el servidor, como un gdata.sites.gdata.ContentEntry.

Para crear un tipo de entrada más complejo que se propaga durante la creación (p.ej., una listpage con encabezados de columna), deberás crear gdata.sites.data.ContentEntry de forma manual, completar las propiedades de interés y llamar a client.Post().

Creación de elementos o páginas en rutas de URL personalizadas

De forma predeterminada, el ejemplo anterior se crearía bajo la URL http://sites.google.com/domainName/siteName/new-webpage-title y tendría un encabezado de página de "Título de página web nuevo". Es decir, el título se normaliza a new-webpage-title para la URL. Para personalizar la ruta de URL de una página, puedes configurar la propiedad page_name en la entrada de contenido. El ayudante CreatePage() lo proporciona como un argumento de palabra clave opcional.

En este ejemplo, se crea una página filecabinet nueva con el encabezado "File Storage", pero se crea la página en la URL http://sites.google.com/domainName/siteName/files (en lugar de http://sites.google.com/domainName/siteName/file-storage) mediante la especificación de la propiedad page_name.

entry = client.CreatePage('filecabinet', 'File Storage', html='<b>HTML content</b>', page_name='files')
print 'Created. View it at: ' + entry.GetAlternateLink().href

El servidor usa las siguientes reglas de prioridad para nombrar la ruta de URL de una página:

  1. page_name, si está presente Debe cumplir con a-z, A-Z, 0-9, -, _.
  2. title no debe ser nulo si el nombre de la página no está presente La normalización consiste en recortar + contraer los espacios en blanco a "-" y quitar los caracteres que no coincidan con a-z, A-Z, 0-9, -, _.

Cómo crear subpáginas

Para crear subpáginas (secundarias) en una página principal, usa el argumento de palabra clave parent de CreatePage(). El parent puede ser un gdata.sites.gdata.ContentEntry o una cadena que representa el ID propio completo de la entrada del contenido.

En este ejemplo, se consulta el feed de contenido para announcementpage y se crea un announcement nuevo en el primero que se encuentre:

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!'

Cómo subir archivos

Al igual que en Google Sites, la API permite subir archivos adjuntos a la página de gabinete de archivos o a la superior. Los archivos adjuntos deben subirse a una página principal. Por lo tanto, debes establecer un vínculo superior en la ContentEntry que intentas subir. Consulta Cómo crear subpáginas para obtener más información.

El método UploadAttachment() de la biblioteca cliente proporciona la interfaz para subir archivos adjuntos.

Subiendo archivos adjuntos

En este ejemplo, se sube un archivo PDF al primer filecabinet que se encuentra en el feed de contenido del usuario. El adjunto se crea con el título “Manual para empleados nuevos” y una descripción (opcional), “Paquete de RR.HH.”.

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

Si la carga se realiza correctamente, attachment contendrá una copia del adjunto creado en el servidor.

Sube un archivo adjunto a una carpeta

Los gabinetes de archivos de Google Sites admiten carpetas. El UploadAttachment() proporciona un argumento de palabra clave adicional, folder_name, que puedes usar para subir un archivo adjunto en una carpeta filecabinet. Simplemente especifica el nombre de esa carpeta:

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')

Ten en cuenta que este ejemplo pasa un objeto gdata.data.MediaSource a UploadAttachment() en lugar de una ruta de archivo. Tampoco pasa un tipo de contenido. En su lugar, el tipo de contenido se especifica en el objeto MediaSource.

Archivos adjuntos web

Los archivos adjuntos web son tipos de archivos adjuntos especiales. En esencia, son vínculos a otros archivos de la Web que puedes agregar a tus fichas de filecabinet. Esta función es similar al método de carga "Agregar archivo mediante URL" en la IU de Google Sites.

Nota: Los archivos adjuntos web solo se pueden crear en una filecabinet. No se pueden subir a otros tipos de páginas.

En este ejemplo, se crea un archivo adjunto web en el primer filecabinet que se encuentra en el feed de contenido del usuario. El título y la descripción (opcional) están configurados en 'GoogleLogo' y 'colores lindo', 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!'

La llamada crea un vínculo que dirige a la imagen en "http://www.google.com/images/logo.gif" de filecabinet.

Volver al principio



Actualización de contenido

Actualizar los metadatos o el contenido HTML de una página

Los metadatos (título, pageName, etc.) y el contenido de la página de cualquier tipo de entrada se pueden editar con el método Update() del cliente.

A continuación, se muestra un ejemplo de cómo actualizar un objeto listpage con los siguientes cambios:

  • El título se cambió a "Título actualizado"
  • El contenido HTML de la página se actualiza a "Contenido HTML actualizado"
  • El encabezado de la primera columna de la lista se cambia a "Propietario"
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!'

Cómo reemplazar el contenido y los metadatos de un archivo adjunto

Para reemplazar el contenido de un archivo adjunto, crea un objeto MediaSource nuevo con el contenido del archivo nuevo y llama al método Update() del cliente. Los metadatos del adjunto (como el título y la descripción) también se pueden actualizar o solo se pueden actualizar. En este ejemplo, se muestra cómo actualizar el contenido y los metadatos del archivo al mismo tiempo:

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)

Volver al principio



Eliminación de contenido

Para quitar una página o un elemento de un sitio de Google, primero recupera la entrada de contenido y, luego, llama al método Delete() del cliente.

client.Delete(content_entry)

También puedes pasar el método Delete() al vínculo edit de la entrada de contenido o forzar la eliminación:

# force=True sets the If-Match: * header instead of using the entry's ETag.
client.Delete(content_entry.GetEditLink().href, force=True)

Para obtener más información sobre las ETags, consulta la guía de referencia de las APIs de datos de Google.

Volver al principio



Descargando archivos adjuntos

Cada entrada attachment incluye un vínculo src de contenido que se puede usar para descargar el contenido del archivo. El cliente de Sites contiene un método auxiliar para acceder al archivo y descargarlo desde este vínculo: DownloadAttachment(). Acepta un gdata.sites.data.ContentEntry o un URI de descarga para su primer argumento y una ruta de acceso al archivo en la que se guardará el adjunto como el segundo.

En este ejemplo, se recupera una entrada de archivo adjunto en particular (con una consulta en el vínculo self) y se descarga el archivo en la ruta especificada:

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!'

Depende del desarrollador de la app especificar una extensión de archivo adecuada para el tipo de contenido del archivo adjunto. El tipo de contenido se puede encontrar en entry.content.type.

En algunos casos, es posible que no puedas descargar el archivo al disco (p.ej., si tu app se ejecuta en Google App Engine). En estas situaciones, usa _GetFileContent() para recuperar el contenido del archivo y almacenarlo en la memoria.

Esta descarga de ejemplo es un archivo adjunto a la memoria.

try:
  file_contents = client._GetFileContent(attachment.content.src)
  # TODO: Do something with the file contents
except gdata.client.RequestError, e:
  raise e

Volver al principio

Feed de LCA

Descripción general de los permisos de uso compartido (LCA)

Cada entrada de LCA en el feed de LCA representa una función de acceso de una entidad en particular, ya sea un usuario, un grupo de usuarios, un dominio o el acceso predeterminado (que es un sitio público). Las entradas solo se mostrarán para las entidades con acceso explícito; se mostrará una entrada para cada dirección de correo electrónico en el panel "Personas con acceso" en la pantalla para compartir de la IU de Google Sites. Por lo tanto, no se mostrarán los administradores de dominio, aunque tengan acceso implícito a un sitio.

Roles

El elemento de rol representa un nivel de acceso que puede tener una entidad. Hay cuatro valores posibles para el elemento gAcl:role:

  • reader: Un lector (equivalente al acceso de solo lectura).
  • escritor: Es un colaborador (equivalente a acceso de lectura/escritura).
  • owner: Por lo general, es el administrador del sitio (equivalente al acceso de lectura y escritura).

Permisos

El elemento de alcance representa a la entidad que tiene este nivel de acceso. Existen cuatro tipos posibles del elemento gAcl:scope:

  • user: Un valor de dirección de correo electrónico, p. ej., "usuario@gmail.com".
  • group: Una dirección de correo electrónico del Grupo de Google, p. ej., "grupo@dominio.com".
  • domain: Un nombre de dominio de G Suite, p. ej., "domain.com".
  • default: Solo hay un alcance posible del tipo "default", que no tiene valor (p. ej., <gAcl:scope type="default">). Este alcance en particular controla el acceso que cualquier usuario tiene de forma predeterminada en un sitio público.

Nota: Los dominios no pueden tener un valor gAcl:role configurado como acceso de “propietario”, solo pueden ser lectores o escritores.

Recupera el feed de LCA

El feed de LCA se puede usar para controlar los permisos de uso compartido de un sitio y se puede recuperar con el método GetAclFeed().

En el siguiente ejemplo, se recupera el feed de LCA para el sitio configurado actualmente en el objeto SitesClient y se imprimen las entradas de permisos:

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)

Después de una consulta correcta, feed será un objeto gdata.sites.data.AclFeed que contiene una lista de gdata.sites.data.AclEntry.

Si trabajas con entradas en el SiteFeed, cada SiteEntry contiene un vínculo a su feed de LCA. Por ejemplo, este fragmento recupera el primer sitio en el feed de sitio del usuario y consulta su feed de LCA:

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())

Compartir un sitio

Nota: Ciertas LCA de uso compartido solo pueden ser posibles si el dominio está configurado para permitir esos permisos (p.ej., si está habilitado el uso compartido fuera del dominio para dominios de G Suite, etcétera).

Para compartir un sitio de Google con la API, crea un gdata.sites.gdata.AclEntry con los valores deseados de gdata.acl.data.AclScope y gdata.acl.data.AclRole. Consulta la sección Descripción general del feed de LCA para conocer los posibles valores de AclScope y AclRoles.

Este ejemplo otorga permisos de lectura en el sitio al usuario "usuario@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)

Uso compartido a nivel de grupo y dominio

Al igual que con compartir un sitio con un solo usuario, puedes compartir un sitio a través de un Grupo de Google o un dominio de G Suite. Los valores scope necesarios se enumeran a continuación.

Compartir contenido con la dirección de correo electrónico de un grupo:

scope = gdata.acl.data.AclScope(value='group_name@example.com', type='group')

Se comparte con todo un dominio:

scope = gdata.acl.data.AclScope(value='example.com', type='domain')

El uso compartido a nivel del dominio solo se admite en los dominios de G Suite y en el dominio en el que se aloja el sitio. Por ejemplo, http://sites.google.com/a/dominio1.com/sitioA solo puede compartir el sitio completo con el dominio1.com, no con el dominio2.com. Los sitios que no se alojan en un dominio de G Suite (p.ej., http://sites.google.com/sitio/sitioB) no pueden invitar a dominios.

Cómo modificar los permisos de uso compartido

Para un permiso de uso compartido existente en un sitio, primero debes obtener el AclEntry en cuestión, modificar el permiso según lo desees y, luego, llamar al método Update() del cliente para modificar la LCA en el servidor.

En este ejemplo, se modifica nuestro acl_entry anterior de la sección Cómo compartir un sitio. Para ello, se actualiza "usuario@example.com" a fin de que sea un 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 obtener más información sobre las ETags, consulta la guía de referencia de las APIs de datos de Google.

Eliminar permisos de uso compartido

Para quitar un permiso de uso compartido, primero recupera AclEntry y, luego, llama al método Delete() del cliente.

client.Delete(acl_entry)

También puedes pasar al método Delete() el vínculo edit de la entrada de la LCA o forzar la eliminación:

# force=True sets the If-Match: * header instead of using the entry's ETag.
client.Delete(acl_entry.GetEditLink().href, force=True)

Para obtener más información sobre las ETags, consulta la guía de referencia de las APIs de datos de Google.

Volver al principio

Temas especiales

Cómo volver a recuperar un feed o una entrada

Si deseas recuperar un feed o una entrada que ya recuperaste antes, puedes mejorar la eficiencia si le indicas al servidor que envíe la lista o la entrada solo si cambió desde la última vez que la recuperaste.

Para realizar este tipo de recuperación condicional, pasa un valor ETag a GetEntry(). Por ejemplo, si tienes un objeto entry existente:

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

Si GetEntry() arroja la excepción gdata.client.NotModified, la ETag de la entrada coincidirá con la versión en el servidor, lo que significa que tienes la copia más actualizada. Sin embargo, si otro cliente o usuario realizó modificaciones, se mostrará la entrada nueva en entry y no se arrojará ninguna excepción.

Para obtener más información sobre las ETags, consulta la guía de referencia de las APIs de datos de Google.

Volver al principio