Práticas recomendadas para melhores resultados

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:

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

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:

  1. Acesse o documento usando o método documents.get e salve o revisionId do recurso documents retornado.
  2. Escreva suas solicitações de atualização.
  3. Inclua um objeto WriteControl opcional com uma destas duas opções:
    1. O campo requiredRevisionId é definido como revisionId 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.
    2. O campo targetRevisionId é definido como o revisionId 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.

Para ver um exemplo de como criar uma solicitação em lote usando WriteControl, consulte este exemplo de solicitação em lote.