Importante: Este documento se escribió antes de 2012. Las opciones de autenticación descritas 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 a contenido de un sitio de Google, lo publiquen y lo modifiquen. Tu aplicación cliente también puede solicitar una lista de actividad reciente, recuperar el historial de revisiones y descargar archivos adjuntos.
Además de proporcionar información sobre las funciones de la API de Sites Data, esta guía ofrece ejemplos para interactuar con la API con la biblioteca cliente de Python. Si necesitas ayuda para configurar la biblioteca cliente, consulta Cómo comenzar a usar la biblioteca cliente de Python de Google Data. Si te interesa obtener más información sobre el protocolo subyacente que usa la biblioteca cliente de Python para interactuar con la API de Sites clásica, consulta la guía de protocolos.
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 Google Data.
Cómo comenzar
Para usar la biblioteca cliente de Python, necesitarás Python 2.2 o una versión posterior y los módulos enumerados en la página de wiki DependencyModules. Después de descargar la biblioteca cliente, consulta Cómo comenzar a usar la biblioteca cliente de Python de datos de Google para obtener ayuda para instalar y usar el cliente.
Ejecuta la muestra
Se encuentra 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 obligatorias, la app te pedirá que ingreses esos valores. La muestra le permite al usuario realizar varias 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 instrucciones 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 Sites clásica.
Ingresa 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 seguir el siguiente formato: company-applicationname-version
Nota: En el resto de la guía, se supone que creaste un objeto SitesClient en la variable client.
Autentícate en la API de la versión clásica de Sites
La biblioteca cliente de Python se puede usar 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 de un sitio y la operación que intentas realizar. Por ejemplo, es posible que puedas leer el feed de contenido de un sitio público, pero no realizar actualizaciones, lo que requiere un cliente autenticado. Esto se puede hacer a través de la autenticación de nombre de usuario y contraseña de ClientLogin, AuthSub o OAuth.
Consulta la Descripción general de la autenticación de las APIs de Google Data para obtener más información sobre AuthSub, OAuth y ClientLogin.
AuthSub para aplicaciones web
La autenticación de AuthSub para aplicaciones web debe usarse en las aplicaciones cliente que necesitan autenticar a sus usuarios en las cuentas de Google o G Suite. El operador no necesita acceder al nombre de usuario y a 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 deseas autenticar usuarios en un dominio alojado en G Suite, pasa el nombre del 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() toma varios parámetros (correspondientes a los parámetros de consulta que usa el controlador AuthSubRequest):
- La URL next: 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.pyen el ejemplo anterior - el alcance:
https://sites.google.com/feeds/ - secure, un valor booleano que indica si el token se usará en modo seguro y registrado o no;
Trueen el ejemplo anterior - session, un segundo valor booleano para indicar si el token de un solo uso se intercambiará más adelante por un token de sesión;
Trueen el ejemplo anterior
Actualiza a un token de sesión
Consulta Cómo usar AuthSub con las bibliotecas cliente de la API de Google Data.
Recupera información sobre un token de sesión
Consulta Cómo usar AuthSub con las bibliotecas cliente de la API de Google Data.
Cómo revocar un token de sesión
Consulta Cómo usar AuthSub con las bibliotecas cliente de la API de Google Data.
Sugerencia: Una vez que tu aplicación haya adquirido correctamente un token de sesión de larga duración, almacénalo en tu base de datos para recuperarlo más adelante. No es necesario que devuelvas al usuario a AuthSub en cada ejecución de la aplicación.
Usa client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR) para establecer un token existente en el cliente.
OAuth para aplicaciones web o instaladas/para dispositivos móviles
OAuth se puede usar como alternativa a AuthSub y está diseñado para aplicaciones web. OAuth es similar al uso del modo seguro y registrado de AuthSub en que todas las solicitudes de datos deben estar firmadas digitalmente y debes registrar tu dominio.
Consulta las instrucciones para incorporar OAuth en tu aplicación instalada
Cómo recuperar un token de solicitud
Consulta Cómo usar OAuth con las bibliotecas cliente de la API de datos de Google.
Cómo autorizar un token de solicitud
Consulta Cómo usar OAuth con las bibliotecas cliente de la API de Google Data.
Actualiza a un token de acceso
Consulta Cómo usar OAuth con las bibliotecas cliente de la API de Google Data.
Sugerencia: Una vez que la aplicación haya adquirido correctamente un token de acceso de OAuth, almacénalo en tu base de datos para recuperarlo para su uso posterior. 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 establecer un token existente en el cliente.
ClientLogin para aplicaciones instaladas o para dispositivos móviles
Las aplicaciones instaladas o para dispositivos móviles que necesiten autenticar a sus usuarios en las Cuentas de Google deben usar ClientLogin. En la primera ejecución, la aplicación le solicita al usuario su nombre de usuario o 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 las solicitudes. Por ejemplo:
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1') client.ClientLogin('user@gmail.com', 'pa$$word', client.source);
Sugerencia: Una vez que 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 que le solicites la contraseña al usuario en cada ejecución de tu aplicación. Consulta Cómo recuperar 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 la sección sobre cómo usar ClientLogin con las bibliotecas cliente de la API de datos de Google.
Feed del sitio
El feed de sitios se puede usar para mostrar los sitios de Google Sites 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.
Sitios de fichas
Para enumerar los sitios a los que tiene acceso un usuario, usa el método GetSiteFeed() del cliente. El método toma un argumento opcional, uri, que puedes usar para especificar un URI de feed de sitio alternativo. De forma predeterminada, GetSiteFeed() usa el nombre y el dominio del sitio establecidos en el objeto cliente. Consulta la sección Introducción para obtener más información sobre cómo configurar estos valores en tu objeto 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, el nombre del sitio, el sitio del que se copió y el URI del feed de ACL.
Creación de sitios nuevos
Nota: Esta función solo está disponible para los dominios de G Suite.
Para aprovisionar sitios nuevos, llama al método CreateSite() de la biblioteca.
Al igual que el auxiliar 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 se configuró en tu objeto SitesClient).
A continuación, se muestra un ejemplo de cómo crear un sitio nuevo con el tema "slate" 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 en 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-de-mi-sitio.
Si el sitio se crea correctamente, el servidor responderá con un objeto gdata.sites.data.SiteEntry, propagado con elementos que el servidor agregó: un vínculo al sitio, un vínculo al feed de ACL del sitio, el nombre del sitio, el título, el resumen, etcétera.
Cómo copiar 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 copiados tendrán este vínculo, al que se puede acceder a través de entry.FindSourceLink(). A continuación, se muestra un ejemplo de cómo duplicar el sitio que se creó 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 está marcada la opción "Publicar este sitio como plantilla" en la página de configuración de Google Sites.
- Puedes copiar un sitio de otro dominio, siempre que aparezcas como propietario en el sitio de origen.
Actualiza los metadatos de un sitio
Para actualizar el título o el resumen de un sitio, necesitarás un SiteEntry que contenga el sitio en cuestión. En este ejemplo, se usa el método GetEntry() para primero recuperar un SiteEntry y, luego, cambiar su título, descripción y 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)
Cómo recuperar el feed de actividad
Nota: Para acceder a este feed, debes ser colaborador o propietario del sitio. Tu cliente debe autenticarse con un token de AuthSub, OAuth o ClientLogin. Consulta Cómo autenticarse en el servicio de Sites.
Para recuperar la actividad reciente (cambios) de un sitio, recupera 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)
Llamar a GetActivityFeed() 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 realizó en el sitio.
Cómo recuperar el historial de revisión
Nota: Para acceder a este feed, debes ser colaborador o propietario del sitio. Tu cliente debe autenticarse con un token AuthSub, OAuth o ClientLogin. Consulta Cómo autenticarse en el servicio de Sites.
El feed de revisiones proporciona información sobre el historial de revisiones de cualquier entrada de contenido. Se puede usar el método GetRevisionFeed() para recuperar las revisiones de una entrada de contenido determinada. El método toma 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 feed de contenido y se recupera 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]
Llamar a GetRevisionFeed() 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.
Canal de contenido
Cómo recuperar el feed de contenido
Nota: Es posible que el feed de contenido requiera o no autenticación, según los permisos de uso compartido del sitio. Si el sitio no es público, tu cliente debe autenticarse con un token de AuthSub, OAuth o ClientLogin. Consulta Cómo autenticarse 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 cadena uri opcional para pasar una consulta personalizada.
Este es un ejemplo de cómo recuperar todo el feed de contenido y, luego, 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: Se puede usar entry.Kind() para determinar el tipo de una 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. Consulta la aplicación de ejemplo para obtener una mejor idea de algunas de las propiedades disponibles en cada tipo de entrada.
Ejemplos de consulta del canal de contenido
Puedes buscar en el feed de contenido con algunos de los parámetros de consulta estándar de la API de Google Data y los específicos de la API de Sites clásica. 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 auxiliar gdata.sites.client.MakeContentFeedUri() para construir el URI base del feed de contenido.
Cómo recuperar tipos de entrada 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 de 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 las 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)
Recupera una página por ruta de acceso
Si conoces la ruta de acceso 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)
Cómo recuperar todas las entradas de una página superior
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 hay):
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.
Creación de contenido
Nota: Antes de crear contenido para un sitio, asegúrate de haberlo configurado en el cliente.client.site = "siteName"
Se puede crear contenido nuevo (páginas web, páginas de lista, gabinetes de archivos, páginas de anuncios, etc.) con CreatePage().
El primer argumento de este método debería 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.
Cómo crear elementos o páginas nuevos
En este ejemplo, se crea un webpage nuevo en el nivel superior, se incluye un poco de 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 tipos de entrada más complejos que se propaguen en la creación (p. ej., un listpage con encabezados de columna), deberás crear el gdata.sites.data.ContentEntry de forma manual, completar las propiedades de interés y llamar a client.Post().
Cómo crear elementos o páginas con rutas de URL personalizadas
De forma predeterminada, el ejemplo anterior se crearía en la URL
http://sites.google.com/domainName/siteName/new-webpage-title y
tendría un encabezado de página que diga “Título de la página web nueva”. 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 establecer la propiedad page_name en la entrada de contenido. El ayudante CreatePage() proporciona esto como un argumento de palabra clave opcional.
En este ejemplo, se crea una página filecabinet nueva con el encabezado "Almacenamiento de archivos", 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) especificando 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 asignar un nombre a la ruta de URL de una página:
page_name, si está presente. Debe satisfacera-z, A-Z, 0-9, -, _.title, no debe ser nulo si no hay un nombre de página. La normalización consiste en recortar y contraer los espacios en blanco a “-” y quitar los caracteres que no coinciden cona-z, A-Z, 0-9, -, _.
Crea 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 represente el ID propio completo de la entrada del contenido.
En este ejemplo, se busca el feed de contenido en busca de elementos announcementpage y se crea un nuevo elemento announcement debajo del 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 admite cargas de archivos adjuntos a una página de archivo o a una página superior. Los archivos adjuntos se deben subir a una página superior. Por lo tanto, debes establecer un vínculo superior en el 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 archivo adjunto se crea con el título “Manual para nuevos empleados” y una descripción (opcional) que dice “Paquete de recursos humanos”.
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 archivo adjunto creado en el servidor.
Sube un archivo adjunto a una carpeta
Los archivos de gabinetes de Google Sites admiten carpetas. UploadAttachment() proporciona un argumento de palabra clave adicional, folder_name, que puedes usar para subir un archivo adjunto a 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 en este ejemplo se pasa un objeto gdata.data.MediaSource a UploadAttachment() en lugar de una ruta de acceso. Tampoco pasa un tipo de contenido. En su lugar, el tipo de contenido se especifica en el objeto MediaSource.
Archivos adjuntos web
Los adjuntos web son tipos especiales de archivos adjuntos. Básicamente, son vínculos a otros archivos de la Web que puedes agregar a tus fichas filecabinet. Esta función es similar al método de carga "Agregar archivo por URL" en la IU de Google Sites.
Nota: Los archivos adjuntos web solo se pueden crear en un filecabinet. No se pueden subir a otros tipos de páginas.
En este ejemplo, se crea un archivo adjunto web en el primer elemento filecabinet encontrado en el feed de contenido del usuario.
Su título y descripción (opcional) se establecen en "GoogleLogo" y "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!'
La llamada crea un vínculo que apunta a la imagen en "http://www.google.com/images/logo.gif" en filecabinet.
Actualización de contenido
Actualiza 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 listpage con los siguientes cambios:
- El título se modifica 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!'
Reemplaza 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. También se pueden actualizar los metadatos del archivo adjunto (como el título y la descripción), o solo los metadatos.
En este ejemplo, se muestra cómo actualizar el contenido y los metadatos de un 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)
Cómo borrar contenido
Para quitar una página o un elemento de un sitio de Google Sites, primero recupera la entrada de contenido y, luego, llama al método Delete() del cliente.
client.Delete(content_entry)
También puedes pasarle al método Delete() el 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 ETag, consulta la guía de referencia de las APIs de datos de Google.
Descarga de archivos adjuntos
Cada entrada attachment contiene 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 para guardar el archivo adjunto como segundo argumento.
En este ejemplo, se recupera una entrada de archivo adjunto en particular (consultando su vínculo self) y se descarga el archivo en la ruta de acceso 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 que tenga sentido 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 en el 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.
En este ejemplo, se descarga 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
Feed de ACL
Descripción general de los permisos de uso compartido (LCA)
Cada entrada de LCA en el feed de LCA representa un rol 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). Solo se mostrarán las entradas de 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 de uso compartido 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.
Funciones
El elemento de rol representa un nivel de acceso que puede tener una entidad. El elemento gAcl:role tiene cuatro valores posibles:
- reader: Un usuario con permiso de lectura (equivalente al acceso de solo lectura).
- escritor: Un colaborador (equivalente al acceso de lectura/escritura)
- owner: Por lo general, el administrador del sitio (equivalente al acceso de lectura y escritura).
Permisos
El elemento de alcance representa la entidad que tiene este nivel de acceso. Hay cuatro tipos posibles del elemento gAcl:scope:
- user: Es un valor de dirección de correo electrónico, p. ej., “user@gmail.com”.
- group: Es una dirección de correo electrónico de Grupos de Google, p. ej., "grupo@domain.com".
- domain: Es un nombre de dominio de G Suite, p. ej., "domain.com".
- default: Solo hay un alcance posible de tipo "default", que no tiene valor (p. ej.,
<gAcl:scope type="default">). Este permiso específico 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 del sitio configurado actualmente en el objeto SitesClient
y se imprimen las entradas de permiso:
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 exitosa, feed será un objeto gdata.sites.data.AclFeed que contiene una lista de gdata.sites.data.AclEntry.
Si trabajas con entradas en SiteFeed, cada SiteEntry contiene un vínculo a su feed de LCA.
Por ejemplo, este fragmento recupera el primer sitio en el feed del 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())
Cómo compartir un sitio
Nota: Es posible que algunas LCA de uso compartido solo sean posibles si el dominio está configurado para permitir esos permisos (p. ej., si está habilitado el uso compartido fuera del dominio para los dominios de G Suite, etcétera).
Para compartir un sitio de Google con la API, crea un gdata.sites.gdata.AclEntry con los valores de gdata.acl.data.AclScope y gdata.acl.data.AclRole deseados. Consulta la sección Descripción general del feed de LCA para conocer los posibles valores de AclScope y AclRoles.
En este ejemplo, se otorgan permisos de lectura en el sitio al usuario "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)
Uso compartido a nivel del dominio y del grupo
Al igual que cuando compartes un sitio con un solo usuario, puedes compartirlo en todo un grupo de Google o en un dominio de G Suite. A continuación, se muestran los valores de scope necesarios.
Si compartes contenido con una dirección de correo electrónico del grupo, haz lo siguiente:
scope = gdata.acl.data.AclScope(value='group_name@example.com', type='group')
Uso compartido con todo un dominio:
scope = gdata.acl.data.AclScope(value='example.com', type='domain')
El uso compartido a nivel del dominio solo es compatible con los dominios de G Suite y solo con el dominio en el que se aloja el sitio. Por ejemplo, http://sites.google.com/a/domain1.com/siteA solo puede compartir todo el sitio con domain1.com, no con domain2.com. Los sitios que no se alojan en un dominio de G Suite (p. ej., http://sites.google.com/site/siteB) no pueden invitar dominios.
Cómo modificar los permisos de uso compartido
Para un permiso de uso compartido existente en un sitio, primero recupera el AclEntry en cuestión, modifica el permiso como desees y, luego, llama al método Update() del cliente para modificar la ACL en el servidor.
En este ejemplo, se modifica nuestro acl_entry anterior de la sección Cómo compartir un sitio y se actualiza "user@example.com" para que sea 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 Google Data.
Cómo quitar permisos de uso compartido
Para quitar un permiso de uso compartido, primero recupera el AclEntry y, luego, llama al método Delete() del cliente.
client.Delete(acl_entry)
También puedes pasar el método Delete() del 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 Google Data.
Temas especiales
Cómo volver a recuperar un feed o una entrada
Si deseas recuperar un feed o una entrada que ya recuperaste, 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 de ETag a GetEntry(). Por ejemplo, si tuvieras un objeto entry existente, haz lo siguiente:
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 coincide con la versión del servidor, lo que significa que tienes la copia más actualizada.
Sin embargo, si otro cliente o usuario realizó modificaciones, la entrada nueva se mostrará en entry y no se arrojará ninguna excepción.
Para obtener más información sobre las ETag, consulta la guía de referencia de las APIs de datos de Google.