Importante: questo documento è stato scritto prima del 2012. Opzioni di autenticazione descritte in questo documento (OAuth 1.0, AuthSub e ClientLogin) sono state ufficialmente ritirato dal 20 aprile 2012 e non sono più disponibili. Ti invitiamo a eseguire la migrazione OAuth 2.0, il prima 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. L'applicazione client può anche richiedere un elenco delle attività recenti, recuperare la cronologia delle revisioni e scaricare allegati.
Oltre a fornire alcune informazioni sulle funzionalità dell'API Sites Data, questa guida fornisce esempi di interazione con l'API. utilizzando la libreria client Python. Per informazioni sulla configurazione della libreria client, consulta Introduzione alla libreria client Python dei dati di Google. Se ti interessa per saperne di più sul protocollo sottostante utilizzato dalla libreria client Python per interagire con l'API della versione classica di Sites, consulta il guida al protocollo.
Pubblico
Questo documento è rivolto agli sviluppatori che desiderano scrivere applicazioni client che interagiscano con Google Sites. utilizzando la libreria client di Python per i dati di Google.
Per 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 di dati di Google per assistenza nell'installazione e nell'utilizzo del client.
Esecuzione dell'esempio
Un esempio funzionante 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 obbligatori non vengono forniti, l'app ti chiederà di inserire questi valori. L'esempio consente all'utente di eseguire una serie di operazioni che dimostrare 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 anche richiedere l'autenticazione tramite AuthSub, OAuth ClientLogin.
Per includere gli esempi in questa guida nel tuo codice, sono necessarie le 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 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
segui il formato: company-applicationname-version
Nota: il resto della guida presuppone che tu abbia creato un oggetto SitesClient
nella variabile client
.
Autenticazione nella versione classica dell'API Sites
La libreria client Python può essere utilizzata per lavorare con feed pubblici o privati. L'API Sites Data fornisce l'accesso a siti privati e pubblici feed, a seconda delle autorizzazioni di un Sito e dell'operazione che stai tentando di eseguire. Ad esempio, potresti riuscire a leggere il feed di contenuti di un sito pubblico ma non aggiornarlo, qualcosa che richiede un client autenticato. Questa operazione può essere eseguita tramite ClientLogin autenticazione nome utente/password, AuthSub oppure OAuth.
Per ulteriori informazioni su AuthSub, OAuth e ClientLogin, consulta la panoramica sull'autenticazione delle API di dati di Google.
AuthSub per applicazioni web
L'autenticazione AuthSub per le applicazioni web dovrebbe essere utilizzata dalle applicazioni client che devono autenticare i propri utenti agli account Google o G Suite. L'operatore non ha bisogno di accedere al nome utente e alla password dell'utente di Google Sites, ma solo un Il token AuthSub è obbligatorio.
Visualizza le istruzioni per incorporare AuthSub nella tua applicazione web
Richiedi un token monouso
Quando l'utente visita per la prima volta la tua applicazione, deve eseguire l'autenticazione. In genere, gli sviluppatori stampano del testo e un link che indirizza l'utente
alla pagina di approvazione AuthSub per autenticare l'utente e richiedere l'accesso ai propri documenti. La libreria client Python di 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, inserisci il nome di 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
Gestore AuthSubRequest):
- L'URL successivo, a cui Google reindirizzerà
dopo che l'utente accede al proprio account e concede l'accesso;
http://www.example.com/myapp.py
nell'esempio precedente - Ambito:
https://sites.google.com/feeds/
- secure, un valore booleano che indica se il token verrà utilizzato o meno in modalità sicura e registrata;
True
nell'esempio precedente - session, un secondo valore booleano che indica se il token monouso verrà successivamente scambiato con un token di sessione o meno;
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 di 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,
quindi archiviare il token nel database per
richiamarlo per utilizzarlo in un secondo momento. Non è necessario reindirizzare l'utente a AuthSub a ogni esecuzione dell'applicazione.
Utilizza client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR)
per impostare un token esistente sul client.
OAuth per applicazioni web o installate/per dispositivi mobili
OAuth può essere utilizzato in alternativa ad AuthSub ed è destinato alle applicazioni web. OAuth è un processo simile all'utilizzo della modalità sicura e registrata di AuthSub. tutte le richieste di dati devono essere firmate digitalmente e devi registrare il dominio.
Visualizza le istruzioni per incorporare OAuth nell'applicazione installata
Recupero di un token di richiesta
Consulta l'articolo Utilizzare OAuth con le librerie client dell'API di dati di Google.
Autorizzazione di un token di richiesta
Consulta l'articolo Utilizzare OAuth con le librerie client dell'API di dati di Google.
Upgrade a un token di accesso
Consulta l'articolo Utilizzare OAuth con le librerie client dell'API di dati di Google.
Suggerimento: una volta che l'applicazione ha acquisito un token di accesso OAuth,
quindi archiviare il token nel database per
richiamarlo per utilizzarlo in un secondo momento. Non è necessario reindirizzare l'utente tramite OAuth a ogni esecuzione dell'applicazione.
Utilizza client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET)
per impostare un token esistente sul client.
ClientLogin per applicazioni installate/mobile
ClientLogin deve essere utilizzato da applicazioni installate o per dispositivi mobili che devono autenticare i propri utenti agli Account Google. Alla prima esecuzione, l'applicazione richiede all'utente il nome utente e la password. Per le 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
GDClient
Specifica l'indirizzo email e
password dell'utente per conto del quale il cliente effettua le richieste. Ad esempio:
client = gdata.sites.client.SitesClient(source='yourCo-yourAppName-v1') client.ClientLogin('user@gmail.com', 'pa$$word', client.source);
Suggerimento: dopo che l'applicazione ha autenticato l'utente per la prima volta, memorizza il token di autenticazione nel database per richiamarlo per utilizzarlo in un secondo momento. Non è necessario richiedere all'utente la password a ogni esecuzione dell'applicazione. Per ulteriori informazioni, consulta la sezione Richiamo di un token di autenticazione.
Per ulteriori informazioni sull'utilizzo di ClientLogin nelle applicazioni Python, consulta Utilizzo di ClientLogin con le librerie client dell'API di dati di Google.
Feed sito
Il feed del sito può essere utilizzato per elencare i siti di Google Sites 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 l'intero sito.
Siti delle schede
Per elencare i siti a cui un utente ha accesso, utilizza il metodo GetSiteFeed()
del client. Il metodo prende un'opzione
uri
, che puoi utilizzare per specificare un URI del feed del sito alternativo. Per impostazione predefinita, GetSiteFeed()
utilizza il nome del sito e il dominio impostati nell'oggetto client. Consulta la sezione Come iniziare per
ulteriori informazioni sull'impostazione di questi valori nell'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 l'URI del feed ACL.
Creazione di 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 di GetSiteFeed()
, CreateSite()
accetta anche un
l'argomento facoltativo uri
, che puoi utilizzare per specificare un URI del feed del sito alternativo (nel caso di creazione
il sito in un dominio diverso da quello impostato nell'oggetto SitesClient
).
Ecco un esempio di creazione di un nuovo sito con il tema "slate" e fornendo una titolo e 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 crea 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 viene creato correttamente, il server risponderà con gdata.sites.data.SiteEntry
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 parola chiave source_site
.
Tutti i siti copiati avranno questo link, a cui è possibile accedere tramite entry.FindSourceLink()
. Ecco un esempio di duplicazione del sito
creati 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:
- Puoi copiare solo i siti e i modelli di siti di proprietà dell'utente autenticato.
- Puoi anche copiare un modello di sito. Un sito è un modello se l'opzione "Pubblica questo sito come modello" sia selezionata nella pagina delle impostazioni di Google Sites.
- Puoi copiare un sito da un altro dominio, a condizione che 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. Questo
esempio utilizza il metodo GetEntry()
per recuperare innanzitutto un SiteEntry
, quindi 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)
Recupero del feed Attività
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. Consulta Autenticazione nel servizio Sites.
Puoi recuperare l'attività recente (modifiche) di un sito recuperando il feed attività.
Il metodo GetActivityFeed()
di 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
una modifica apportata al Sito.
Recupero della cronologia delle 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. Consulta Autenticazione nel servizio Sites.
Il feed delle revisioni fornisce informazioni sulla cronologia delle revisioni per qualsiasi voce di contenuto. GetRevisionFeed()
può essere usato per recuperare le revisioni di una determinata voce di contenuto. Il metodo richiede un valore facoltativo uri
parametro che accetta gdata.sites.data.ContentEntry
, l'URI completo di una voce di contenuti o l'ID di una voce di contenuto.
In questo esempio viene eseguita una query sul feed di 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 come il contenuto
alla revisione, al numero di versione e alla data di creazione della nuova versione.
Feed di contenuti
Recupero del feed di contenuti in corso...
Nota: il feed di 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 Autenticazione nel servizio Sites.
Il feed di contenuti restituisce i contenuti più recenti di un sito. È possibile accedervi chiamando il comando lib
Metodo GetContentFeed()
, che accetta un parametro facoltativo stringa uri
per il passaggio
per creare una query personalizzata.
Ecco un esempio di come recuperare l'intero feed di contenuti e stampare 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/un elemento diverso all'interno
sito dell'utente e contiene elementi specifici per il tipo di voce. Per un'idea migliore, vedi l'applicazione di esempio
di alcune delle proprietà disponibili in ogni tipo di voce.
Esempi di query sui feed di contenuti
Puoi cercare nel feed di contenuti utilizzando alcuni dei parametri di query standard dell'API di dati di Google. e quelle specifiche dell'API della versione classica di Sites. Per informazioni più dettagliate e un elenco completo dei parametri supportati, consulta 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 di contenuti.
Recupero di tipi di voce 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 filecabinet
e
listpage
voci:
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 restituirebbe la pagina che si trova in
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 sotto una pagina principale
Se conosci l'ID dell'inserimento dei contenuti di una pagina (ad es. "1234567890" nell'esempio riportato di seguito), puoi utilizzare il parametro parent
per recuperare tutte le 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.
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 elenco, armadi di file, 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.
Creazione di nuovi elementi / pagine
In questo esempio viene creato un nuovo webpage
sotto il livello più alto e include un codice HTML per il corpo della pagina.
e imposta il titolo 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, come gdata.sites.gdata.ContentEntry
.
Per creare tipi di voci più complessi compilati al momento della creazione (ad es. listpage
con intestazioni di colonna), devi creare
gdata.sites.data.ContentEntry
manualmente, compila le proprietà che ti interessano e chiama client.Post()
.
Creazione di elementi/pagine nei percorsi degli URL personalizzati
Per impostazione predefinita, l'esempio precedente viene creato nell'URL
http://sites.google.com/domainName/siteName/new-webpage-title
e
avere un'intestazione di pagina "Nuovo titolo della 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 dei contenuti. L'aiutante di CreatePage()
lo fornisce come argomento parola chiave facoltativo.
In questo esempio viene creata una nuova pagina filecabinet
con l'intestazione "Archiviazione file", ma la pagina viene creata
dell'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:
page_name
, se presente. Deve soddisfarea-z, A-Z, 0-9, -, _
.title
non deve essere null se il nome pagina non è presente. La normalizzazione consiste nel tagliare e comprimere lo spazio vuoto in "-" e rimuovi i caratteri non corrispondenti aa-z, A-Z, 0-9, -, _
.
Creazione di pagine secondarie
Per creare pagine secondarie (secondarie) sotto una pagina principale, utilizza l'argomento parola chiave parent
di CreatePage()
.
parent
può essere un gdata.sites.gdata.ContentEntry
o una stringa che rappresenta il
ID completo della voce di contenuti.
Questo esempio esegue una query nel feed di contenuti per trovare 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
Come in Google Sites, l'API supporta il caricamento degli allegati in una pagina schedario o pagina principale. Gli allegati devono essere caricati
a una pagina principale. Di conseguenza, devi impostare un link principale sul file ContentEntry
che stai cercando 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 di 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 viene eseguito correttamente, attachment
conterrà una copia dell'allegato creato sul server.
Caricamento di un allegato in una cartella
Gli armadi file in Google Sites supportano le cartelle. Il UploadAttachment()
fornisce un'ulteriore 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')
Tieni presente che in questo esempio viene invece passato un oggetto gdata.data.MediaSource
a UploadAttachment()
di un percorso file. Inoltre, non trasmette un tipo di contenuti. Il tipo di contenuto viene invece specificato nell'oggetto MediaSource.
Allegati web
Gli allegati web sono tipi speciali di allegati. Essenzialmente, si tratta di link ad altri file sul web
che puoi aggiungere alle tue schede filecabinet
. Questa funzionalità è analoga ad "Aggiungi file tramite URL" di caricamento nella UI di Google Sites.
Nota: gli allegati web possono essere creati solo in filecabinet
. Non possono essere caricati su altri tipi di pagine.
In questo esempio viene creato un allegato web sotto il primo filecabinet
trovato nel feed di contenuti dell'utente.
Il titolo e la descrizione (facoltativa) sono impostati su "GoogleLogo". e "colori piacevoli", rispettivamente.
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
.
Aggiornamento dei contenuti
Aggiornamento dei metadati e/o dei contenuti HTML di una pagina
I metadati (title, pageName ecc.) e i contenuti della pagina di qualsiasi tipo di voce possono essere modificati
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"
- 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!'
Sostituire i contenuti e i metadati di un allegato
Puoi sostituire i contenuti del file di un allegato creando un nuovo oggetto MediaSource
con i nuovi contenuti del file e chiamare il metodo Update()
del client. L'ID
è possibile aggiornare anche i metadati (come titolo e descrizione) o solo 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)
Eliminazione di contenuti
Per rimuovere una pagina o un elemento da un sito Google, devi prima recuperare la voce dei contenuti, quindi chiamare il metodo Delete()
del client.
client.Delete(content_entry)
Puoi anche trasmettere il metodo Delete()
del link edit
della voce di contenuto 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.
Download degli allegati
Ogni voce attachment
contiene un link src
che può essere utilizzato per scaricare i contenuti del file.
Il client Sites contiene un metodo di supporto per accedere al file e scaricarlo da questo link: DownloadAttachment()
.
Accetta un gdata.sites.data.ContentEntry
o un URI di download per il primo argomento e un percorso file per salvare l'allegato
come secondo.
Questo esempio recupera una determinata voce di allegato (eseguendo 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 appropriata per il 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 es. se la tua app è in esecuzione in Google App Engine).
In questi casi, utilizza _GetFileContent()
per recuperare i contenuti del file e archiviarli in memoria.
Questo download di esempio è un allegato a una memoria.
try: file_contents = client._GetFileContent(attachment.content.src) # TODO: Do something with the file contents except gdata.client.RequestError, e: raise e
Feed ACL
Panoramica delle autorizzazioni di condivisione (ACL)
Ogni voce ACL nel feed ACL rappresenta un ruolo di accesso di una particolare entità: 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. Ne verrà mostrata una sola per ogni indirizzo email nella sezione "Persone con accesso" nella schermata di condivisione della UI di Google Sites. Pertanto, gli amministratori di dominio non vengono mostrati, anche se hanno accesso implicito a un sito.
Ruoli
L'elemento Role rappresenta un livello di accesso che un'entità può avere. Esistono quattro possibili valori per l'elemento gAcl:role
:
- reader: 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 ambito rappresenta l'entità con questo livello di accesso. Esistono quattro tipi possibili di elemento gAcl:scope
:
- utente: un valore dell'indirizzo email, ad esempio "utente@gmail.com".
- gruppo: l'indirizzo email di un gruppo Google, ad esempio "gruppo@dominio.com".
- domain: un nome di dominio G Suite, ad esempio "dominio.com".
- default: esiste un solo ambito possibile di tipo "default", che non ha alcun valore.
(ad es.
<gAcl:scope type="default">
). Questo particolare ambito controlla l'accesso di cui dispone per impostazione predefinita qualsiasi utente su un sito pubblico.
Nota: i domini non possono avere un valore gAcl:role
imposta su "proprietario" all'accesso, possono essere solo lettori o autori.
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 nell'oggetto SitesClient
,
e stampa le voci relative alle 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 utilizzando le voci di 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 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 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 gdata.sites.gdata.AclEntry
con
Valori di gdata.acl.data.AclScope
e gdata.acl.data.AclRole
. Consulta le
Sezione Panoramica del feed ACL per la possibile AclScope
e AclRoles
.
In questo esempio vengono concesse 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 con un
Gruppo Google o dominio G Suite. I valori di 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 su cui è ospitato il sito. Ad esempio, http://sites.google.com/a/dominio1.com/sitoA può solo condividere l'intero sito con dominio1.com, non dominio2.com. Siti che non sono ospitati su un dominio G Suite (ad es. http://sites.google.com/site/siteB) non possono invitare domini.
Modifica delle autorizzazioni di condivisione
Per un'autorizzazione di condivisione esistente su un sito, recupera innanzitutto l'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 valore acl_entry
precedente dalla sezione Condivisione di un sito,
aggiornando "utente@example.com" Essere 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
Per rimuovere un'autorizzazione di condivisione, devi prima recuperare AclEntry
, quindi chiamare il metodo Delete()
del client.
client.Delete(acl_entry)
Puoi anche passare il metodo Delete()
del collegamento 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.
Argomenti speciali
Recupero di un feed o di una voce
Se vuoi recuperare un feed o una voce già recuperati, puoi migliorare l'efficienza comunicando il server di inviare l'elenco o la voce solo se è stata modificata dall'ultima volta che l'hai recuperata.
Per eseguire questo tipo di recupero condizionale, passa un valore ETag all'elemento GetEntry()
. Ad esempio, se avevi 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
, il parametro
L'ETag corrisponde alla versione sul server, il che significa che disponi della copia più aggiornata.
Tuttavia, se un altro cliente/utente ha apportato modifiche, la nuova voce verrà restituita in entry
senza generare alcuna eccezione.
Per ulteriori informazioni sugli ETag, consulta la guida di riferimento delle API di dati di Google.