Il 22 novembre 2016 è stata lanciata una versione ricostruita di Sites. L'API Sites non può accedere ai siti creati con questa versione o modificarli, ma può comunque accedere alla versione classica di Sites.

Guida di Python

Importante:questo documento è stato scritto prima del 2012. Le opzioni di autenticazione descritte in questo documento (OAuth 1.0, AuthSub e ClientLogin) sono state ritirate ufficialmente a partire dal 20 aprile 2012 e non sono più disponibili. Ti invitiamo a eseguire la migrazione a OAuth 2.0 il prima possibile.

L'API di dati Google Sites consente alle applicazioni client di accedere, pubblicare e modificare i contenuti all'interno di un sito di Google Sites. L'applicazione client può anche richiedere un elenco delle attività recenti, recuperare la cronologia delle revisioni e scaricare gli allegati.

Oltre a fornire alcune informazioni sulle funzionalità dell'API di dati di Sites, questa guida fornisce esempi di interazione con l'API utilizzando la libreria client di Python. Per assistenza per la configurazione della libreria client, consulta la guida introduttiva alla libreria client Python dei dati di Google. Se vuoi saperne di più sul protocollo sottostante utilizzato dalla libreria client Python per interagire con l'API Sites, consulta la guida al protocollo.

Audience

Questo documento è destinato agli sviluppatori che vogliono scrivere applicazioni client che interagiscono con Google Sites utilizzando la libreria client del servizio Python dei dati di Google.

Per cominciare

Per utilizzare la libreria client Python, è necessario Python 2.2+ e i moduli elencati nella pagina wiki DependencyModules. Dopo aver scaricato la libreria client, consulta la Guida introduttiva alla libreria Python dei dati di Google per informazioni su come installare e utilizzare il client.

Esecuzione dell'esempio

Un esempio di funzionamento completo si trova nella sottodirectory samples/sites del repository Mercurial del progetto (/samples/sites/sites_example.py).

Esegui l'esempio come segue:

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

Se i flag richiesti non vengono forniti, l'app ti chiederà di inserire questi valori. L'esempio consente all'utente di eseguire una serie di operazioni che indicano come utilizzare l'API Sites. Di conseguenza, dovrai eseguire l'autenticazione per eseguire determinate operazioni (ad es. la modifica dei contenuti). Il programma ti chiederà anche di eseguire l'autenticazione tramite AuthSub, OAuth o ClientLogin.

Per includere gli esempi in questa guida nel tuo codice, devi disporre delle seguenti istruzioni import:

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

Dovrai anche configurare un oggetto SitesClient, che rappresenta una connessione client all'API Sites. Inserisci il nome della tua applicazione e il nome dello spazio web del sito (dal relativo URL):

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

Per lavorare con un sito ospitato su un dominio G Suite, imposta il dominio utilizzando il parametro domain:

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

Negli snippet precedenti, l'argomento source è facoltativo ma consigliato per il logging. Dovrebbe essere nel seguente formato: company-applicationname-version

Nota: il resto della guida presuppone che tu abbia creato un oggetto SitesClient nella variabile client.

Autenticazione nell'API Sites

La libreria client Python può essere utilizzata per lavorare con feed pubblici o privati. L'API di dati di Sites fornisce l'accesso ai feed privati e pubblici, a seconda delle autorizzazioni di un sito e dell'operazione che stai tentando di eseguire. Ad esempio, potresti essere in grado di leggere il feed di contenuti di un sito pubblico ma non di aggiornarlo, operazione che richiede un client autenticato. Questa operazione può essere eseguita tramite l'autenticazione di nome utente e password ClientLogin, AuthSub o OAuth.

Per saperne di più su AuthSub, OAuth e ClientLogin, consulta la Panoramica sull'autenticazione delle API di dati di Google.

AuthSub per applicazioni web

AuthSub Authentication for Web Applications deve essere utilizzato dalle applicazioni client che devono autenticare gli utenti negli account Google o G Suite. L'operatore non deve necessariamente accedere al nome utente e alla password dell'utente Google Sites: è richiesto solo un token AuthSub.

Visualizza le istruzioni per incorporare AuthSub nella tua applicazione web.

Richiedere un token monouso

