문서

이 가이드에서는 Google Docs API를 구성하는 기본 메서드, 문서에 액세스하는 방법, 문서를 만들 때의 워크플로와 같은 개념을 소개합니다.

API 메서드

documents 리소스는 Docs API를 호출하는 데 사용하는 메서드를 제공합니다. 다음 메서드를 사용하면 Docs 문서를 만들고, 읽고, 업데이트할 수 있습니다.

  • documents.create 메서드를 사용하여 문서를 만듭니다.
  • documents.get 메서드를 사용하여 지정된 문서의 콘텐츠를 검색합니다.
  • documents.batchUpdate 메서드를 사용하여 지정된 문서에서 일련의 업데이트를 원자적으로 실행합니다.

documents.get 및 documents.batchUpdate 메서드에는 타겟 문서를 지정하는 매개변수로 documentId가 필요합니다. documents.create 메서드는 생성된 문서의 인스턴스를 반환하며, 이 인스턴스에서 documentId를 읽을 수 있습니다. Docs API 요청 및 응답 메서드에 관한 자세한 내용은 요청 및 응답을 참고하세요.

문서 ID

documentId는 문서의 고유 식별자이며 문서의 URL에서 파생될 수 있습니다. 문자, 숫자, 특수문자가 포함된 특정 문자열입니다. 문서 이름이 변경되더라도 문서 ID는 변경되지 않습니다.

https://docs.google.com/document/d/DOCUMENT_ID/edit

다음 정규식을 사용하여 Google Docs URL에서 documentId를 추출할 수 있습니다.

/document/d/([a-zA-Z0-9-_]+)

Google Drive API에 대해 잘 알고 있다면 documentId는 files 리소스의 id에 해당합니다.

Google Drive에서 문서를 관리

Docs 파일은 Google의 클라우드 기반 스토리지 서비스인 Google Drive에 저장됩니다. Docs API에는 자체 독립형 메서드가 있지만 사용자의 Docs 파일과 상호작용하려면 Google Drive API 메서드도 사용해야 하는 경우가 많습니다. 예를 들어 Docs 파일을 복사하려면 Drive API의 files.copy 메서드를 사용합니다. 자세한 내용은 기존 문서 복사를 참고하세요.

기본적으로 Docs API를 사용하면 새 문서가 Drive의 사용자 루트 폴더에 저장됩니다. Drive 폴더에 파일을 저장하는 옵션이 있습니다. 자세한 내용은 Google Drive 폴더 작업을 참고하세요.

Docs 파일로 작업하기

사용자의 내 드라이브에서 문서를 검색하려면 먼저 Drive의 files.list 메서드를 사용하여 파일의 ID를 가져와야 하는 경우가 많습니다. 매개변수 없이 이 메서드를 호출하면 사용자의 ID를 비롯한 모든 파일 및 폴더 목록이 반환됩니다.

문서의 MIME 유형은 데이터 유형과 형식을 나타냅니다. Docs의 MIME 유형 형식은 application/vnd.google-apps.document입니다. MIME 유형 목록은 Google Workspace 및 Google Drive에서 지원되는 MIME 유형을 참고하세요.

내 드라이브 내에서 Docs 파일만 MIME 유형으로 검색하려면 다음 쿼리 문자열 필터를 추가하세요.

q: mimeType = 'application/vnd.google-apps.document'

검색 문자열 필터에 대한 자세한 내용은 파일 및 폴더 검색을 참고하세요.

documentId를 알면 documents.get 메서드를 사용하여 지정된 문서의 전체 인스턴스를 검색합니다. 자세한 내용은 요청 및 응답을 참고하세요.

Google Workspace 문서 바이트 콘텐츠를 내보내려면 내보낼 파일의 documentId 및 올바른 내보내기 MIME 유형과 함께 Drive의 files.export 메서드를 사용합니다. 자세한 내용은 Google Workspace 문서 콘텐츠 내보내기를 참고하세요.

Get 및 List 메서드 비교

다음 표에서는 Drive 및 Docs 메서드의 차이점과 각 메서드와 함께 반환되는 데이터를 설명합니다.

연산자 설명 사용
drive.files.get ID별로 파일의 메타데이터를 가져옵니다. files 리소스의 인스턴스를 반환합니다. 특정 파일의 메타데이터를 가져옵니다.
drive.files.list 사용자의 파일을 가져옵니다. 파일 목록을 반환합니다. 수정해야 할 파일을 잘 모르는 경우 사용자 파일 목록을 가져옵니다.
docs.documents.get 모든 서식 및 텍스트를 포함하여 지정된 문서의 최신 버전을 가져옵니다. documents 리소스의 인스턴스를 반환합니다. 특정 문서 ID의 문서를 가져옵니다.

문서 생성 워크플로

새 문서를 만들고 채우는 것은 간단합니다. 우려할 기존 콘텐츠가 없고 문서 상태를 변경할 수 있는 공동작업자가 없기 때문입니다. 개념적으로 다음 시퀀스 다이어그램과 같이 작동합니다.

새 문서를 만들고 채우는 워크플로입니다.
그림 1. 새 문서를 만들고 채우는 워크플로

그림 1에서 documents 리소스와 상호작용하는 사용자는 다음과 같은 정보 흐름을 갖습니다.

  1. 앱이 웹 서버에서 documents.create 메서드를 호출합니다.
  2. 웹 서버는 생성된 문서의 인스턴스를 documents 리소스로 포함하는 HTTP 응답을 전송합니다.
  3. 원하는 경우 앱은 documents.batchUpdate 메서드를 호출하여 일련의 수정 요청을 원자적으로 실행하여 문서에 데이터를 채웁니다.
  4. 웹 서버가 HTTP 응답을 보냅니다. 일부 documents.batchUpdate 메서드는 적용된 요청에 관한 정보가 포함된 응답 본문을 제공하는 반면, 다른 메서드는 빈 응답을 표시합니다.

문서 업데이트 워크플로

기존 문서를 업데이트하는 것은 더 복잡합니다. 문서를 업데이트하기 위해 의미 있는 호출을 실행하려면 문서의 현재 상태(문서를 구성하는 요소, 요소의 콘텐츠, 문서 내 요소의 순서)를 알아야 합니다. 다음 시퀀스 다이어그램은 작동 방식을 보여줍니다.

문서를 업데이트하는 워크플로입니다.
그림 2. 문서를 업데이트하는 워크플로입니다.

그림 2에서 documents 리소스와 상호작용하는 사용자는 다음과 같은 정보 흐름을 갖습니다.

  1. 앱이 찾을 파일의 documentId를 사용하여 웹 서버에서 documents.get 메서드를 호출합니다.
  2. 웹 서버는 지정된 문서의 인스턴스를 documents 리소스로 포함하는 HTTP 응답을 전송합니다. 반환된 JSON에는 문서 콘텐츠, 서식, 기타 기능이 포함됩니다.
  3. 앱은 JSON을 파싱하여 사용자가 업데이트할 콘텐츠 또는 형식을 결정할 수 있도록 합니다.
  4. 앱은 documents.batchUpdate 메서드를 호출하여 수정 요청 집합을 원자적으로 실행하여 문서를 업데이트합니다.
  5. 웹 서버가 HTTP 응답을 보냅니다. 일부 documents.batchUpdate 메서드는 적용된 요청에 관한 정보가 포함된 응답 본문을 제공하는 반면, 다른 메서드는 빈 응답을 표시합니다.

이 다이어그램은 다른 공동작업자가 동일한 문서에서 동시에 업데이트하는 워크플로는 고려하지 않습니다. 자세한 내용은 권장사항 섹션 공동작업 계획을 참고하세요.