Google Docs API를 사용할 때 따라야 할 몇 가지 원칙이 있습니다. 예를 들면 다음과 같습니다.
- 효율성을 위해 뒤에서 편집
- 공동작업 계획
WriteControl
필드를 사용하여 상태 일관성 보장- 탭 고려
다음 섹션에서는 이러한 원칙을 설명합니다.
효율성을 위해 뒤에서 편집
documents.batchUpdate
메서드의 단일 호출 내에서 색인 위치의 내림차순으로 요청을 정렬합니다. 이렇게 하면 삽입 및 삭제로 인한 색인 변경사항을 계산할 필요가 없습니다.
공동작업 계획
문서 상태가 변경될 것으로 예상됩니다. 다음 다이어그램과 같이 한 메서드 호출과 다른 메서드 호출 사이에서 다른 공동작업자가 문서를 업데이트할 수 있습니다.
색인이 잘못된 경우 오류가 발생할 수 있습니다. 여러 사용자가 UI로 문서를 편집하므로 Google Docs가 이를 투명하게 처리합니다. 하지만 API 클라이언트로서 앱에서 이를 관리해야 합니다. 문서에 대한 공동작업이 예상되지 않더라도 방어적으로 프로그래밍하고 문서 상태가 일관되게 유지되도록 하는 것이 중요합니다. 일관성을 보장하는 한 가지 방법은 WriteControl
섹션을 검토하세요.
WriteControl로 상태 일관성 설정
문서를 읽은 후 업데이트할 때 documents.batchUpdate
메서드의 WriteControl
필드를 사용하여 경쟁하는 변경사항이 처리되는 방식의 동작을 제어할 수 있습니다. WriteControl
는 쓰기 요청이 실행되는 방식에 대한 권한을 제공합니다.
사용 방법은 다음과 같습니다.
documents.get
메서드를 사용하여 문서를 가져오고 반환된documents
리소스에서revisionId
를 저장합니다.- 업데이트 요청을 작성합니다.
- 다음 두 옵션 중 하나와 함께 선택적
WriteControl
객체를 포함합니다.requiredRevisionId
필드는 쓰기 요청이 적용되는 문서의revisionId
로 설정됩니다. API 읽기 요청 이후 문서가 수정된 경우 쓰기 요청이 처리되지 않고 오류가 반환됩니다.targetRevisionId
필드는 쓰기 요청이 적용되는 문서의revisionId
로 설정됩니다. API 읽기 요청 이후 문서가 수정된 경우 쓰기 요청 변경사항이 공동작업자 변경사항에 적용됩니다. 쓰기 요청의 결과는 쓰기 요청 변경사항과 공동작업자 변경사항을 모두 문서의 새 버전에 통합합니다. Docs 서버가 콘텐츠를 병합합니다.
WriteControl
를 사용하여 일괄 요청을 구성하는 방법의 예시는 이 일괄 요청 예시를 참조하세요.
탭 고려
단일 문서에 여러 탭이 포함될 수 있으며, 이 경우 API 요청에서 특정 처리가 필요합니다.
다음 사항을 기억하세요.
documents.get
메서드에서includeTabsContent
매개변수를true
로 설정하여 문서의 모든 탭에서 콘텐츠를 가져옵니다. 기본적으로 일부 탭 콘텐츠만 반환됩니다.documents.batchUpdate
메서드에서 각Request
을 적용할 탭의 ID를 지정합니다. 각Request
에는 업데이트를 적용할 탭을 지정하는 방법이 포함되어 있습니다. 기본적으로 탭을 지정하지 않으면 대부분의 경우Request
가 문서의 첫 번째 탭에 적용됩니다. 자세한 내용은Request
문서를 참고하세요.