Quando l'utente visita la tua applicazione per la prima volta, deve eseguire l'autenticazione. In genere, gli sviluppatori stampano del testo e un link che rimanda l'utente alla pagina di approvazione di AuthSub per autenticare l'utente e richiedere l'accesso ai propri documenti. La libreria client Python dei dati di Google fornisce una funzione, generate_auth_sub_url() per generare questo URL. Il codice seguente imposta un link alla pagina 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()

Se vuoi autenticare gli utenti su un dominio ospitato da G Suite, passa il nome 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)

Il metodo generate_auth_sub_url() accetta diversi parametri (corrispondenti ai parametri di query utilizzati dal gestore AuthSubRequest):

  • l'URL successivo: URL a cui Google reindirizzerà dopo che l'utente avrà eseguito l'accesso al suo account e concede l'accesso; http://www.example.com/myapp.py nell'esempio precedente
  • scope: https://sites.google.com/feeds/
  • secure, un valore booleano per indicare se il token verrà utilizzato in modalità sicura e registrata o meno; True nell'esempio precedente
  • session, un secondo booleano che indica se il token monouso verrà successivamente scambiato o meno con un token di sessione; True nell'esempio precedente

Upgrade a un token di sessione

Consulta la sezione Utilizzo di AuthSub con le librerie client dell'API di dati di Google.

Recupero delle informazioni relative a un token di sessione

Consulta la sezione Utilizzo di AuthSub con le librerie client dell'API di dati di Google.

Revoca di un token di sessione

Consulta la sezione Utilizzo di AuthSub con le librerie client dell'API di dati di Google.

Suggerimento: una volta che la tua applicazione ha acquisito un token di sessione di lunga durata, archivialo nel tuo database per utilizzarlo in seguito. Non è necessario rimandare l'utente ad AuthSub a ogni esecuzione della tua applicazione. Usa client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR) per impostare un token esistente sul client.

OAuth per applicazioni web o installate su dispositivi mobili

OAuth può essere utilizzato come alternativa a AuthSub ed è destinato alle applicazioni web. OAuth è simile all'uso della modalità sicura e registrata di AuthSub, in quanto tutte le richieste di dati devono essere firmate digitalmente e devi registrare il tuo dominio.

Visualizza le istruzioni per incorporare OAuth nell'applicazione installata

Recupero di un token di richiesta

Consulta la sezione Utilizzo di OAuth con le librerie client dell'API di dati di Google.

Autorizzazione di un token di richiesta

Consulta la sezione Utilizzo di OAuth con le librerie client dell'API di dati di Google.

Upgrade a un token di accesso

Consulta la sezione Utilizzo di OAuth con le librerie client dell'API di dati di Google.

Suggerimento: una volta che la tua applicazione ha acquisito un token di accesso OAuth, memorizzalo nel database per utilizzarlo in seguito. Non è necessario rimandare l'utente tramite OAuth a ogni esecuzione della tua applicazione. Usa client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET) per impostare un token esistente sul client.

ClientLogin per le applicazioni installate/per dispositivi mobili

ClientLogin deve essere utilizzato da applicazioni installate o da dispositivi mobili che devono autenticare gli utenti agli Account Google. Alla prima esecuzione, la tua applicazione richiede all'utente il suo nome utente/la tua password. Per le richieste successive viene fatto riferimento a un token di autenticazione.

Visualizza le istruzioni per incorporare ClientLogin nella tua applicazione installata

Per utilizzare ClientLogin, richiama il metodo ClientLogin() dell'oggetto SitesClient, che viene ereditato da GDClient. Specifica l'indirizzo email e la password dell'utente per conto del quale il cliente invia le richieste. Ad esempio:

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

Suggerimento: una volta che l'applicazione ha eseguito correttamente l'autenticazione dell'utente per la prima volta, memorizza il token di autenticazione nel database per utilizzarlo in seguito. Non è necessario richiedere all'utente la sua password a ogni esecuzione della tua applicazione. Per ulteriori informazioni, consulta l'articolo Richiamare un token di autenticazione.

Per ulteriori informazioni sull'utilizzo di ClientLogin nelle tue applicazioni Python, consulta Utilizzo di ClientLogin con le librerie client dell'API di dati Google.

Torna all'inizio

