Práticas recomendadas para melhores resultados

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

  • Faça edições na ordem inversa para aumentar a eficiência
  • Planejar a colaboração
  • Garantir a consistência do estado usando o WriteControl campo
  • Leve as guias em consideração

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 ao método documents.batchUpdate método, ordene suas solicitações ordem decrescente do local do índice. Isso elimina a necessidade de calcular o mudanças do í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, os 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. Com vários usuários editando um documento usando a interface, o Documentos Google cuida disso de maneira transparente. No entanto, como cliente de API, ele precisa fazer isso. Mesmo que você não antecipe colaboração no documento, é importante programar defensivamente e garantir garantir que o estado do documento permaneça consistente. Uma maneira de 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 mudanças concorrentes são tratadas usando o 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 documents.get e salve as revisionId do recurso documents retornado.
  2. Escreva suas solicitações de atualização.
  3. Incluir um WriteControl opcional com uma destas duas opções:
    1. O campo requiredRevisionId é definido como o revisionId do o documento ao qual a solicitação de gravação é aplicada. Se o documento tiver sido modificado desde que a solicitação de leitura da API, a solicitação de gravação não seja processada retorna um erro.
    2. O campo targetRevisionId está definido como revisionId do documento. ao qual a solicitação de gravação é aplicada. Se o documento tiver sido modificado desde a de leitura da API, as alterações da solicitação de gravação serão aplicadas ao alterações feitas pelos colaboradores. O resultado da solicitação de gravação incorpora a solicitação de gravação é alterada, e o colaborador muda para um novo revisão do documento. O servidor do Documentos é responsável para mesclar o conteúdo.

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

Leve as guias em consideração

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

Lembre-se:

  1. Defina o parâmetro includeTabsContent como true na documents.get para recuperar o conteúdo de todas as guias em um documento. Por padrão, nem todas as guias conteúdos sejam retornados.
  2. Especifique os IDs das guias a serem aplicadas para cada Request. na documents.batchUpdate . Cada Request inclui uma maneira de especificar as guias nas quais a atualização será aplicada. Por padrão, se um guia não for especificada, a Request na maioria dos casos será aplicada à primeira guia no documento. Consulte a Requests a documentação para mais detalhes.