Prácticas recomendadas para obtener los mejores resultados
Organiza tus páginas con colecciones
Guarda y categoriza el contenido según tus preferencias.
Hay varios principios que debes seguir cuando uses la API de Google Docs.
Estos incluyen los siguientes:
Edita hacia atrás para mayor eficiencia
Planifica la colaboración
Cómo garantizar la coherencia del estado con el campo WriteControl
Ten en cuenta las pestañas
En las siguientes secciones, se explican estos principios.
Edita hacia atrás para mayor eficiencia
En una sola llamada al método documents.batchUpdate, ordena tus solicitudes en orden descendente de la ubicación del índice. Esto elimina la necesidad de calcular los cambios en el índice debido a las inserciones y eliminaciones.
Planifica la colaboración
Se espera que cambie el estado del documento. Entre una llamada a un método y otra, otros colaboradores pueden actualizar el documento, como se muestra en el siguiente diagrama:
Esto puede generar errores si los índices son incorrectos. Cuando varios usuarios editan un documento con la IU, Documentos de Google se encarga de esto de forma transparente. Sin embargo, como cliente de la API, tu app debe administrar esto. Incluso si no prevés que se colabore en el documento, es importante programar de forma defensiva y asegurarse de que el estado del documento siga siendo coherente. Para conocer una forma de garantizar la coherencia, consulta la sección WriteControl.
Establece la coherencia del estado con WriteControl
Cuando lees y, luego, actualizas un documento, puedes controlar el comportamiento de cómo se controlan los cambios simultáneos con el campo WriteControl en el método documents.batchUpdate. WriteControl proporciona autoridad sobre cómo se ejecutan las solicitudes de escritura.
Sigue estos pasos para usarla:
Obtén el documento con el método documents.get y guarda el revisionId del recurso documents que se devolvió.
Redacta tus solicitudes de actualización.
Incluye un objeto WriteControl opcional con una de las dos opciones siguientes:
El campo requiredRevisionId se establece en el revisionId del documento al que se aplica la solicitud de escritura. Si el documento se modificó desde la solicitud de lectura de la API, no se procesa la solicitud de escritura y se muestra un error.
El campo targetRevisionId se establece en el revisionId del documento al que se aplica la solicitud de escritura. Si el documento se modificó desde la solicitud de lectura de la API, los cambios de la solicitud de escritura se aplican en función de los cambios del colaborador. El resultado de la solicitud de escritura incorpora los cambios de la solicitud de escritura y los cambios del colaborador en una nueva revisión del documento. El servidor de Docs es responsable de combinar el contenido.
Para ver un ejemplo de cómo crear una solicitud por lotes con WriteControl, consulta este ejemplo de solicitud por lotes.
Ten en cuenta las pestañas
Un solo documento puede contener varias pestañas, que requieren un manejo específico en tus solicitudes a la API.
Recuerda lo siguiente:
Establece el parámetro includeTabsContent en true en el método documents.get para recuperar el contenido de todas las pestañas de un documento. De forma predeterminada, no se devuelve todo el contenido de las pestañas.
Especifica los IDs de las pestañas a las que se aplicará cada Request en el método documents.batchUpdate. Cada Request incluye una forma de especificar las pestañas a las que se aplicará la actualización. De forma predeterminada, si no se especifica una pestaña, Request se aplicará, en la mayoría de los casos, a la primera pestaña del documento. Consulta la documentación de Request para obtener detalles.
[[["Fácil de comprender","easyToUnderstand","thumb-up"],["Resolvió mi problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Falta la información que necesito","missingTheInformationINeed","thumb-down"],["Muy complicado o demasiados pasos","tooComplicatedTooManySteps","thumb-down"],["Desactualizado","outOfDate","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Problema con las muestras o los códigos","samplesCodeIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 2025-08-29 (UTC)"],[],[],null,["# Best practices for best results\n\nThere are several principles you should follow when using the Google Docs API.\nThese include:\n\n- Edit backwards for efficiency\n- Plan for collaboration\n- Ensure state consistency using the [`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol) field\n- Take tabs into account\n\nThe following sections explain these principles.\n\nEdit backwards for efficiency\n-----------------------------\n\nWithin a single call to the\n[`documents.batchUpdate`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate)\nmethod, order your requests in\n*descending order* of index location. This eliminates the need to compute the\nindex changes due to insertions and deletions.\n\nPlan for collaboration\n----------------------\n\nExpect the document state to change. Between one method call and another, other\ncollaborators might update the document, as shown in the following diagram:\n\nThis can lead to errors if your indexes are wrong. With multiple users editing a\ndocument using the UI, Google Docs takes care of this transparently. However,\nas an API client your app must manage this. Even if you don't anticipate\ncollaboration on the document, it's important to program defensively and make\nsure the document state remains consistent. For one way to ensure consistency,\nreview the [`WriteControl`](#establish-state-consistency) section.\n\nEstablish state consistency with WriteControl\n---------------------------------------------\n\nWhen you read and then update a document, you can control the behavior of how\ncompeting changes are handled using the\n[`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol)\nfield in the `documents.batchUpdate` method. `WriteControl` provides authority\nover how write requests are executed.\n\nHere's how you use it:\n\n1. Get the document using the [`documents.get`](/workspace/docs/api/reference/rest/v1/documents/get) method and save the [`revisionId`](/workspace/docs/api/reference/rest/v1/documents#Document.FIELDS.revision_id) from the returned `documents` resource.\n2. Compose your update requests.\n3. Include an optional [`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol) object with one of two options:\n 1. The `requiredRevisionId` field is set to the `revisionId` of the document the write request is applied to. If the document was modified since the API read request, the write request isn't processed and it returns an error.\n 2. The `targetRevisionId` field is set to the `revisionId` of the document the write request is applied to. If the document was modified since the API read request, the write request changes are applied against the collaborator changes. The result of the write request incorporates both the write request changes and the collaborator changes into a new revision of the document. The Docs server is responsible for merging the content.\n\nFor an example of how to construct a batch request using `WriteControl`, see\nthis [batch request example](/workspace/docs/api/how-tos/batch#example).\n\nTake tabs into account\n----------------------\n\nA single document can contain multiple [tabs](/workspace/docs/api/how-tos/tabs),\nwhich require specific handling in your API requests.\n\nHere's what to remember:\n\n1. Set the `includeTabsContent` parameter to `true` in the [`documents.get`](/workspace/docs/api/reference/rest/v1/documents/get) method to retrieve the content from all tabs in a document. By default, not all tab contents are returned.\n2. Specify the ID(s) of the tab(s) to apply each [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) to in the [`documents.batchUpdate`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate) method. Each [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) includes a way to specify the tabs to apply the update to. By default, if a tab is not specified, the [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) will in most cases be applied to the first tab in the document. Refer to the [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request)s documentation for specifics.\n\nRelated topics\n--------------\n\n- [Batch requests](/workspace/docs/api/how-tos/batch)\n- [Requests and responses](/workspace/docs/api/concepts/request-response)\n- [Work with tabs](/workspace/docs/api/how-tos/tabs)"]]