Feed del sito

Il feed del sito può essere utilizzato per elencare i siti Google di proprietà di un utente o per cui si dispone delle autorizzazioni di visualizzazione. Può essere utilizzato anche per modificare il nome di un sito esistente. Infine, con i domini G Suite può essere utilizzata anche per creare e/o copiare un intero sito.

Elenco dei siti

Per elencare i siti a cui un utente ha accesso, utilizza il metodo GetSiteFeed() del client. Il metodo utilizza un argomento facoltativo, uri, che puoi utilizzare per specificare un URI del feed del sito alternativo. Per impostazione predefinita, GetSiteFeed() utilizza il nome e il dominio del sito impostati nell'oggetto client. Consulta la sezione Per iniziare per saperne di più sull'impostazione di questi valori nell'oggetto client.

Ecco un esempio di recupero dell'elenco di siti degli utenti autenticati:

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

Lo snippet riportato sopra stampa il titolo, il nome e il sito del sito da cui è stato copiato l'URI e il relativo URI del feed.

Creare nuovi siti

Nota: questa funzionalità è disponibile solo per i domini G Suite.

Per eseguire il provisioning dei nuovi siti, chiama il metodo CreateSite() della libreria. Analogamente all'Assistente GetSiteFeed(), CreateSite() accetta anche un argomento facoltativo, uri, che puoi utilizzare per specificare un URI del feed del sito alternativo (in caso di creazione del sito con un dominio diverso da quello impostato nell'oggetto SitesClient).

Ecco un esempio di creazione di un nuovo sito con il tema 'slate' e fornisci un titolo e una descrizione (facoltativa):

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 richiesta precedente creerà un nuovo sito nel dominio G Suite example2.com. Pertanto, l'URL del sito sarà https://sites.google.com/a/example2.com/titolo-per-il-mio-sito.

Se il sito viene creato correttamente, il server risponde con un oggetto gdata.sites.data.SiteEntry, completato con gli elementi aggiunti dal server: un link al sito, un link al feed ACL del sito, il nome del sito, il titolo, il riepilogo e così via.

Copiare un sito

Nota: questa funzionalità è disponibile solo per i domini G Suite.

CreateSite() può essere utilizzato anche per copiare un sito esistente. A tale scopo, passa l'argomento della parola chiave source_site. Qualsiasi sito che è stato copiato avrà questo link, che è accessibile tramite entry.FindSourceLink(). Ecco un esempio di duplicazione del sito creato nella sezione Creazione di nuovi siti:

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

Punti importanti:

  • È possibile copiare solo i siti e i modelli di sito di proprietà dell'utente autenticato.
  • Puoi anche copiare un modello di sito. Un sito è un modello se l'impostazione "Pubblica questo sito come modello" è selezionata nella pagina delle impostazioni di Google Sites.
  • Puoi copiare un sito da un altro dominio, in attesa di comparire come proprietario sul sito di origine.

Aggiornamento dei metadati di un sito

Per aggiornare il titolo o il riepilogo di un sito, devi avere un SiteEntry contenente il sito in questione. In questo esempio viene utilizzato il metodo GetEntry() per recuperare prima un SiteEntry e poi modificare il titolo, la descrizione e il tag di 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)

Torna all'inizio

Recupero del feed delle attività in corso...

Nota: per accedere a questo feed è necessario essere un collaboratore o un proprietario del sito. Il client deve eseguire l'autenticazione utilizzando un token AuthSub, OAuth o ClientLogin. Vedi Autenticazione al servizio Sites.

Puoi recuperare l'attività recente di un sito (modifiche) recuperando il feed delle attività. Il metodo lib's GetActivityFeed() fornisce l’accesso a questo 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)

La chiamata a GetActivityFeed() restituisce un oggetto gdata.sites.data.ActivityFeed contenente un elenco di gdata.sites.data.ActivityEntry. Ogni attività contiene informazioni su una modifica apportata al Sito.

Torna all'inizio

Recupero cronologia revisioni

Nota: per accedere a questo feed è necessario essere un collaboratore o un proprietario del sito. Il client deve eseguire l'autenticazione utilizzando un token AuthSub, OAuth o ClientLogin. Vedi Autenticazione al servizio Sites.

