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