문서

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

API 메서드

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

  • 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에서 문서를 관리

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

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

Docs 파일 작업

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

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

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

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

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

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

Google Workspace 문서 바이트 콘텐츠를 내보내려면 Drive의 files.export 메서드를 내보낼 파일의 documentId 및 올바른 MIME 내보내기 유형과 함께 사용합니다. 자세한 내용은 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 메서드는 적용된 요청에 대한 정보가 포함된 응답 본문을 제공하는 반면, 다른 메서드는 빈 응답을 표시합니다.

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