Il feed delle revisioni fornisce informazioni sulla cronologia delle revisioni per qualsiasi voce di contenuti. Il metodo GetRevisionFeed() può essere utilizzato per recuperare le revisioni per una determinata voce di contenuti. Il metodo accetta un parametro uri facoltativo che accetta un gdata.sites.data.ContentEntry, un URI completo di una voce di contenuti o un ID di voce di contenuti.

Questo esempio esegue una query sul feed dei contenuti e recupera il feed di revisione per la prima voce di contenuti:

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]

La chiamata a GetRevisionFeed() restituisce un oggetto gdata.sites.data.RevisionFeed contenente un elenco di gdata.sites.data.RevisionEntry. Ogni voce di revisione contiene informazioni quali i contenuti della revisione, il numero di versione e la data di creazione della nuova versione.

Torna all'inizio

Feed di contenuti

Recupero del feed di contenuti in corso...

Nota: il feed dei contenuti potrebbe richiedere o meno l'autenticazione, in base alle autorizzazioni di condivisione del sito. Se il sito non è pubblico, il client deve eseguire l'autenticazione utilizzando un token AuthSub, OAuth o ClientLogin. Consulta la pagina relativa all'autenticazione al servizio Sites.

Il feed di contenuti restituisce i contenuti più recenti di un sito. È possibile accedervi chiamando il metodo lib's GetContentFeed(), che richiede un parametro stringa uri facoltativo per passare una query personalizzata.

Ecco un esempio di recupero dell'intero feed di contenuti e della stampa di alcuni elementi interessanti:

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

Suggerimento: il valore entry.Kind() può essere utilizzato per determinare la voce di un tipo.

L'oggetto feed risultante è un gdata.sites.data.ContentFeed che contiene un elenco di gdata.sites.data.ContentEntry. Ogni voce rappresenta una pagina/elemento diverso all'interno del sito dell'utente e presenta elementi specifici per la tipologia di voce. Consulta l'applicazione di esempio per avere un'idea più chiara di alcune delle proprietà disponibili in ogni tipo di voce.

Torna all'inizio

Esempi di query per i feed di contenuti

Puoi cercare nel feed dei contenuti utilizzando alcuni dei parametri standard delle query dell'API Google Data e quelli specifici dell'API Sites. Per informazioni più dettagliate e un elenco completo dei parametri supportati, consulta la Guida di riferimento.

Nota: gli esempi in questa sezione utilizzano il metodo gdata.sites.client.MakeContentFeedUri() helper per la creazione dell'URI di base del feed di contenuti.

Recupero di tipi di voci specifici

Per recuperare solo un determinato tipo di voce, utilizza il parametro kind. Ad esempio, questo snippet restituisce solo attachment voci:

kind = 'webpage'

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

Per restituire più di un tipo, separa ogni elemento kind con una virgola. Ad esempio, questo snippet restituisce voci filecabinet e listpage:

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

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

Recupero di una pagina tramite percorso

Se conosci il percorso relativo di una pagina nel sito di Google Sites, puoi utilizzare il parametro path per recuperarla. Questo esempio restituisce la pagina che si trova all'indirizzo 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)

Recupero di tutte le voci di una pagina principale

Se conosci l'ID voce dei contenuti di una pagina (ad esempio "1234567890" nell'esempio riportato di seguito), puoi utilizzare il parametro parent per recuperare tutte le voci secondarie eventualmente presenti:

parent = '1234567890'

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

Per ulteriori parametri, consulta la Guida di riferimento.

Torna all'inizio



Creare contenuti

Nota: prima di creare contenuti per un sito, assicurati di averlo impostato nel client.
client.site = "siteName"

Puoi creare nuovi contenuti (pagine web, pagine elenco, schedari, pagine di comunicazioni e così via) utilizzando CreatePage(). Il primo argomento per questo metodo deve essere il tipo di pagina da creare, seguito dal titolo e dai contenuti HTML.

Per un elenco dei tipi di nodi supportati, consulta il parametro kind nella Guida di riferimento.

Creazione di nuovi elementi / pagine

Questo esempio crea un nuovo webpage al livello più alto, include alcuni XHTML per il corpo della pagina e imposta il titolo dell'intestazione su 'New WebPage Title':

