Existem vários princípios que precisam ser seguidos ao usar a API Google Docs. Por exemplo:
- Faça edições para melhorar a eficiência
- Planejar a colaboração
- Garanta a consistência do estado usando o
campo
WriteControl
.
As seções a seguir explicam esses princípios.
Faça edições para melhorar a eficiência
Em uma única chamada para o método
documents.batchUpdate
, ordene as solicitações em
ordem decrescente de localização do índice. Isso elimina a necessidade de calcular as
mudanças de índice devido a inserções e exclusões.
Planejar a colaboração
O estado do documento deve mudar. Entre uma chamada de método e outra, outros colaboradores podem atualizar o documento, conforme mostrado no diagrama a seguir:
Isso pode causar erros se os índices estiverem errados. Como vários usuários editam um documento usando a interface, o Documentos Google cuida disso de maneira transparente. No entanto,
como cliente da API, seu app precisa gerenciar isso. Mesmo que você não preveja
a colaboração no documento, é importante programar de maneira defensiva e garantir
que o estado do documento permaneça consistente. Para garantir a consistência,
consulte a seção WriteControl
.
Estabelecer consistência de estado com WriteControl
Ao ler e atualizar um documento, você pode controlar o comportamento de como
as mudanças concorrentes são processadas usando o campo
WriteControl
no método documents.batchUpdate
. WriteControl
fornece autoridade
sobre como as solicitações de gravação são executadas.
Veja como usar:
- Acesse o documento usando o método
documents.get
e salve orevisionId
do recursodocuments
retornado. - Escreva suas solicitações de atualização.
- Inclua um objeto
WriteControl
opcional com uma destas duas opções:- O campo
requiredRevisionId
é definido comorevisionId
do documento ao qual a solicitação de gravação é aplicada. Se o documento foi modificado desde a solicitação de leitura da API, a solicitação de gravação não será processada e retornará um erro. - O campo
targetRevisionId
é definido como orevisionId
do documento ao qual a solicitação de gravação é aplicada. Se o documento foi modificado desde a solicitação de leitura da API, as alterações da solicitação de gravação serão aplicadas às alterações do colaborador. O resultado da solicitação de gravação incorpora as mudanças da solicitação de gravação e do colaborador em uma nova revisão do documento. O servidor do Documentos é responsável por mesclar o conteúdo.
- O campo
Para ver um exemplo de como criar uma solicitação em lote usando WriteControl
, consulte este exemplo de solicitação em lote.