Bonnes pratiques pour obtenir de meilleurs résultats

Il existe plusieurs principes que vous devez suivre lorsque vous utilisez l'API Google Docs. En voici quelques-unes :

  • Effectuez des modifications à l'envers pour plus d'efficacité
  • Planifier la collaboration
  • Assurez la cohérence des états à l'aide du champ WriteControl.

Ces principes sont décrits dans les sections suivantes.

Effectuez des modifications à l'envers pour plus d'efficacité

Dans un même appel à la méthode documents.batchUpdate, triez vos requêtes par ordre décroissant de l'emplacement de l'index. Ainsi, il n'est pas 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 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 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, puis mettez à jour un document, vous pouvez contrôler le comportement de gestion des modifications concurrentes à l'aide du champ WriteControl de la méthode documents.batchUpdate. WriteControl détermine la façon dont les requêtes d'écriture sont exécutées.

Voici comment l'utiliser:

  1. Récupérez le document à l'aide de la méthode documents.get, puis enregistrez l'élément 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 l'élément 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 l'élément 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 le collaborateur. Le résultat de la requête d'écriture intègre à la fois les modifications de la requête d'écriture et celles apportées par les collaborateurs dans une nouvelle révision 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.