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 deprecate ufficialmente il 20 aprile 2012 e non sono più disponibili. Ti consigliamo di eseguire la migrazione ad OAuth 2.0 appena possibile.

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

Oltre a fornire alcune informazioni di base sulle funzionalità dell'API Sites Data, questa guida fornisce esempi di interazione con l'API mediante la libreria client Python. Per assistenza nella configurazione della libreria client, consulta la pagina Introduzione 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 della versione classica di Sites, consulta la guida ai protocolli.

Pubblico

Questo documento è destinato agli sviluppatori che desiderano scrivere applicazioni client che interagiscano con Google Sites utilizzando la libreria client Python dei dati di Google.

Come iniziare

Per utilizzare la libreria client Python, sono necessari Python 2.2 o versioni successive 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 assistenza su installazione e utilizzo del client.

Esecuzione dell'esempio

Un esempio completo funzionante 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 obbligatori non vengono forniti, l'app ti chiederà di inserire questi valori. L'esempio consente all'utente di eseguire una serie di operazioni che mostrano come utilizzare l'API della versione classica di Sites. Di conseguenza, dovrai autenticarti per eseguire determinate operazioni (ad esempio la modifica dei contenuti). Il programma ti chiederà anche di eseguire l'autenticazione tramite AuthSub, OAuth o ClientLogin.

Per includere gli esempi di 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 della versione classica di Sites. Inserisci il nome dell'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 riportati sopra, l'argomento source è facoltativo, ma consigliato per il logging. Deve avere il seguente formato: company-applicationname-version

Nota: la parte restante della guida presuppone che tu abbia creato un oggetto SitesClient nella variabile client.

Autenticazione nell'API della versione classica di Sites

La libreria client Python può essere utilizzata per lavorare con feed pubblici o privati. L'API Sites Data fornisce l'accesso a feed privati e pubblici, in base alle autorizzazioni di un sito e all'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 nome utente/password di ClientLogin, AuthSub o OAuth.

Per ulteriori informazioni su AuthSub, OAuth e ClientLogin, consulta la panoramica sull'autenticazione delle API di dati di Google.

AuthSub per le applicazioni web

L'autenticazione AuthSub per le applicazioni web deve essere utilizzata dalle applicazioni client che devono autenticare i propri utenti per gli account Google o G Suite. L'operatore non ha bisogno di accedere al nome utente e alla password dell'utente di 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 per la prima volta l'applicazione, deve eseguire l'autenticazione. In genere, gli sviluppatori stampano del testo e un link che indirizza l'utente alla pagina di approvazione di AuthSub per autenticare l'utente e richiedere l'accesso ai loro documenti. La libreria client Python dei dati di Google fornisce una funzione generate_auth_sub_url() per generare questo URL. Il codice seguente consente di impostare 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, trasmetti 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() richiede diversi parametri (corrispondenti ai parametri di query utilizzati dal gestore AuthSubRequest):

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

Upgrade a un token di sessione

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

Recupero delle informazioni su un token di sessione

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

Revoca di un token di sessione

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

Suggerimento: una volta che l'applicazione ha acquisito correttamente un token di sessioni di lunga durata, archivialo nel database per richiamarlo per un utilizzo futuro. Non è necessario reindirizzare 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/mobile

Il protocollo OAuth può essere utilizzato in alternativa a AuthSub ed è destinato alle applicazioni web. OAuth è simile all'utilizzo della modalità protetta 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 Utilizzo di OAuth con le librerie client dell'API di dati di Google.

Autorizzazione di un token di richiesta

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

Upgrade a un token di accesso

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

Suggerimento: una volta che l'applicazione ha acquisito correttamente un token di accesso OAuth, archivia il token nel database per poterlo utilizzare in un secondo momento. Non è necessario rinviare 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 applicazioni installate/mobili

ClientLogin deve essere utilizzato da applicazioni installate o per dispositivi mobili che devono autenticare i propri utenti per gli Account Google. Alla prima esecuzione, l'applicazione richiede all'utente il nome utente e la password. Nelle richieste successive, viene fatto riferimento a un token di autenticazione.

Visualizza le istruzioni per incorporare ClientLogin nell'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 tuo client effettua 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 autenticato l'utente per la prima volta, archivia il token di autenticazione nel database per poterlo utilizzare in seguito. Non è necessario richiedere all'utente la password a ogni esecuzione della tua applicazione. Per saperne di più, consulta Richiamo di un token di autenticazione.

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

Torna all'inizio

Feed sito

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

Elenchi di siti

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

Ecco un esempio di come recuperare l'elenco di siti dell'utente autenticato:

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 del sito, il sito da cui è stato copiato e il relativo URI del feed acl.

Creare nuovi siti

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

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

Di seguito è riportato un esempio di creazione di un nuovo sito con il tema "slate" e di come fornire 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/title-for-my-site.

Se il sito è stato creato correttamente, il server risponderà 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.

Copia di un sito

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

CreateSite() può essere utilizzato anche per copiare un sito esistente. Per farlo, passa l'argomento della parola chiave source_site. Tutti i siti copiati saranno associati a questo link, accessibile tramite entry.FindSourceLink(). Di seguito è riportato 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 siti di proprietà dell'utente autenticato.
  • È possibile copiare anche 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, purché tu sia indicato come proprietario nel sito di origine.

