このガイドでは、Google ドキュメント API を構成する主なメソッド、ドキュメントへのアクセス方法、ドキュメント作成時のワークフローなどのコンセプトを紹介します。
API メソッド
documents
リソースは、Docs API を呼び出すためのメソッドを提供します。次のメソッドを使用すると、Google ドキュメントのドキュメントを作成、読み取り、更新できます。
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 のクラウドベースのストレージ サービスである Google ドライブに保存されます。ドキュメント API には独自のスタンドアロン メソッドがありますが、ユーザーのドキュメント ファイルを操作するには、多くの場合、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 ドキュメントのバイト コンテンツをエクスポートするには、エクスポートするファイルの documentId
と正しいエクスポート MIME タイプを指定して、ドライブの files.export
メソッドを使用します。詳細については、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
メソッドを呼び出します。 - ウェブサーバーは、指定されたドキュメントのインスタンスを含む HTTP レスポンスを
documents
リソースとして送信します。返される JSON には、ドキュメントのコンテンツ、フォーマット、その他の機能が含まれます。 - アプリは JSON を解析し、ユーザーは更新するコンテンツや形式を判断できます。
- アプリは
documents.batchUpdate
メソッドを呼び出して、ドキュメントを更新するための一連の編集リクエストをアトミックに実行します。 - ウェブサーバーが HTTP レスポンスを送信します。
documents.batchUpdate
メソッドには、適用されたリクエストに関する情報をレスポンスの本文として提供するメソッドもあれば、空のレスポンスを表示するメソッドもあります。
この図では、他の共同編集者による同じドキュメントで同時に更新が行われるワークフローは考慮されていません。詳しくは、コラボレーションを計画するのベスト プラクティスのセクションをご覧ください。