Práticas recomendadas para melhores resultados

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

  • Edite de trás para frente para aumentar a eficiência
  • Planeje a colaboração
  • Garantir a consistência do estado usando o campo WriteControl
  • Considere as guias

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

Edite de trás para frente para aumentar a eficiência

Em uma única chamada para o método documents.batchUpdate, ordene as solicitações em ordem decrescente do local do índice. Isso elimina a necessidade de calcular as mudanças de índice devido a inserções e exclusões.

Planeje a colaboração

O estado do documento vai 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 gerar erros se os índices estiverem errados. Com vários usuários editando um documento usando a interface, o Documentos Google cuida disso de forma transparente. No entanto, como um cliente de API, seu app precisa gerenciar isso. Mesmo que você não antecipe a colaboração no documento, é importante programar de forma defensiva e garantir que o estado do documento permaneça consistente. Para garantir a consistência, consulte a seção WriteControl.

Estabelecer a consistência do estado com o 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. O WriteControl fornece autoridade sobre como as solicitações de gravação são executadas.

Confira como usá-lo:

  1. Receba o documento usando o método documents.get e salve o revisionId do recurso documents retornado.
  2. Escrever solicitações de atualização.
  3. Inclua um objeto WriteControl opcional com uma das duas opções:
    1. O campo requiredRevisionId é definido como o revisionId do documento em que 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 em que a solicitação de gravação é aplicada. Se o documento foi modificado desde a solicitação de leitura da API, as mudanças na solicitação de gravação são aplicadas às mudanças do colaborador. O resultado da solicitação de gravação incorpora as alterações 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 saber como criar uma solicitação em lote usando WriteControl, consulte este exemplo de solicitação em lote.

Considere as guias

Um único documento pode conter várias guias, que exigem um processamento específico nas solicitações de API.

O que você precisa lembrar:

  1. Defina o parâmetro includeTabsContent como true no método documents.get para extrair o conteúdo de todas as guias em um documento. Por padrão, nem todo o conteúdo da guia é retornado.
  2. Especifique os IDs das guias para aplicar cada Request no método documents.batchUpdate. Cada Request inclui uma maneira de especificar as guias em que a atualização será aplicada. Por padrão, se uma guia não for especificada, o Request será aplicado, na maioria dos casos, à primeira guia do documento. Consulte a documentação do Request para saber mais detalhes.