Aggiornamento dei metadati di un sito

Per aggiornare il titolo o il riepilogo di un sito, è necessario un SiteEntry contenente il sito in questione. In questo esempio viene utilizzato il metodo GetEntry() per recuperare prima un elemento SiteEntry e poi modificarne 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 attività

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

Puoi recuperare l'attività recente di un sito (modifiche) recuperando il feed attività. Il metodo GetActivityFeed() della lib 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 voce di attività contiene informazioni su una modifica apportata al sito.

Torna all'inizio

Recupero cronologia delle revisioni

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

Il feed delle revisioni fornisce informazioni sulla cronologia delle revisioni per qualsiasi voce di contenuti. Puoi utilizzare il metodo GetRevisionFeed() per recuperare le revisioni di una determinata voce di contenuto. Il metodo accetta un parametro uri facoltativo che accetta gdata.sites.data.ContentEntry, l'URI completo di una voce di contenuto o un ID voce di contenuto.

Questo esempio esegue una query sul feed dei contenuti e recupera il feed delle revisioni 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 il contenuto di quella revisione, il numero di versione e la data di creazione della nuova versione.

Torna all'inizio

Feed di contenuti

Recupero del feed di contenuti

Nota: il feed dei contenuti potrebbe richiedere o meno l'autenticazione, a seconda delle autorizzazioni di condivisione del sito. Se il sito non è pubblico, il client deve eseguire l'autenticazione utilizzando un token AuthSub, OAuth o ClientLogin. Vedi Autenticazione nel servizio Sites.

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

Ecco un esempio relativo al recupero dell'intero feed di contenuti e alla 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: entry.Kind() può essere utilizzato per determinare il tipo di una voce.

L'oggetto feed risultante è un gdata.sites.data.ContentFeed contenente un elenco di gdata.sites.data.ContentEntry. Ogni voce rappresenta una pagina/elemento diverso all'interno del sito dell'utente e include elementi specifici per il tipo di voce in questione. 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 relative al feed di contenuti

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

Nota: gli esempi in questa sezione utilizzano il metodo helper gdata.sites.client.MakeContentFeedUri() per creare l'URI di base del feed dei 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ù tipi, separa ogni kind con una virgola. Ad esempio, questo snippet restituisce le 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 in base al percorso

Se conosci il percorso relativo di una pagina all'interno del sito Google, puoi utilizzare il parametro path per recuperare quella pagina specifica. 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 in una pagina padre

