Existem vários princípios que você deve seguir ao usar a API Google Docs. São elas:
- Faça edições na ordem inversa para aumentar a eficiência
- Planejar a colaboração
- Garantir a consistência do estado usando o campo
WriteControl
As seções a seguir explicam esses princípios.
Faça edições na ordem inversa para aumentar a eficiência
Em uma única chamada para o método
documents.batchUpdate
, ordene suas solicitações na
ordem decrescente do local 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 pode mudar. Entre uma chamada de método e outra, outros colaboradores podem atualizar o documento, conforme mostrado no diagrama a seguir:
Isso poderá causar erros se os índices estiverem errados. Quando vários usuários editam um documento usando a interface, o Documentos Google cuida disso de maneira transparente. No entanto, como cliente de 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 dele 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, é possível 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.
Confira 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 como orevisionId
do documento ao qual a solicitação de gravação é aplicada. Se o documento tiver sido 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 tiver sido modificado desde a solicitação de leitura da API, as alterações na solicitação de gravação serão aplicadas às alterações do colaborador. O resultado da solicitação de gravação incorpora as alterações da solicitação e o colaborador muda em uma nova revisão do documento. O servidor do app Documentos é responsável por mesclar o conteúdo.
- O campo
Para saber como criar uma solicitação em lote usando WriteControl
, consulte este exemplo de solicitação em lote.