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
  • Planejar a colaboração
  • Garantir a consistência de estado usando o campo WriteControl
  • Considerar 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 ao método documents.batchUpdate, ordene suas 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 vai 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 incorretos. Com vários usuários editando um documento usando a interface, o Google Docs cuida disso de forma transparente. No entanto, como um cliente de API, seu app precisa gerenciar isso. Mesmo que você não preveja 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 de estado com WriteControl

Ao ler e atualizar um documento, você pode controlar o comportamento de como as mudanças conflitantes 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.

Veja como usar:

  1. Receba o documento usando o método documents.get e salve o revisionId do recurso documents retornado.
  2. Crie suas 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 tiver sido modificado desde a solicitação de leitura da API, a solicitação de gravação não será processada e vai retornar um erro.
    2. O campo targetRevisionId é definido como o revisionId do documento a que a solicitação de gravação é aplicada. Se o documento tiver sido modificado desde a solicitação de leitura da API, as mudanças da solicitação de gravação serão aplicadas às mudanças do colaborador. O resultado da solicitação de gravação incorpora as mudanças da solicitação e as do colaborador em uma nova revisão do documento. O servidor do Google Docs é responsável por mesclar o conteúdo.

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

Considerar as guias

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

Lembre-se do seguinte:

  1. Defina o parâmetro includeTabsContent como true no método documents.get para recuperar o conteúdo de todas as guias de um documento. Por padrão, nem todo o conteúdo das guias é retornado.
  2. Especifique os IDs das guias em que cada Request será aplicado 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 à primeira guia do documento na maioria dos casos. Consulte a documentação do Requests para mais detalhes.