このガイドでは、Google Docs API を構成する主なリクエスト メソッドとレスポンス メソッド、およびドキュメントを一括で更新する方法について説明します。
Google Docs API は、HTTP リクエストを使用するか、言語固有のクライアント ライブラリでメソッド呼び出しを使用することで呼び出すことができます。これらはほぼ同等です。
Google Docs API は HTTP レスポンスを返します。通常、これにはリクエスト呼び出しの結果が含まれます。クライアント ライブラリを使用してリクエストを行う場合、レスポンスは言語固有の方法で返されます。
リクエストのメソッド
Docs API は次のメソッドをサポートしています。
documents.create: 空の Google ドキュメントを作成します。documents.get: 指定されたドキュメントの完全なインスタンスを返します。返された JSON を解析して、ドキュメントのコンテンツ、書式設定、その他の機能を抽出できます。documents.batchUpdate: ドキュメントにアトミックに適用する編集リクエストのリストを送信し、結果のリストを返します。
documents.get メソッドと documents.batchUpdate メソッドでは、ターゲット ドキュメントを指定するパラメータとして documentId が必要です。documents.create メソッドは、作成されたドキュメントのインスタンスを返します。このインスタンスから documentId を読み取ることができます。documentId の詳細については、ドキュメント ID をご覧ください。
documents.get メソッドを使用して公開済みドキュメントを取得することはできません。公開されたドキュメントは、異なる URL 形式を使用します。URL の新しい documentId を documents.get メソッドで使用しようとすると、404 HTTP ステータス コード レスポンスが返されます。公開された URL から元の documentId を取得する方法はありません。この問題を回避するには、Drive API を使用して、公開されたドキュメントをコピーして共有ドキュメントを作成し、代わりにこのファイルにアクセスします。詳しくは、Google ドキュメント、スプレッドシート、スライド、フォームを公開するをご覧ください。
バッチ アップデート
documents.batchUpdate メソッドは、実行する単一のリクエストを指定する request オブジェクトのリストを受け取ります。たとえば、段落の書式を設定してから、インライン画像を追加します。各リクエストは適用前に検証され、バッチ リクエストに表示される順序で処理されます。
バッチ更新内のすべてのリクエストはアトミックに適用されます。つまり、リクエストが無効な場合、更新全体が失敗し、（依存関係がある可能性のある）変更は適用されません。
一部の documents.batchUpdate メソッドは、適用されたリクエストに関する情報を含むレスポンスを提供します。これらのメソッドは、response オブジェクトのリストを含むレスポンス本文を返します。他のリクエストでは、情報を返す必要はなく、空の返信が表示されます。レスポンス リスト内のオブジェクトは、対応するリクエストと同じインデックス順序になります。
一括リクエストを行う一般的なパターンは次のようになります。
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
Docs API 呼び出しをバッチ処理する方法の詳細については、バッチ リクエストのベスト プラクティスをご覧ください。リクエストとレスポンスのタイプについては、documents.batchUpdate リファレンス ドキュメントをご覧ください。
バッチ更新オペレーション
バッチ更新リクエストにはさまざまな種類があります。リクエスト タイプをカテゴリ別に分類したものは次のとおりです。