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:
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:
- Récupérez le document à l'aide de la méthode
documents.get
, puis enregistrez lerevisionId
à partir de la ressourcedocuments
renvoyée. - Rédigez vos requêtes de mise à jour.
- Incluez un objet
WriteControl
facultatif avec l'une des deux options suivantes :- 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. - Le champ
targetRevisionId
est défini sur la valeurrevisionId
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.
- Le champ
Pour découvrir comment créer une requête par lot à l'aide de WriteControl
, consultez cet exemple de requête par lot.