Zadbaj o dobrą organizację dzięki kolekcji
Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.
Podczas korzystania z interfejsu Google Docs API należy przestrzegać kilku zasad.
Obejmują one:
Edytowanie od końca w celu zwiększenia wydajności
Planowanie współpracy
Zapewnianie spójności stanu za pomocą pola WriteControl
Uwzględnianie kart
W sekcjach poniżej znajdziesz wyjaśnienie tych zasad.
Edytowanie od końca w celu zwiększenia wydajności
W ramach jednego wywołania metody documents.batchUpdate uporządkuj żądania w kolejności malejącej lokalizacji indeksu. Eliminuje to konieczność obliczania zmian indeksu spowodowanych wstawieniami i usunięciami.
Planowanie współpracy
Spodziewaj się zmiany stanu dokumentu. Między wywołaniami jednej metody a wywołaniami innej metody inni współpracownicy mogą aktualizować dokument, jak pokazano na tym diagramie:
Jeśli indeksy są nieprawidłowe, może to prowadzić do błędów. Gdy wielu użytkowników edytuje dokument w interfejsie, Dokumenty Google robią to w sposób przejrzysty. Jednak jako klient interfejsu API Twoja aplikacja musi zarządzać tym procesem. Nawet jeśli nie przewidujesz współpracy nad dokumentem, ważne jest, aby zaprogramować go w sposób defensywny i zapewnić spójność stanu dokumentu. Aby dowiedzieć się, jak zapewnić spójność, zapoznaj się z sekcją WriteControl.
Zapewnianie spójności stanu za pomocą WriteControl
Podczas odczytywania, a następnie aktualizowania dokumentu możesz kontrolować sposób obsługi konkurencyjnych zmian za pomocą pola WriteControl w metodzie documents.batchUpdate. WriteControl zapewnia kontrolę nad sposobem wykonywania żądań zapisu.
Oto jak go używać:
Pobierz dokument za pomocą metody documents.get i zapisz revisionId z zwróconego zasobu documents.
Utwórz prośby o aktualizację.
Dołącz opcjonalny obiekt WriteControl z jedną z 2 opcji:
Pole requiredRevisionId jest ustawione na revisionId dokumentu, do którego stosowane jest żądanie zapisu. Jeśli dokument został zmodyfikowany od czasu wysłania żądania odczytu z interfejsu API, żądanie zapisu nie zostanie przetworzone i zwróci błąd.
Pole targetRevisionId jest ustawione na revisionId dokumentu, do którego zastosowano żądanie zapisu. Jeśli dokument został zmodyfikowany od czasu wysłania żądania odczytu z interfejsu API, zmiany z żądania zapisu zostaną zastosowane do zmian wprowadzonych przez współpracownika. Wynik żądania zapisu obejmuje zarówno zmiany wprowadzone w ramach żądania zapisu, jak i zmiany wprowadzone przez współpracownika w nowej wersji dokumentu. Serwer Dokumentów jest odpowiedzialny za scalanie treści.
Jeden dokument może zawierać wiele kart, które wymagają specjalnego traktowania w żądaniach API.
Oto o czym warto pamiętać:
Ustaw parametr includeTabsContent na true w metodzie documents.get, aby pobrać zawartość ze wszystkich kart w dokumencie. Domyślnie nie są zwracane wszystkie treści kart.
W metodzie documents.batchUpdate
określ identyfikatory kart, do których ma być zastosowana każda wartość Request. Każda z nichRequest
umożliwia określenie kart, do których ma być zastosowana aktualizacja. Domyślnie, jeśli karta nie jest określona, Request w większości przypadków zostanie zastosowany do pierwszej karty w dokumencie. Szczegółowe informacje znajdziesz w dokumentacji Request.
[[["Łatwo zrozumieć","easyToUnderstand","thumb-up"],["Rozwiązało to mój problem","solvedMyProblem","thumb-up"],["Inne","otherUp","thumb-up"]],[["Brak potrzebnych mi informacji","missingTheInformationINeed","thumb-down"],["Zbyt skomplikowane / zbyt wiele czynności do wykonania","tooComplicatedTooManySteps","thumb-down"],["Nieaktualne treści","outOfDate","thumb-down"],["Problem z tłumaczeniem","translationIssue","thumb-down"],["Problem z przykładami/kodem","samplesCodeIssue","thumb-down"],["Inne","otherDown","thumb-down"]],["Ostatnia aktualizacja: 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)"]]
