Bonnes pratiques pour obtenir de meilleurs résultats

Vous devez respecter plusieurs principes lorsque vous utilisez l'API Google Docs. Exemples :

  • Monter à rebours pour plus d'efficacité
  • Planifier la collaboration
  • Assurer la cohérence de l'état à l'aide du champ WriteControl
  • Prendre en compte les onglets

Les sections suivantes expliquent ces principes.

Monter à rebours pour plus d'efficacité

Dans un seul appel à la méthode documents.batchUpdate, triez vos requêtes par ordre décroissant de l'emplacement de l'index. Cela évite de calculer les modifications d'index dues aux insertions et aux suppressions.

Planifier la collaboration

Attendez que l'état du document change. Entre un appel de méthode et un autre, d'autres collaborateurs peuvent mettre à jour le document, comme illustré dans le diagramme suivant:

Comment un document peut changer entre les appels de méthode.

Cela peut entraîner des erreurs si vos index sont incorrects. Lorsque plusieurs utilisateurs modifient un document à l'aide de l'interface utilisateur, Google Docs s'en occupe de manière transparente. Toutefois, en tant que client API, votre application doit gérer cela. Même si vous ne prévoyez pas de collaboration sur le document, il est important de programmer de manière défensive et de vous assurer que l'état du document reste cohérent. Pour assurer la cohérence, consultez la section WriteControl.

Établir la cohérence de l'état avec WriteControl

Lorsque vous lisez et mettez à jour un document, vous pouvez contrôler le comportement de la gestion des modifications concurrentes à l'aide du champ WriteControl dans la méthode documents.batchUpdate. WriteControl contrôle la manière dont les requêtes d'écriture sont exécutées.

Pour l'utiliser, procédez comme suit:

  1. Récupérez le document à l'aide de la méthode documents.get et enregistrez le revisionId à partir de la ressource documents renvoyée.
  2. Rédigez vos demandes de mise à jour.
  3. Incluez un objet WriteControl facultatif avec l'une des deux options suivantes :
    1. Le champ requiredRevisionId est défini sur le revisionId du document auquel la requête d'écriture s'applique. Si le document a été modifié depuis la requête de lecture de l'API, la requête d'écriture n'est pas traitée et renvoie une erreur.
    2. Le champ targetRevisionId est défini sur le revisionId du document auquel la requête d'écriture s'applique. Si le document a été modifié depuis la requête de lecture de l'API, les modifications de la requête d'écriture sont appliquées aux modifications du collaborateur. Le résultat de la requête d'écriture intègre à la fois les modifications de la requête d'écriture et les modifications du collaborateur dans une nouvelle version du document. Le serveur Docs est responsable de la fusion du contenu.

Pour savoir comment créer une requête par lot à l'aide de WriteControl, consultez cet exemple de requête par lot.

Prendre en compte les onglets

Un seul document peut contenir plusieurs onglets, qui nécessitent une gestion spécifique dans vos requêtes API.

Voici ce qu'il faut retenir:

  1. Définissez le paramètre includeTabsContent sur true dans la méthode documents.get pour récupérer le contenu de tous les onglets d'un document. Par défaut, tous les contenus des onglets ne sont pas renvoyés.
  2. Spécifiez l'ID ou les ID des onglets auxquels appliquer chaque Request dans la méthode documents.batchUpdate. Chaque Request inclut un moyen de spécifier les onglets auxquels appliquer la mise à jour. Par défaut, si aucun onglet n'est spécifié, Request est généralement appliqué au premier onglet du document. Pour en savoir plus, consultez la documentation de Request.