はじめに

Google Docs API を使用すると、ドキュメントを作成、変更できます。

アプリに Docs API を統合することで、ユーザー データとシステム提供データの両方から洗練されたドキュメントを作成できます。この API を使用すると、次のことができます。

  • 処理の自動化
  • ドキュメントを一括作成する
  • 請求書や契約書を作成する

API の概要

documents リソースは、Docs API の呼び出しに使用するメソッドを提供します。

API メソッド

次のメソッドで、Google ドキュメントのドキュメントを作成、読み取り、更新できます。

  • documents.create を使用してドキュメントを作成します。
  • documents.get を使用して、指定したドキュメントの内容を取得します。
  • 指定したドキュメントに対する一連の更新をアトミックに実行するには、documents.batchUpdate を使用します。

get メソッドと batchUpdate メソッドには、ターゲット ドキュメントを指定するためのパラメータとして documentId(以下を参照)が必要です。create メソッドは、作成されたドキュメントのインスタンスを返し、そこから ID を読み取ることができます。

バッチ アップデート

batchUpdate メソッドはリクエスト オブジェクトのリストを受け取り、バッチ リクエストに表示されるのと同じ順序で更新します。バッチ更新の更新はアトミックに適用されます。つまり、有効でないリクエストがある場合、更新全体が失敗し、依存する可能性のある変更は適用されません。

batchUpdate メソッドは、レスポンス オブジェクトのリストを返します。このリスト内のオブジェクトは、対応するリクエストと同じインデックス順序を占有します。

API 呼び出しをバッチ処理する方法については、バッチ リクエストのベスト プラクティスをご覧ください。リクエストとレスポンスの種類については、batchUpdate リファレンス ドキュメントをご覧ください。

ドキュメント ID

ドキュメント ID はドキュメントを参照し、次の URL から取得できます。

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

documentId は、文字、数字、いくつかの特殊文字を含む一意の文字列です。次の正規表現を使用して、Google ドキュメントの URL からドキュメント ID を抽出できます。

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

Google Drive API をご存じであれば、documentIdFile リソースの ID に対応します。

ドキュメント内のロケーション: インデックス

ドキュメントのコンテンツを更新するたびに、ある場所またはドキュメント内の範囲で更新が行われます。これらの場所と範囲は、含まれるドキュメントのセグメント内のオフセットを表すインデックスを使用して指定します。インデックスとその使用方法について詳しくは、Google ドキュメント ドキュメントの構造のコンセプト ガイドをご覧ください。

ドキュメント更新ワークフロー

既存のコンテンツを心配する必要がなく、ドキュメントの状態を変更できる共同編集者もいないため、新しいドキュメントの作成と入力は簡単です。概念的には、これは次のシーケンス図のように機能します。

新しいドキュメントを作成して入力するためのワークフロー。

既存のドキュメントの更新はより複雑。意味のある呼び出しを行ってドキュメントを更新する前に、ドキュメントの現在の状態、つまりドキュメントを構成する要素、それらの要素内のコンテンツ、すべてのアイテムがドキュメント内のどこにあるかを把握する必要があります。次のシーケンス図はこの仕組みを示しています。

ドキュメントを更新するワークフロー。

この図では、同じドキュメント内で他の共同編集者による同時更新が行われるワークフローは考慮されていません。このトピックについては、コラボレーションの計画をご覧ください。