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:
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:
- Récupérez le document à l'aide de la méthode
la méthode
documents.get
, puis enregistrez larevisionId
à partir de la ressourcedocuments
renvoyée. - Rédigez vos requêtes de mise à jour.
- Inclure un
WriteControl
facultatif avec l'une des deux options suivantes: <ph type="x-smartling-placeholder">- </ph>
- Le champ
requiredRevisionId
est défini sur la valeurrevisionId
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. - 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 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 permettant de fusionner le contenu.
- Le champ
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:
- Définissez le paramètre
includeTabsContent
surtrue
dansdocuments.get
pour récupérer le contenu de tous les onglets d'un document. Par défaut, tous les onglets sont renvoyés. - Indiquez l'ID du ou des onglets à appliquer chaque
Request
dans lesdocuments.batchUpdate
. ChaqueRequest
inclut un moyen de spécifier les onglets auxquels appliquer la mise à jour. Par défaut, si un l'ongletRequest
n'est pas spécifié. s'appliquera dans la plupart des cas au premier onglet du document. Consultez laRequest
s dans la documentation Google Cloud Platform.