Guide Python

Important : Ce document a été rédigé avant 2012. Les options d'authentification décrites dans ce document (OAuth 1.0, AuthSub et ClientLogin) ont été officiellement abandonnées depuis le 20 avril 2012 et ne sont plus disponibles. Nous vous encourageons à passer à OAuth 2.0 dès que possible.

L'API Google Sites Data permet aux applications clientes d'accéder, de publier et de modifier le contenu d'un site Google. Votre application cliente peut également demander une liste des activités récentes, récupérer l'historique des révisions et télécharger des pièces jointes.

En plus de fournir des informations sur les fonctionnalités de l'API Sites Data, ce guide fournit des exemples d'interaction avec l'API à l'aide de la bibliothèque cliente Python. Pour obtenir de l'aide pour configurer la bibliothèque cliente, consultez la section Premiers pas avec la bibliothèque cliente Google Data Python. Pour en savoir plus sur le protocole sous-jacent utilisé par la bibliothèque cliente Python pour interagir avec l'API Sites classique, consultez le guide du protocole.

Audience

Ce document est destiné aux développeurs qui souhaitent écrire des applications clientes qui interagissent avec Google Sites à l'aide de la bibliothèque cliente Google Data Python.

Premiers pas

Pour utiliser la bibliothèque cliente Python, vous devez disposer de Python 2.2+ et des modules répertoriés sur la page wiki DependencyModules. Après avoir téléchargé la bibliothèque cliente, consultez Premiers pas avec la bibliothèque Python Google Data pour obtenir de l'aide pour installer et utiliser le client.

Exécuter l'exemple

Un exemple fonctionnel complet se trouve dans le sous-répertoire samples/sites du dépôt Mercurial du projet (/samples/sites/sites_example.py).

Exécutez l'exemple comme suit :

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

Si les indicateurs obligatoires ne sont pas fournis, l'application vous invite à saisir ces valeurs. L'exemple permet à l'utilisateur d'effectuer un certain nombre d'opérations qui montrent comment utiliser l'API Google Sites classique. Vous devez donc vous authentifier pour effectuer certaines opérations (par exemple, modifier du contenu). Le programme vous invite également à vous authentifier via AuthSub, OAuth ou ClientLogin.

Pour inclure les exemples de ce guide dans votre propre code, vous avez besoin des instructions import suivantes :

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

Vous devez également configurer un objet SitesClient, qui représente une connexion client à l'API Sites classique. Transmettez le nom de votre application et le nom de l'espace Web du site (à partir de son URL) :

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

Pour travailler avec un site hébergé sur un domaine G Suite, définissez le domaine à l'aide du paramètre domain :

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

Dans les extraits ci-dessus, l'argument source est facultatif, mais recommandé pour la journalisation. Il doit respecter le format suivant: company-applicationname-version

Remarque : Le reste du guide suppose que vous avez créé un objet SitesClient dans la variable client.

S'authentifier auprès de l'API de la version classique de Google Sites

La bibliothèque cliente Python peut être utilisée pour travailler avec des flux publics ou privés. L'API Sites Data permet d'accéder à des flux privés et publics, en fonction des autorisations accordées à un site et de l'opération que vous essayez d'effectuer. Par exemple, vous pouvez être en mesure de lire le flux de contenu d'un site public, mais pas de le mettre à jour (ce qui nécessite un client authentifié). Vous pouvez le faire via l'authentification par nom d'utilisateur/mot de passe ClientLogin, AuthSub ou OAuth.

Pour en savoir plus sur AuthSub, OAuth et ClientLogin, consultez la présentation de l'authentification via les API Google Data.

AuthSub pour les applications Web

L'authentification AuthSub pour les applications Web doit être utilisée par les applications clientes qui doivent authentifier leurs utilisateurs auprès de comptes Google ou G Suite. L'opérateur n'a pas besoin d'accéder au nom d'utilisateur ni au mot de passe de l'utilisateur Google Sites. Seul un jeton AuthSub est requis.

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

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)

OAuth pour le Web ou les applications installées/mobiles

OAuth peut être utilisé à la place d'AuthSub et est destiné aux applications Web. OAuth est semblable à l'utilisation du mode sécurisé et enregistré d'AuthSub, car toutes les requêtes de données doivent être signées numériquement et vous devez enregistrer votre domaine.

ClientLogin pour les applications installées/mobiles