entry = client.CreatePage('webpage', 'New WebPage Title', html='<b>HTML content</b>')
print 'Created. View it at: %s' % entry.GetAlternateLink().href

Se la richiesta ha esito positivo, entry conterrà una copia della voce creata sul server, come gdata.sites.gdata.ContentEntry.

Per creare tipi di voci più complessi e completati al momento della creazione (ad esempio, un listpage con intestazioni di colonna), dovrai creare gdata.sites.data.ContentEntry manualmente, compilare le proprietà di interesse e chiamare client.Post().

Creazione di elementi/pagine in percorsi URL personalizzati

Per impostazione predefinita, l'esempio precedente verrà creato sotto l'URL http://sites.google.com/domainName/siteName/new-webpage-title e avrà l'intestazione di una pagina con 'Nuovo titolo della pagina web'. Ciò significa che il titolo viene normalizzato in new-webpage-title per l'URL. Per personalizzare il percorso dell'URL di una pagina, puoi impostare la proprietà page_name nella voce dei contenuti. L'helper CreatePage() fornisce questo come argomento parola chiave facoltativo.

In questo esempio viene creata una nuova pagina filecabinet con l'intestazione 'File Storage', ma viene creata la pagina sotto l'URL http://sites.google.com/domainName/siteName/files (anziché http://sites.google.com/domainName/siteName/file-storage) specificando la proprietà page_name.

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

Il server utilizza le seguenti regole di precedenza per assegnare un nome al percorso dell'URL di una pagina:

  1. page_name, se presente. Deve soddisfare il a-z, A-Z, 0-9, -, _.
  2. title, non deve essere null se non è presente il nome della pagina. La normalizzazione consiste nel tagliare e comprimere lo spazio vuoto in '-' e rimuovere i caratteri che non corrispondono a a-z, A-Z, 0-9, -, _.

Creare pagine secondarie

Per creare sottopagine (secondarie) in una pagina principale, utilizza l'argomento parola chiave parent di CreatePage(). parent può essere un gdata.sites.gdata.ContentEntry o una stringa che rappresenta l'ID completo della voce dei contenuti.

Questo esempio esegue una query sul feed dei contenuti per announcementpage e crea un nuovo announcement sotto il primo sito trovato:

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

Caricamento di file

Proprio come in Google Sites, l'API supporta il caricamento degli allegati in una pagina schedario o in una pagina principale. Gli allegati devono essere caricati in una pagina principale. Di conseguenza, devi impostare un link principale sulla ContentEntry che stai tentando di caricare. Per ulteriori informazioni, consulta la sezione Creare pagine secondarie.

Il metodo UploadAttachment() della libreria client fornisce l'interfaccia per il caricamento degli allegati.

Caricamento di allegati

Questo esempio carica un file PDF nei primi filecabinet presenti nel feed di contenuti dell'utente. L'allegato viene creato con un titolo 'Guida per nuovi dipendenti' e una descrizione (facoltativa) e 'pacchetto HR'.

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 il caricamento ha esito positivo, attachment conterrà una copia dell'allegato creato sul server.

Caricare un allegato in una cartella

Gli schedari in Google Sites supportano le cartelle. UploadAttachment() fornisce un argomento aggiuntivo sulla parola chiave, folder_name che puoi utilizzare per caricare un allegato in una cartella filecabinet. Specifica semplicemente il nome della cartella:

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

Nota che questo esempio trasmette un oggetto gdata.data.MediaSource a UploadAttachment() invece che a un percorso file. Inoltre, non trasmette un tipo di contenuti. Il tipo di contenuti viene invece specificato nell'oggetto MediaSource.

Allegati web

Gli allegati web sono tipi speciali di allegati. Essenzialmente, sono link ad altri file sul Web che puoi aggiungere alle tue schede filecabinet. Questa funzionalità è analoga al metodo 'Aggiungi file tramite URL' metodo di caricamento nell'interfaccia utente di Google Sites.

Nota: gli allegati web possono essere creati solo con un filecabinet. Non possono essere caricate su altri tipi di pagine.

