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
  • Assurez la cohérence des états à l'aide de la WriteControl champ
  • Prendre en compte les onglets

Ces principes sont décrits dans les sections suivantes.

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

En un seul appel, documents.batchUpdate ordonnez vos requêtes ordre décroissant de l'emplacement de l'index. Il n'est donc plus nécessaire de calculer les modifications d'index dues à des insertions et des suppressions ;

Planifier la collaboration

Attendez-vous à ce que l'état du document change. Entre un appel de méthode et un autre, 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 document à l'aide de l'interface utilisateur, Google Docs s'en charge en toute transparence. Toutefois, en tant que client API, votre application doit gérer cela. Même si vous ne prévoyez pas la collaboration sur le document, il est important de programmer de manière défensive et de faire en sorte 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, puis mettez à jour un document, vous pouvez contrôler la façon dont les changements concurrents sont gérés à l'aide du WriteControl dans 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 la méthode documents.get, puis enregistrez la revisionId à partir de la ressource documents renvoyée.
  2. Rédigez vos requêtes de mise à jour.
  3. Inclure un WriteControl facultatif avec l'une des deux options suivantes:
    1. Le champ requiredRevisionId est défini sur la valeur revisionId de la document auquel la requête d'écriture est appliquée. Si le document a été modifié puisque 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 le de lecture de l'API, les modifications de requête d'écriture sont appliquées les modifications apportées par les collaborateurs. Le résultat de la requête d'écriture intègre à la fois la demande d'écriture change et le collaborateur de la révision du document. Le serveur Google Docs est responsable pour fusionner le 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.

Prendre en compte les onglets

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

Points à retenir:

  1. Définissez le paramètre includeTabsContent sur true dans documents.get pour récupérer le contenu de tous les onglets d'un document. Par défaut, tous les onglets sont renvoyés.
  2. Indiquez l'ID du ou des onglets à appliquer chaque Request dans les documents.batchUpdate . Chaque Request inclut un moyen de spécifier les onglets auxquels appliquer la mise à jour. Par défaut, si un l'onglet Request n'est pas spécifié. s'appliquera dans la plupart des cas au premier onglet du document. Consultez le Requests dans la documentation Google Cloud Platform.