Se conosci l'ID voce dei contenuti di una pagina (ad es. "1234567890" nell'esempio di seguito), puoi utilizzare il parametro parent per recuperare tutte le relative voci figlio (se 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



Creazione di contenuti

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

È possibile creare nuovi contenuti (pagine web, pagine di elenchi, archivi di dati, pagine di annunci e così via) utilizzando CreatePage(). Il primo argomento di questo metodo deve essere il tipo di pagina da creare, seguito dal titolo e dai relativi contenuti HTML.

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

Creare nuovi elementi / pagine

In questo esempio viene creato un nuovo webpage sotto il livello superiore, include codice ISBN per il corpo della pagina e il titolo dell'intestazione viene impostato su "Nuovo titolo pagina web":

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 sotto forma di gdata.sites.gdata.ContentEntry.

Per creare tipi di voci più complesse da completare al momento della creazione (ad es. un listpage con intestazioni di colonna), devi creare gdata.sites.data.ContentEntry manualmente, compilare le proprietà che ti interessano e chiamare client.Post().

Creazione di elementi/pagine in percorsi dell'URL personalizzati

Per impostazione predefinita, l'esempio precedente verrebbe creato nell'URL http://sites.google.com/domainName/siteName/new-webpage-title e avrà l'intestazione di pagina "Nuovo titolo pagina web". Ciò significa che il titolo è 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 di contenuti. L'helper CreatePage() lo fornisce come argomento facoltativo per la parola chiave.

In questo esempio viene creata una nuova pagina filecabinet con l'intestazione "Archiviazione file", ma viene creata nell'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 la denominazione del percorso dell'URL di una pagina:

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

Creazione di pagine secondarie

Per creare pagine secondarie (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 personale completo della voce dei contenuti.

Questo esempio esegue una query nel feed di contenuti per announcementpage e crea un nuovo announcement sotto il primo 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 padre. Di conseguenza, devi impostare un link principale nell'elemento ContentEntry che stai tentando di caricare. Per ulteriori informazioni, consulta la sezione Creazione di pagine secondarie.

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

Caricamento di allegati

In questo esempio viene caricato un file PDF nel primo filecabinet trovato nel feed dei contenuti dell'utente. L'allegato viene creato con il titolo "Manuale per i nuovi dipendenti" e una descrizione (facoltativa), "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.

Caricamento di un allegato in una cartella

I file cabine in Google Sites supportano le cartelle. UploadAttachment() fornisce un ulteriore argomento della parola chiave, folder_name, che puoi utilizzare per caricare un allegato in una cartella filecabinet. È sufficiente specificare 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 passa un oggetto gdata.data.MediaSource a UploadAttachment() anziché un percorso file. Inoltre, non trasmette alcun tipo di contenuti. ma viene 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 funzione è analoga al metodo di caricamento "Aggiungi file tramite URL" nell'interfaccia utente di Google Sites.

Nota: gli allegati web possono essere creati solo in filecabinet. Non possono essere caricati in altri tipi di pagine.

In questo esempio viene creato un allegato web sotto il primo filecabinet trovato nel feed dei contenuti dell'utente. Il titolo e la descrizione (facoltativa) sono impostati rispettivamente su "Logo Google" e "Belli colori".

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 rimanda 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

È possibile modificare i metadati (titolo, pageName ecc.) e i contenuti della pagina di qualsiasi tipo di voce utilizzando il metodo Update() del client.

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

  • Il titolo viene modificato in "Titolo aggiornato"
  • I contenuti HTML della pagina vengono aggiornati in "Contenuti HTML aggiornati"
  • L'intestazione della prima colonna dell'elenco è stata 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 i contenuti del nuovo file e chiamando il metodo Update() del client. Possono essere aggiornati anche i metadati dell'allegato, ad esempio titolo e descrizione, o semplicemente i metadati. Questo esempio mostra come aggiornare contemporaneamente i contenuti e i metadati del 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 dei contenuti

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

client.Delete(content_entry)

Puoi anche passare il metodo Delete() del 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 include un link src dei contenuti che può essere utilizzato per scaricare i contenuti del file. Il client Sites contiene un metodo helper per accedere e scaricare il file da questo link: DownloadAttachment(). Accetta un URI gdata.sites.data.ContentEntry o di download per il primo argomento e un percorso file in cui salvare l'allegato come secondo.

Questo esempio recupera una determinata voce di allegato (tramite una query sul 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 adeguata al tipo di contenuti dell'allegato. Il tipo di contenuti è disponibile 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, usa _GetFileContent() per recuperare i contenuti del file e archiviarli in memoria.

In questo esempio viene scaricato 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à: un utente, un gruppo di utenti, un dominio o l'accesso predefinito (ovvero un sito pubblico). Le voci verranno visualizzate solo per le entità con accesso esplicito: verrà mostrata una voce per ogni indirizzo email nel riquadro "Persone con accesso" della 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 ruolo rappresenta il livello di accesso che un'entità può avere. Esistono quattro valori possibili dell'elemento gAcl:role:

  • lettore: un visualizzatore (equivalente all'accesso di sola lettura).
  • writer: un collaboratore (equivalente all'accesso in lettura/scrittura).
  • owner: in genere l'amministratore del sito (equivalente all'accesso in lettura/scrittura).

Ambiti

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

  • utente: il valore di un indirizzo email, ad esempio "utente@gmail.com".
  • group: un indirizzo email di un gruppo Google, ad esempio "gruppo@dominio.com".
  • domain: un nome di dominio di G Suite, ad esempio "dominio.com".
  • default: esiste un solo ambito possibile di tipo "default", privo di valore (ad esempio <gAcl:scope type="default">). Questo ambito specifico controlla l'accesso di cui ogni utente dispone per impostazione predefinita su un sito pubblico.

Nota: i domini non possono avere un valore gAcl:role impostato sull'accesso "proprietario", ma 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 usando il metodo GetAclFeed().

L'esempio seguente recupera il feed ACL per il sito attualmente impostato nell'oggetto SitesClient e stampa le voci di autorizzazione:

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 utilizzando le voci del SiteFeed, ogni SiteEntry contiene un link al relativo feed ACL. Ad esempio, questo snippet recupera il primo sito nel feed 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: alcuni ACL di condivisione potrebbero essere possibili solo se il dominio è configurato in modo da consentire queste autorizzazioni (ad esempio se è abilitata la condivisione all'esterno del dominio per i domini G Suite 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 possibili valori di AclScope e AclRoles.

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

Analogamente alla condivisione di un sito con un singolo utente, puoi condividere un sito all'interno di un gruppo Google o di un dominio G Suite. I valori scope necessari sono elencati di seguito.

Condivisione con l'indirizzo email di un 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 in cui è ospitato il sito. Ad esempio, http://sites.google.com/a/dominio1.com/sitoA può condividere l'intero sito solo con dominio1.com e non con dominio2.com. I siti che non sono ospitati su un dominio G Suite (ad es. http://sites.google.com/site/siteB) non possono invitare domini.

Modificare le 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 nostro acl_entry precedente della sezione Condivisione di un sito, aggiornando "utente@example.com" in modo che diventi uno scrittore (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 in corso...

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() del link edit della voce acl e/o 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

Recuperare di nuovo un feed o una voce

Se vuoi recuperare un feed o una voce recuperati in precedenza, puoi migliorare l'efficienza comunicando al server di inviare l'elenco o la voce solo se sono cambiati dall'ultima volta che li hai recuperati.

Per eseguire questo tipo di recupero condizionale, trasmetti un valore ETag a GetEntry(). Ad esempio, se avessi 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 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