Práticas recomendadas para melhores resultados

Existem vários princípios que você precisa seguir ao usar a API Google Docs. São eles:

  • Faça edições retroativas para aumentar a eficiência
  • Planejar a colaboração
  • Garantir a consistência do estado com WriteControl

As seções a seguir explicam esses princípios.

Faça edições retroativas para aumentar a eficiência

Em uma única chamada para o método BatchUpdate, organize suas solicitações em ordem decrescente de localização do índice. Isso elimina a necessidade de calcular as mudanças no í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, como mostrado no diagrama a seguir:

Como um documento pode mudar entre chamadas de método.

Isso pode causar erros se os índices estiverem errados. Com vários usuários editando um documento na IU, os Documentos Google cuidam disso de maneira transparente, mas, como cliente de API, seu app precisa gerenciar isso. Mesmo que você não antecipe a colaboração no documento, é importante programar defensivamente e garantir que o estado do documento permaneça consistente. Para garantir a consistência, consulte a seção WriteControl abaixo.

Garantir a consistência do estado com o WriteControl

Ao ler e atualizar um documento, use o campo WriteControl no método BatchUpdate para garantir que ele não foi atualizado. Isso permite que você edite o documento somente se a versão não tiver sido alterada. Veja como usá-lo:

  1. Acesse o documento e salve a string revisionId incluída nele.
  2. Escreva suas solicitações de atualização.
  3. Inclua um objeto WriteControl com o requiredRevisionId definido como a string que você salvou.
  4. Quando você chama BatchUpdate, se a revisão do documento foi alterada, ela retorna um erro e não executa uma atualização.