Bonnes pratiques pour obtenir de meilleurs résultats

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

  • Modifiez vos documents en arrière pour plus d'efficacité
  • Planifier la collaboration
  • Assurer la cohérence des états à l'aide du champ WriteControl

Ces principes sont décrits dans les sections suivantes.

Modifiez vos documents en arrière pour plus d'efficacité

Dans un seul appel à la méthode documents.batchUpdate, triez vos requêtes par ordre décroissant d'emplacement d'index. Il n'est donc plus nécessaire 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 un appel de méthode et un autre, d'autres collaborateurs peuvent mettre à jour le document, comme illustré dans le schéma suivant:

Façon dont un document peut changer entre les appels de méthode

Cela peut entraîner des erreurs si vos index sont erronés. Lorsque plusieurs utilisateurs modifient un document à l'aide de l'interface utilisateur, Google Docs s'en charge de manière transparente. Cependant, en tant que client API, votre application doit gérer cela. Même si vous n'anticipez pas la 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 plus de cohérence, consultez la section WriteControl.

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

Lorsque vous lisez, puis mettez à jour un document, vous pouvez contrôler le comportement de traitement des modifications en concurrence à l'aide du champ WriteControl de la méthode documents.batchUpdate. WriteControl fournit une autorité sur l'exécution des requêtes d'écriture.

Voici comment l'utiliser:

  1. Récupérez le document à l'aide de la méthode documents.get, puis enregistrez le revisionId à partir de la ressource documents renvoyée.
  2. Rédigez vos requêtes de mise à jour.
  3. Incluez un objet WriteControl facultatif avec l'une des deux options suivantes :
    1. Le champ requiredRevisionId est défini sur l'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 renvoie une erreur.
    2. Le champ targetRevisionId est défini sur la valeur 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, les modifications de la requête d'écriture sont appliquées aux modifications apportées par les collaborateurs. Le résultat de la requête d'écriture intègre à la fois les modifications de la requête d'écriture et les modifications apportées par les collaborateurs dans une nouvelle révision du document. Le serveur Docs est responsable de la fusion du contenu.

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