ClientLogin doit être utilisé par les applications installées ou mobiles qui doivent authentifier leurs utilisateurs auprès de comptes Google. Lors de la première exécution, votre application invite l'utilisateur à saisir son nom d'utilisateur/mot de passe. Dans les requêtes ultérieures, un jeton d'authentification est référencé.

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

Haut de page

Flux de site

Le flux de sites permet de lister les sites Google Sites dont un utilisateur est propriétaire ou pour lesquels il dispose d'autorisations de consultation. Vous pouvez également l'utiliser pour modifier le nom d'un site existant. Enfin, pour les domaines G Suite, vous pouvez également l'utiliser pour créer et/ou copier un site entier.

Sites de référencement

Pour répertorier les sites auxquels un utilisateur a accès, utilisez la méthode GetSiteFeed() du client. La méthode accepte un argument facultatif, uri, que vous pouvez utiliser pour spécifier un autre URI de flux de site. Par défaut, GetSiteFeed() utilise le nom et le domaine du site définis sur l'objet client. Pour en savoir plus sur la définition de ces valeurs sur votre objet client, consultez la section Premiers pas.

Voici un exemple de récupération de la liste des sites de l'utilisateur authentifié:

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

L'extrait ci-dessus imprime le titre et le nom du site à partir duquel il a été copié, ainsi que l'URI du flux de la LCA correspondante.

Création de sites

Remarque: Cette fonctionnalité n'est disponible que pour les domaines G Suite.

Les nouveaux sites peuvent être provisionnés en appelant la méthode CreateSite() de la bibliothèque. Comme pour l'outil d'aide GetSiteFeed(), CreateSite() accepte également un argument facultatif, uri, que vous pouvez utiliser pour spécifier un URI de flux de site alternatif (si vous créez le site sous un domaine différent de celui défini sur votre objet SitesClient).

Voici un exemple de création d'un site avec le thème "ardoise", en fournissant un titre et une description (facultatif) :

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 demande ci-dessus entraîne la création d'un site sous le domaine G Suite example2.com. L'URL du site sera donc https://sites.google.com/a/example2.com/titre-de-mon-site.

Si le site est créé, le serveur répond avec un objet gdata.sites.data.SiteEntry, renseigné par les éléments ajoutés par le serveur : un lien vers le site, un lien vers le flux ACL du site, le nom du site, le titre, le résumé, etc.

Copier un site

Remarque : Cette fonctionnalité n'est disponible que pour les domaines G Suite.

CreateSite() peut également être utilisé pour copier un site existant. Pour ce faire, transmettez l'argument de mot clé source_site. Tous les sites copiés contiennent ce lien, qui est accessible via entry.FindSourceLink(). Voici un exemple de dupliquer le site créé dans la section Créer des sites :

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

Points importants :

• Seuls les sites et les modèles de sites appartenant à l'utilisateur authentifié peuvent être copiés.
• Vous pouvez également copier un modèle de site. Un site est un modèle si l'option "Publier ce site comme modèle" est cochée sur la page des paramètres de Google Sites.
• Vous pouvez copier un site à partir d'un autre domaine, à condition d'être listé comme propriétaire sur le site source.

Mettre à jour les métadonnées d'un site

Pour modifier le titre ou le résumé d'un site, vous avez besoin d'un SiteEntry contenant le site en question. Cet exemple utilise la méthode GetEntry() pour d'abord extraire un SiteEntry, puis modifier son titre, sa description et sa balise de catégorie :

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)

Haut de page

Récupérer le flux d'activité

Remarque : Pour accéder à ce flux, vous devez être collaborateur ou propriétaire du site. Votre client doit s'authentifier à l'aide d'un jeton AuthSub, OAuth ou ClientLogin. Consultez la section S'authentifier auprès du service Sites.

Vous pouvez extraire l'activité récente (modifications) d'un site en extrayant le flux d'activité. La méthode GetActivityFeed() de la bibliothèque permet d'accéder à ce flux:

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)

L'appel de GetActivityFeed() renvoie un objet gdata.sites.data.ActivityFeed contenant une liste de gdata.sites.data.ActivityEntry. Chaque entrée d'activité contient des informations sur une modification apportée au site.

Haut de page

Récupération de l'historique des révisions

Remarque : Pour accéder à ce flux, vous devez être collaborateur ou propriétaire du site. Votre client doit s'authentifier à l'aide d'un jeton AuthSub, OAuth ou ClientLogin. Consultez la section S'authentifier auprès du service Sites.

