ドキュメント

このガイドでは、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 ドキュメントの URL から documentId を抽出できます。

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

Google Drive API に精通している方は、documentId が files リソースの id に対応していることが理解できるでしょう。

Google ドライブのドキュメントの管理

ドキュメント ファイルは、クラウド ベースのストレージ サービスである Google ドライブに保存されます。Docs API には独自のスタンドアロン メソッドがありますが、ユーザーの Docs ファイルにアクセスするには、Google Drive API メソッドも使用する必要があります。たとえば、ドキュメント ファイルをコピーするには、Drive API の files.copy メソッドを使用します。詳細については、既存のドキュメントをコピーするをご覧ください。

デフォルトでは、Docs API を使用すると、新しいドキュメントはユーザーのドライブのルートフォルダに保存されます。ドライブのフォルダにファイルを保存する方法はいくつかあります。詳細については、Google ドライブ フォルダを操作するをご覧ください。

ドキュメント ファイルで作業する

ユーザーのマイドライブからドキュメントを取得するには、多くの場合、まずドライブの files.list メソッドを使用してファイルの ID を取得する必要があります。パラメータなしでメソッドを呼び出すと、ユーザーの ID を含むすべてのファイルとフォルダのリストが返されます。

ドキュメントの MIME タイプは、データの種類と形式を示します。ドキュメントの MIME タイプ形式は application/vnd.google-apps.document です。MIME タイプの一覧については、Google Workspace と Google ドライブでサポートされている MIME タイプをご覧ください。

マイドライブ内のドキュメント ファイルだけを MIME タイプで検索するには、次のクエリ文字列フィルタを追加します。

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

クエリ文字列フィルタの詳細については、ファイルとフォルダを検索するをご覧ください。

documentId がわかったら、documents.get メソッドを使用して、指定したドキュメントの完全なインスタンスを取得します。詳細については、リクエストとレスポンスをご覧ください。

Google Workspace ドキュメントのバイト コンテンツをエクスポートするには、ドライブの files.export メソッドを使用して、エクスポートするファイルの documentId と正しいエクスポート MIME タイプを指定します。詳細については、Google Workspace ドキュメントのコンテンツをエクスポートするをご覧ください。

Get メソッドと List メソッドを比較する

次の表に、ドライブとドキュメントのメソッドの違いと、それぞれのメソッドで返されるデータを示します。

演算子 説明 用途
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 メソッドは、適用されたリクエストに関する情報を含むレスポンス本文を提供しますが、他のメソッドは空のレスポンスを表示します。

この図では、他の共同編集者による同じドキュメントの同時更新が考慮されていません。詳細については、ベスト プラクティスのコラボレーションを計画するをご覧ください。