Bonnes pratiques pour obtenir de meilleurs résultats

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

  • Monter à l'envers pour plus d'efficacité
  • Planifier la collaboration
  • Assurer la cohérence de l'état à l'aide du champ WriteControl
  • Tenir compte des onglets

Les sections suivantes expliquent ces principes.

Monter à l'envers pour plus d'efficacité

Dans un seul appel à la méthode documents.batchUpdate, ordonnez vos requêtes par ordre décroissant de l'emplacement de l'index. Vous n'avez donc plus besoin de calculer les modifications d'index dues aux insertions et aux suppressions.

Planifier la collaboration

Attendez-vous à ce que l'état du document change. Entre deux appels de méthode, d'autres collaborateurs peuvent modifier le document, comme le montre le schéma 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 charge 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 collaborer 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 garantir la cohérence, consultez la section WriteControl.

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

Lorsque vous lisez un document, puis le mettez à jour, vous pouvez contrôler la façon dont les modifications concurrentes sont gérées à l'aide du champ WriteControl dans la méthode documents.batchUpdate. WriteControl fournit l'autorité sur la façon dont les requêtes d'écriture sont exécutées.

Voici comment l'utiliser :

  1. Obtenez 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 est appliquée. 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 une erreur est renvoyée.
    2. Le champ targetRevisionId est défini sur le revisionId du document auquel la requête d'écriture est appliquée. Si le document a été modifié depuis la demande de lecture de l'API, les modifications de la demande d'écriture sont appliquées aux modifications apportées par les collaborateurs. Le résultat de la requête d'écriture intègre les modifications de la requête d'écriture et celles du collaborateur dans une nouvelle révision du document. Le serveur Docs est responsable de la fusion du contenu.

Pour obtenir un exemple de création d'une requête par lot à l'aide de WriteControl, consultez cet exemple de requête par lot.

Tenir compte des onglets

Un même document peut contenir plusieurs onglets, qui nécessitent un traitement spécifique dans vos requêtes API.

Voici quelques points à 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, le contenu de tous les onglets n'est pas renvoyé.
  2. Spécifiez le 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 appliqué dans la plupart des cas au premier onglet du document. Pour en savoir plus, consultez la documentation de Request.