Questo esempio crea un allegato web sotto i primi filecabinet presenti nel feed di contenuti dell'utente. Il titolo e la descrizione (facoltativa) sono impostati rispettivamente su 'GoogleLogo' e 'nicecolor'.

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 chiamata crea un link che punta all'immagine all'indirizzo 'http://www.google.com/images/logo.gif' in filecabinet.

Torna all'inizio



Aggiornamento dei contenuti

Aggiornamento dei metadati e/o dei contenuti html di una pagina

I metadati (titolo, nome pagina ecc.) e i contenuti della pagina di qualsiasi tipo possono essere modificati utilizzando il metodo Update() del client.

Di seguito è riportato un esempio di aggiornamento di listpage con le seguenti modifiche:

  • Il titolo è stato modificato in 'Title aggiornato'
  • I contenuti HTML della pagina vengono aggiornati a 'Contenuti HTML aggiornati'
  • La prima intestazione di colonna dell'elenco viene modificata in "Proprietario".
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!'

Sostituzione dei contenuti e dei metadati di un allegato

Puoi sostituire i contenuti del file di un allegato creando un nuovo oggetto MediaSource con il nuovo contenuto del file e chiamando il metodo Update() del client. Puoi aggiornare anche i metadati dell'allegato, ad esempio titolo e descrizione, o solamente i metadati. Questo esempio mostra l'aggiornamento simultaneo di contenuti e metadati dei file:

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)

Torna all'inizio



Eliminazione di contenuti

Per rimuovere una pagina o un elemento da un sito Google, recupera prima la voce dei contenuti, quindi chiama il metodo Delete() del client.

client.Delete(content_entry)

Puoi anche passare il metodo Delete() al link edit della voce di contenuti e/o forzare l'eliminazione:

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

Per ulteriori informazioni sugli ETag, consulta la guida di riferimento delle API di dati di Google.

Torna all'inizio



Download degli allegati

Ogni voce attachment contiene un link ai contenuti src che può essere utilizzato per scaricare i contenuti dei file. Il client di Sites contiene un metodo di supporto per accedere al file e scaricarlo da questo link: DownloadAttachment(). Accetta un URI gdata.sites.data.ContentEntry o scarica l'URI per il suo primo argomento e un percorso file per salvare l'allegato come secondo.

Questo esempio recupera una determinata voce di allegato (eseguendo una query sul relativo link self) e scarica il file nel percorso specificato:

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

Spetta allo sviluppatore dell'app specificare un'estensione del file adatta al tipo di contenuti dell'allegato. Il tipo di contenuti si trova in entry.content.type.

In alcuni casi potresti non essere in grado di scaricare il file su disco (ad esempio, se la tua app è in esecuzione in Google App Engine). In questi casi, utilizza _GetFileContent() per recuperare i contenuti del file e archiviarli.

Questo esempio scarica un allegato in memoria.

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

Torna all'inizio

Feed ACL

Panoramica delle autorizzazioni di condivisione (ACL)

Ogni voce ACL nel feed ACL rappresenta un ruolo di accesso di una determinata entità, ovvero un utente, un gruppo di utenti, un dominio o l'accesso predefinito (che è un sito pubblico). Le voci verranno mostrate solo per le entità con accesso esplicito: una voce verrà mostrata per ogni indirizzo email nel riquadro "Persone con accesso" nella schermata di condivisione dell'interfaccia utente di Google Sites. Pertanto, gli amministratori di dominio non verranno mostrati, anche se hanno accesso implicito a un sito.

Ruoli

L'elemento del ruolo rappresenta un livello di accesso che un'entità può avere. Esistono quattro possibili valori dell'elemento gAcl:role:

  • reader: uno spettatore (equivalente a un accesso di sola lettura).
  • writer: un collaboratore (equivalente a accesso in lettura/scrittura).
  • owner: in genere l'amministratore del sito (equivalente a accesso in lettura/scrittura).

Mirini con ingrandimento

L'elemento dell'ambito rappresenta l'entità che dispone di questo livello di accesso. Esistono quattro possibili tipi di elementi gAcl:scope:

  • user: un valore dell'indirizzo email, ad esempio "utente@gmail.com".
  • group: un indirizzo email di Google Gruppi, ad esempio "group@domain.com".
  • domain: un nome di dominio G Suite, ad esempio "domain.com".
  • default: esiste un solo ambito di tipo "default", che non ha alcun valore (ad esempio <gAcl:scope type="default">). Questo particolare ambito controlla l'accesso che ogni utente avrà per impostazione predefinita su un sito pubblico.