Le flux des révisions fournit des informations sur l'historique des révisions pour chaque entrée de contenu. La méthode GetRevisionFeed() permet d'extraire les révisions d'une entrée de contenu donnée. La méthode utilise un paramètre uri facultatif qui accepte un élément gdata.sites.data.ContentEntry, l'URI complet d'une entrée de contenu ou un ID d'entrée de contenu.

Cet exemple interroge le flux de contenu et extrait le flux de révisions de la première entrée de contenu :

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]

L'appel de GetRevisionFeed() renvoie un objet gdata.sites.data.RevisionFeed contenant une liste de gdata.sites.data.RevisionEntry. Chaque entrée de révision contient des informations telles que le contenu de cette révision, le numéro de version et la date de création de la nouvelle version.

Haut de page

Flux de contenu

Récupération du flux de contenu

Remarque : L'accès au flux de contenus peut nécessiter ou non une authentification, en fonction des autorisations de partage du site. Si le site n'est pas public, votre client doit s'authentifier à l'aide d'un jeton AuthSub, OAuth ou ClientLogin. Consultez la section S'authentifier auprès du service Sites.

Le flux de contenu renvoie le contenu le plus récent d'un site. Vous pouvez y accéder en appelant la méthode GetContentFeed() de la lib, qui accepte un paramètre de chaîne uri facultatif pour transmettre une requête personnalisée.

Voici un exemple de récupération de l'intégralité du flux de contenu et d'impression de certains éléments intéressants :

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

Conseil: entry.Kind() peut être utilisé pour déterminer le type d'une entrée.

L'objet feed obtenu est un gdata.sites.data.ContentFeed contenant une liste de gdata.sites.data.ContentEntry. Chaque entrée représente une page/un élément différent sur le site de l'utilisateur et comporte des éléments spécifiques au type d'entrée. Consultez l'exemple d'application pour mieux comprendre certaines des propriétés disponibles pour chaque type d'entrée.

Haut de page

Exemples de requêtes de flux de contenu

Vous pouvez rechercher dans le flux de contenu à l'aide de certains des paramètres de requête standards de l'API Google Data et de ceux spécifiques à l'API Sites classique. Pour en savoir plus et obtenir la liste complète des paramètres acceptés, consultez le guide de référence.

Remarque : Les exemples de cette section utilisent la méthode d'assistance gdata.sites.client.MakeContentFeedUri() pour créer l'URI de base du flux de contenu.

Récupérer des types d'entrées spécifiques

Pour ne récupérer qu'un type d'entrée particulier, utilisez le paramètre kind. Par exemple, cet extrait ne renvoie que des entrées attachment:

kind = 'webpage'

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

Pour renvoyer plusieurs types, séparez chaque kind par une virgule. Par exemple, cet extrait renvoie des entrées filecabinet et listpage :

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

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

Récupérer une page par chemin

Si vous connaissez le chemin d'accès relatif d'une page du site Google, vous pouvez utiliser le paramètre path pour récupérer cette page en particulier. Cet exemple renverrait la page située à l'emplacement 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)

Récupérer toutes les entrées d'une page parente

Si vous connaissez l'ID d'entrée de contenu d'une page (par exemple, "1234567890" dans l'exemple ci-dessous), vous pouvez utiliser le paramètre parent pour récupérer toutes ses entrées enfants (le cas échéant) :

parent = '1234567890'

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

Pour en savoir plus sur les paramètres supplémentaires, consultez le guide de référence.

Haut de page

Créer du contenu

Remarque:Avant de créer le contenu d'un site, assurez-vous de l'avoir configuré dans le client.
client.site = "siteName"

