このガイドでは、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 タイプは、データの種類と形式を示します。Docs の 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 では、ユーザーが documents リソースを操作すると、次の情報フローが実行されます。
- アプリがウェブサーバーで
documents.createメソッドを呼び出します。 - ウェブサーバーは、作成されたドキュメントのインスタンスを
documentsリソースとして含む HTTP レスポンスを送信します。 - 必要に応じて、アプリは
documents.batchUpdateメソッドを呼び出して、一連の編集リクエストをアトミックに実行し、ドキュメントにデータを入力します。 - ウェブサーバーが HTTP レスポンスを送信します。一部の
documents.batchUpdateメソッドは、適用されたリクエストに関する情報を含むレスポンス本文を提供しますが、他のメソッドは空のレスポンスを表示します。
ドキュメント更新ワークフロー
既存のドキュメントの更新は複雑です。ドキュメントを更新する意味のある呼び出しを行うには、ドキュメントの現在の状態（構成要素、要素内のコンテンツ、ドキュメント内の要素の順序）を把握する必要があります。次のシーケンス図は、この仕組みを示しています。
図 2 では、documents リソースを操作するユーザーに次の情報フローが適用されます。
- アプリが、検索するファイルの
documentIdを指定して、ウェブサーバーでdocuments.getメソッドを呼び出します。 - ウェブサーバーは、指定されたドキュメントのインスタンスを
documentsリソースとして含む HTTP レスポンスを送信します。返される JSON には、ドキュメントのコンテンツ、フォーマット、その他の機能が含まれます。 - アプリは JSON を解析し、ユーザーが更新するコンテンツや形式を決定できるようにします。
- アプリは
documents.batchUpdateメソッドを呼び出して、一連の編集リクエストをアトミックに実行し、ドキュメントを更新します。 - ウェブサーバーが HTTP レスポンスを送信します。一部の
documents.batchUpdateメソッドは、適用されたリクエストに関する情報を含むレスポンス本文を提供しますが、他のメソッドは空のレスポンスを表示します。
この図では、他の共同編集者による同じドキュメントの同時更新が考慮されていません。詳細については、ベスト プラクティスのコラボレーションを計画するをご覧ください。