Práticas recomendadas para melhores resultados

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:

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

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:

  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 o revisionId 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.
    2. O campo targetRevisionId é definido como o revisionId 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.

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