Nota: i domini non possono avere un valore gAcl:role impostato su "Proprietario", possono essere solo lettori o scrittori.

Recupero del feed ACL

Il feed ACL può essere utilizzato per controllare le autorizzazioni di condivisione di un sito e può essere recuperato utilizzando il metodo GetAclFeed().

L'esempio seguente recupera il feed ACL per il sito attualmente impostato sull'oggetto SitesClient e stampa le voci delle autorizzazioni:

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)

Dopo una query riuscita, feed sarà un oggetto gdata.sites.data.AclFeed contenente un elenco di gdata.sites.data.AclEntry.

Se stai lavorando con voci nel SiteFeed, ogni SiteEntry contiene un link al relativo feed ACL. Ad esempio, questo snippet recupera il primo sito nel feed del sito dell'utente ed esegue una query sul relativo feed 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())

Condividere un sito

Nota: la condivisione di determinati ACL potrebbe essere possibile solo se il dominio è configurato per consentire queste autorizzazioni (ad esempio, se la condivisione all'esterno del dominio per i domini G Suite è abilitata e così via).

Per condividere un sito Google utilizzando l'API, crea un elemento gdata.sites.gdata.AclEntry con i valori gdata.acl.data.AclScope e gdata.acl.data.AclRole desiderati. Consulta la sezione Panoramica del feed ACL per i valori possibili di AclScope e AclRoles.

Questo esempio concede le autorizzazioni di lettura sul sito all'utente '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)

Condivisione a livello di gruppo e dominio

Come per la condivisione di un sito con un singolo utente, puoi condividere un sito in un gruppo Google o un dominio G Suite. Di seguito sono elencati i valori scope necessari.

Condivisione con un indirizzo email di gruppo:

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

Condivisione con un intero dominio:

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

La condivisione a livello di dominio è supportata solo per i domini G Suite e solo per il dominio su cui è ospitato il sito. Ad esempio, http://sites.google.com/a/dominio1.com/sitoA può condividere solo l'intero sito con dominio1.com, non dominio2.com. I siti che non sono ospitati su un dominio G Suite (ad esempio http://sites.google.com/sito/sitoB) non possono invitare i domini.

Modifica delle autorizzazioni di condivisione

Per un'autorizzazione di condivisione esistente su un sito, recupera innanzitutto il AclEntry in questione, modifica l'autorizzazione come preferisci, quindi chiama il metodo Update() del client per modificare l'ACL sul server.

Questo esempio modifica il precedente acl_entry nella sezione Condivisione di un sito, aggiornando 'user@example.com' per diventare autore (collaboratore):

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)

Per ulteriori informazioni sugli ETag, consulta la guida di riferimento delle API di dati di Google.

Rimozione delle autorizzazioni di condivisione

Per rimuovere un'autorizzazione di condivisione, recupera prima il AclEntry, quindi chiama il metodo Delete() del client.

client.Delete(acl_entry)

Puoi anche passare il metodo Delete() e utilizzare il link edit della voce acl per forzare l'eliminazione.

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

Per ulteriori informazioni sugli ETag, consulta la guida di riferimento delle API di dati di Google.

Torna all'inizio

Argomenti speciali

Recupero di un feed o di una nuova voce

Se vuoi recuperare un feed o una voce che hai recuperato in precedenza, puoi migliorare l'efficienza comunicando al server di inviare l'elenco o la voce solo se è cambiata dall'ultima volta che l'hai recuperata.

Per eseguire questa operazione di recupero condizionale, passa un valore ETag al GetEntry(). Ad esempio, se hai un oggetto entry esistente:

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() genera l'eccezione gdata.client.NotModified, l'ETag della voce corrisponde alla versione sul server, il che significa che hai la copia più aggiornata. Tuttavia, se un altro client/utente ha apportato delle modifiche, la nuova voce verrà restituita in entry e non verrà generata alcuna eccezione.

Per ulteriori informazioni sugli ETag, consulta la guida di riferimento delle API di dati di Google.

Torna all'inizio