Vous pouvez créer du contenu (pages Web, pages de liste, cabinets de fichiers, pages d'annonces, etc.) à l'aide de CreatePage(). Le premier argument de cette méthode doit être le type de page à créer, suivi du titre et de son contenu HTML.

Pour obtenir la liste des types de nœuds compatibles, consultez le paramètre kind dans le guide de référence.

Création de nouveaux éléments / pages

Cet exemple crée un webpage sous le niveau supérieur, inclut du code XHTML pour le corps de la page et définit le titre de l'en-tête sur "Nouveau titre de la page Web" :

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

Si la requête aboutit, entry contient une copie de l'entrée créée sur le serveur, sous la forme d'un gdata.sites.gdata.ContentEntry.

Pour créer un type d'entrée plus complexe qui est renseigné lors de la création (par exemple, un listpage avec des titres de colonnes), vous devez créer manuellement le gdata.sites.data.ContentEntry, renseigner les propriétés qui vous intéressent et appeler client.Post().

Créer des articles/pages sous des chemins d'URL personnalisées

Par défaut, l'exemple précédent est créé sous l'URL http://sites.google.com/domainName/siteName/new-webpage-title et porte le titre de page "Nouveau titre de la page Web". Autrement dit, le titre est normalisé en new-webpage-title pour l'URL. Pour personnaliser le chemin d'accès à l'URL d'une page, vous pouvez définir la propriété page_name sur l'entrée de contenu. L'aide CreatePage() fournit cela en tant qu'argument de mot clé facultatif.

Cet exemple crée une page filecabinet avec un en-tête "File Storage", mais la crée sous l'URL http://sites.google.com/domainName/siteName/files (au lieu de http://sites.google.com/domainName/siteName/file-storage) en spécifiant la propriété page_name.

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

Le serveur utilise les règles de priorité suivantes pour nommer le chemin d'accès à l'URL d'une page :

1. page_name, si présent. Doit être conforme à a-z, A-Z, 0-9, -, _.
2. title : ne doit pas être nul si le nom de la page n'est pas indiqué. La normalisation consiste à couper et à réduire les espaces en tabulation à "-", et à supprimer les caractères qui ne correspondent pas à a-z, A-Z, 0-9, -, _.

Créer des sous-pages

Pour créer des sous-pages (enfants) sous une page parente, utilisez l'argument de mot clé parent de CreatePage(). parent peut être un gdata.sites.gdata.ContentEntry ou une chaîne représentant l'ID complet de l'entrée du contenu.

Cet exemple interroge le flux de contenu pour les announcementpage et crée un announcement sous le premier trouvé :

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

Importer des fichiers

Comme dans Google Sites, l'API permet d'importer des pièces jointes sur une page de classeur ou une page parente. Les pièces jointes doivent être importées sur une page parente. Vous devez donc définir un lien parent sur le ContentEntry que vous essayez d'importer. Pour en savoir plus, consultez la section Créer des sous-pages.

La méthode UploadAttachment() de la bibliothèque cliente fournit l'interface permettant d'importer des pièces jointes.

Transfert de pièces jointes

Cet exemple importe un fichier PDF dans le premier filecabinet trouvé dans le flux de contenu de l'utilisateur. Le fichier joint est créé avec le titre "Nouveau manuel du personnel" et une description (facultative) "Paquet RH".

uri = '%s?kind=%s' % (client.MakeContentFeedUri(),'filecabinet')
feed = client.GetContentFeed(uri=uri)

attachment = client.UploadAttachment('/path/to/file.pdf', feed.entry[0], content_type='application/pdf',
                                     title='New Employee Handbook', description='HR Packet')
print 'Uploaded. View it at: %s' % attachment.GetAlternateLink().href

Si l'importation réussit, attachment contient une copie de la pièce jointe créée sur le serveur.

Importer une pièce jointe dans un dossier

Les armoires à fichiers de Google Sites acceptent les dossiers. UploadAttachment() fournit un argument de mot clé supplémentaire, folder_name, que vous pouvez utiliser pour importer une pièce jointe dans un dossier filecabinet. Indiquez simplement le nom de ce dossier:

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

Notez que cet exemple transmet un objet gdata.data.MediaSource à UploadAttachment() au lieu d'un chemin d'accès. Il ne transmet pas non plus de type de contenu. Le type de contenu est spécifié sur l'objet MediaSource.

Pièces jointes Web

Les pièces jointes Web sont des types de pièces jointes spéciaux. Il s'agit essentiellement de liens vers d'autres fichiers sur le Web que vous pouvez ajouter à vos fiches filecabinet. Cette fonctionnalité est semblable à la méthode d'importation Ajouter un fichier par URL dans l'interface utilisateur de Google Sites.

Remarque: Les pièces jointes Web ne peuvent être créées qu'à partir d'un filecabinet. Vous ne pouvez pas les importer sur d'autres types de pages.

Dans cet exemple, une pièce jointe Web est créée sous le premier élément filecabinet trouvé dans le flux de contenu de l'utilisateur. Son titre et sa description (facultative) sont respectivement définis sur "GoogleLogo" et "nice colors".

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

L'appel crée un lien pointant vers l'image à l'adresse "http://www.google.com/images/logo.gif" dans filecabinet.

Haut de page

Mise à jour du contenu

Mettre à jour les métadonnées et/ou le contenu HTML d'une page

Les métadonnées (title, pageName, etc.) et le contenu de la page de tout type d'entrée peuvent être modifiés à l'aide de la méthode Update() du client.

Vous trouverez ci-dessous un exemple de mise à jour d'un listpage avec les modifications suivantes :

• Le titre est modifié pour devenir "Nouveau titre".
• Le contenu HTML de la page est remplacé par "Contenu HTML mis à jour".
• L'en-tête de la première colonne de la liste est remplacé par "Propriétaire".

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

Remplacement du contenu et des métadonnées d'une pièce jointe

Vous pouvez remplacer le contenu du fichier d'une pièce jointe en créant un objet MediaSource avec le nouveau contenu du fichier et en appelant la méthode Update() du client. Les métadonnées de la pièce jointe (telles que le titre et la description) peuvent également être modifiées, ou simplement les métadonnées. Cet exemple illustre la mise à jour simultanée du contenu et des métadonnées d'un fichier:

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)

