このガイドでは、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.batchUpdate メソッドは、実行するリクエストを 1 つずつ指定する request オブジェクトのリストを受け取ります。たとえば、段落をフォーマットしてから、インライン画像を追加します。各リクエストは適用前に検証され、バッチ リクエストに表示される順序に従って処理されます。
バッチ アップデートのすべてのリクエストはアトミックに適用されます。つまり、いずれかのリクエストが有効でない場合、更新全体が失敗し、（依存している可能性のある）変更は適用されません。
一部の documents.batchUpdate メソッドは、適用されたリクエストに関する情報を含むレスポンスを返します。これらのメソッドは、response オブジェクトのリストを含むレスポンス本文を返します。他のリクエストでは、情報を返す必要はなく、空のリプライを返すことができます。レスポンス リスト内のオブジェクトは、対応するリクエストと同じインデックス順序で配置されます。
一括リクエストを実行する一般的なパターンは次のとおりです。
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
Docs API 呼び出しをバッチ処理する方法の詳細については、バッチ リクエストのベスト プラクティスをご覧ください。また、リクエストとレスポンスのタイプについては、documents.batchUpdate リファレンス ドキュメントをご覧ください。
バッチ アップデート オペレーション
バッチ アップデート リクエストにはさまざまな種類があります。以下は、リクエスト タイプの分類です。