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 읽기 요청 이후 문서가 수정된 경우 쓰기 요청 변경사항이 공동작업자 변경사항에 적용됩니다. 쓰기 요청의 결과는 쓰기 요청 변경사항과 공동작업자 변경사항을 모두 문서의 새 버전에 통합합니다. 문서 서버는 콘텐츠 병합을 담당합니다.
WriteControl
를 사용하여 일괄 요청을 구성하는 방법의 예시는 이 일괄 요청 예시를 참조하세요.