Haut de page

Supprimer du contenu

Pour supprimer une page ou un élément d'un site Google, commencez par récupérer l'entrée de contenu, puis appelez la méthode Delete() du client.

client.Delete(content_entry)

Vous pouvez également transmettre à la méthode Delete() le lien edit de l'entrée de contenu et/ou forcer la suppression :

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

Pour en savoir plus sur les ETags, consultez le guide de référence des API Google Data.

Haut de page

Télécharger des pièces jointes

Chaque entrée attachment contient un lien de contenu src qui permet de télécharger le contenu du fichier. Le client Sites contient une méthode d'assistance permettant d'accéder au fichier et de le télécharger à partir de ce lien : DownloadAttachment(). Elle accepte un URI gdata.sites.data.ContentEntry ou de téléchargement pour son premier argument, ainsi qu'un chemin d'accès pour enregistrer la pièce jointe comme second argument.

Cet exemple extrait une entrée de pièce jointe particulière (en interrogeant son lien self) et télécharge le fichier au chemin spécifié:

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

Il appartient au développeur de l'application de spécifier une extension de fichier adaptée au type de contenu de la pièce jointe. Le type de contenu se trouve dans entry.content.type.

Dans certains cas, vous ne pourrez peut-être pas télécharger le fichier sur le disque (si votre application s'exécute dans Google App Engine, par exemple). Dans ces situations, utilisez _GetFileContent() pour extraire le contenu du fichier et le stocker en mémoire.

Cet exemple de téléchargement est une pièce jointe à la mémoire.

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

Haut de page

Flux LCA

Présentation des autorisations de partage (ACL)

Chaque entrée de LCA dans le flux de LCA représente un rôle d'accès d'une entité spécifique : un utilisateur, un groupe d'utilisateurs, un domaine ou l'accès par défaut (qui est un site public). Les entrées ne s'affichent que pour les entités disposant d'un accès explicite. Une entrée s'affiche pour chaque adresse e-mail dans le panneau "Utilisateurs disposant d'un accès" de l'écran de partage de l'interface utilisateur de Google Sites. Par conséquent, les administrateurs de domaine ne s'affichent pas, même s'ils disposent d'un accès implicite à un site.

Rôles

L'élément "role" représente un niveau d'accès qu'une entité peut avoir. L'élément gAcl:role peut avoir quatre valeurs:

• reader : lecteur (équivalent à l'accès en lecture seule).
• Rédacteur : collaborateur (équivalent à l'accès en lecture/écriture).
• propriétaire : généralement l'administrateur du site (qui équivaut à un accès en lecture/écriture).

Niveaux d'accès

L'élément de champ d'application représente l'entité disposant de ce niveau d'accès. Il existe quatre types d'éléments gAcl:scope possibles :

• utilisateur : valeur d'adresse e-mail, par exemple "utilisateur@gmail.com".
• group : adresse e-mail d'un groupe Google, par exemple "group@domain.com".
• domaine : nom de domaine G Suite, par exemple "domaine.com".
• default : il n'existe qu'un seul champ d'application possible de type "default", qui n'a aucune valeur (par exemple, <gAcl:scope type="default">). Ce champ d'application contrôle l'accès par défaut à un utilisateur à un site public.

Remarque : Les domaines ne peuvent pas avoir une valeur gAcl:role définie sur "owner" (propriétaire). Ils ne peuvent être que des lecteurs ou des auteurs.

Récupérer le flux de LCA

Le flux LCA peut être utilisé pour contrôler les autorisations de partage d'un site et peut être récupéré à l'aide de la méthode GetAclFeed().

L'exemple suivant extrait le flux de LCA pour le site actuellement défini sur l'objet SitesClient et affiche les entrées d'autorisation :

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)

Une fois la requête effectuée, feed est un objet gdata.sites.data.AclFeed contenant une liste de gdata.sites.data.AclEntry.

Si vous travaillez avec des entrées dans le SiteFeed, chaque SiteEntry contient un lien vers son flux LCA. Par exemple, cet extrait extrait le premier site du flux de sites de l'utilisateur et interroge son flux 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())

Partager un site

Remarque : Certaines ACL de partage ne sont possibles que si le domaine est configuré pour autoriser ces autorisations (par exemple, si le partage en dehors du domaine pour les domaines G Suite est activé, etc.).

Pour partager un site Google à l'aide de l'API, créez un gdata.sites.gdata.AclEntry avec les valeurs gdata.acl.data.AclScope et gdata.acl.data.AclRole souhaitées. Consultez la section Présentation du flux d'ACL pour connaître les valeurs possibles de AclScope et de AclRoles.

L'exemple suivant accorde des autorisations de lecture sur le site à l'utilisateur "utilisateur@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)

Partage au niveau du groupe et du domaine

Comme pour le partage d'un site avec un seul utilisateur, vous pouvez partager un site avec un groupe Google ou un domaine G Suite. Les valeurs scope nécessaires sont listées ci-dessous.

Partager avec une adresse e-mail de groupe :

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

Partage avec l'ensemble d'un domaine:

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

Le partage au niveau du domaine n'est possible que pour les domaines G Suite, et uniquement pour le domaine sur lequel le site est hébergé. Par exemple, http://sites.google.com/a/domain1.com/siteA ne peut partager l'intégralité du site qu'avec domain1.com, et non domain2.com. Les sites qui ne sont pas hébergés sur un domaine G Suite (ex. http://sites.google.com/site/siteB) ne peuvent pas inviter de domaines.

Modifier les autorisations de partage

Pour obtenir une autorisation de partage existante sur un site, commencez par récupérer le AclEntry en question, modifiez l'autorisation comme vous le souhaitez, puis appelez la méthode Update() du client pour modifier la LCA sur le serveur.

Cet exemple modifie notre acl_entry précédent de la section Partager un site, en remplaçant "utilisateur@example.com" par un auteur (collaborateur):

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)

Pour en savoir plus sur les ETags, consultez le guide de référence des API Google Data.

Supprimer les autorisations de partage

Pour supprimer une autorisation de partage, commencez par récupérer AclEntry, puis appelez la méthode Delete() du client.

client.Delete(acl_entry)

Vous pouvez également transmettre à la méthode Delete() le lien edit de l'entrée ACL et/ou forcer la suppression :

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

Pour en savoir plus sur les ETags, consultez le guide de référence des API Google Data.

Haut de page

Sujets spéciaux

Récupération d'un flux ou d'une entrée

Si vous souhaitez récupérer un flux ou une entrée que vous avez déjà récupérés, vous pouvez améliorer l'efficacité en indiquant au serveur de n'envoyer la liste ou l'entrée que si elle a changé depuis la dernière fois que vous l'avez récupérée.

Pour effectuer ce type de récupération conditionnelle, transmettez une valeur ETag à GetEntry(). Par exemple, si vous disposez d'un objet entry existant :

import gdata.client

try:
  entry = client.GetEntry(entry.GetSelfLink().href, desired_class=gdata.sites.data.ContentEntry, etag=entry.etag)
except gdata.client.NotModified, error:
  print 'You have the latest copy of this entry'
  print error

Si GetEntry() génère l'exception gdata.client.NotModified, l'ETag de l'entrée correspond à la version sur le serveur, ce qui signifie que vous disposez de la copie la plus à jour. Toutefois, si un autre client/utilisateur a apporté des modifications, la nouvelle entrée sera renvoyée dans entry et aucune exception ne sera générée.

Pour en savoir plus sur les ETags, consultez le guide de référence des API Google Data.

Haut de page