Docs APIのコメントと提案モードがGA — 自動化前の確認点

契約書のひな形や議事録を、Apps ScriptやAIで自動チェックしたい。ところがAPIで本文を直接書き換えると、どこを誰が変えたのかが文書上に残らず、確認する人は差分を探すところから始めることになります。これまでのDocs APIには、人がエディタで使う「提案モード」に相当する書き込み方がありませんでした。

2026年9月30日、GoogleはDocs・Sheets・Slides APIでコメントを操作する機能を一般提供（GA）にしました。Docs APIでは、書き込みを「提案」として残すこともできます。7〜8月に先行提供されていた機能が、誰でも使える段階になった形です。公式のリリースノートとガイドで確かめた範囲と、業務の自動化に組み込む前に決めておく点をまとめます。

9月30日に一般提供になったもの

Google Workspace Updatesの告知とDocs・Sheets・Slidesのリリースノートによると、9月30日に一般提供になったのは次の操作です。

提案として書き込めるのはDocs APIだけです。Sheets・Slidesでできるのはコメントの操作に限られます。

告知に書かれた提供条件は次のとおりです。

• 対象: すべてのGoogle Workspaceの契約と、個人のGoogleアカウント
• 展開: 即時リリース・計画的リリースのどちらのドメインも、9月30日から段階的に展開し、使えるようになるまで最大15日かかる
• 管理者の設定: この機能専用のオン・オフはない。どのアプリにWorkspaceのデータへのアクセスを許すかは、既存のアプリのアクセス制御で管理する

リリースノートによると、同じ機能はDocsが7月7日、Sheetsが7月23日、Slidesが8月31日にDeveloper Preview（参加登録した開発者向けの先行提供）として公開されていました。なお、Docs・Sheets・SlidesのMCPサーバー（AIエージェントから文書を操作するための接続口）を経由したコメント操作は、MCPサーバー自体と同じく先行提供の扱いのままだと告知に書かれています。今回の一般提供はREST APIの話です。

Discoveryの表示はまだ古いまま

Discoveryドキュメントは、Googleが各APIのメソッドと型を機械可読の形で公開しているものです。10月5日に取得したDocs・Sheets・SlidesのDiscovery（いずれもrevision 20260928）では、追加された項目の説明に「Developer Preview」の表示が残っていました。一方、developers.google.comのAPIリファレンス（batchUpdate など、9月30日更新）とガイドには、この表示はありません。表示が残っている理由は公式に説明されていないため、提供段階はリリースノートと告知で判断するのが確実です。

提案は「書き込み方」で作る

提案を作る専用のリクエストはありません。writeControl の writeMode に SUGGEST を指定して、いつもの insertText や deleteContentRange を送ります。指定しなければ通常の編集です。ガイドには「リクエスト内のすべての更新が提案として処理される」とあるので、同じ batchUpdate の中で確定の編集と提案を混ぜることはできません。分けたいときはリクエストを2回に分けます。

{
  "requests": [
    { "insertText": { "location": { "index": 120 }, "text": "（甲乙協議のうえ）" } }
  ],
  "writeControl": { "writeMode": "SUGGEST" }
}

応答の suggestionResponses には、各更新で作られた・承認された・却下された提案のIDが、リクエストと1対1で返ります。後から人が承認・却下した結果を照合する手がかりになります。

自動化に組み込む前に確かめること

提案モードで使えないリクエストがある

ガイドによると、SUGGEST では次のリクエストがエラーになります。

• タブの追加・削除・設定変更（AddDocumentTab・DeleteTab・UpdateDocumentTabProperties）
• 名前付き範囲の作成・削除（CreateNamedRange・DeleteNamedRange）
• ヘッダー・フッターの削除（DeleteHeader・DeleteFooter）
• 表の列の設定変更（UpdateTableColumnProperties）

UpdateDocumentStyle でも、用紙の形式（documentFormat）や、偶数ページ・先頭ページのヘッダーとフッターの設定は提案にできません。既存の自動化をそのまま SUGGEST に切り替えると、これらを含むリクエストは通らなくなります。

コメントや提案だけ保存に失敗することがある

ガイドには、コメントや提案を伴う batchUpdate は「部分的に失敗することがある」と書かれています。本文の挿入や削除は反映されたのに、付けたはずのコメントや提案が保存されていない、という状態です。応答の commentUpdateState が ALL_SAVED なら成功、ALL_FAILED_UNKNOWN_REASON ならコメント・提案の保存は失敗しています。Sheets・Slidesにも同じ項目があります。HTTPのステータスが成功でも、この値を見ないと失敗に気づけません。

位置は提案を含めた状態で数える

文書に未処理の提案があると、documents.get の読み方によって本文の位置（インデックス）がずれます。ガイドは、次の batchUpdate で使う位置を得るには suggestionsViewMode を SUGGESTIONS_INLINE にして読むよう求めています。提案を承認済み・却下済みとして表示する読み方で位置を取ると、書き込み先がずれます。

削除・編集・承認に必要な権限

• コメント本文は2,048 UTF-8コード単位まで。 日本語は1文字3バイトのため、目安は約680文字です。担当者（assigneeEmailAddress）も同じ上限です
• 削除・編集は作成者だけ。 コメントの削除や投稿の編集は、作成者以外だと400エラーになります。対応状況の変更（解決・再開）や担当者を含む返信は、作成者でも削除できません。自動化用のアカウントで付けたコメントは、そのアカウントでしか消せません
• 提案スレッドの最初の投稿は編集できない。 提案モードの書き込みで自動的に作られるためです
• 承認・却下・削除で必要な権限が違う。 提案の承認は編集権限が必要で、ない場合は403。却下は編集権限か提案の作成者であること、削除は提案の作成者であることが必要です

コメントを含めて読むときの指定

Docsで commentsViewMode を COMMENTS_VIEW_MODE_INCLUDED にする場合、suggestionsViewMode を SUGGESTIONS_INLINE にし、includeTabsContent を true にする必要があります（タブを参照するフィールドマスクでも可）。何も指定しなければコメントは返りません。Sheetsで範囲やシートを絞って読むと、元のセルが削除されて位置を失ったコメントは含まれません。

クライアントライブラリとApps Script

Node.jsの公式クライアントは、10月3日公開の googleapis 183.0.0と、Docsだけを含む @googleapis/docs 14.1.0で、writeMode と insertComment が型定義に入りました。9月24日公開の182.0.0までは入っていないので、古い版を固定している場合は更新が必要です。

Apps Scriptの高度なサービス（Docs）は、説明ページに「公開APIと同じオブジェクト・メソッド・パラメーターを使う」とあります。ただし、コメントや提案の操作についての個別の記載はなく、編集部はApps Scriptから実際に呼べるかを確かめていません。

Drive APIのコメントとの違い

Drive API v3にも以前から comments.create があります。こちらは文書内の位置を anchor というJSON文字列で表す方式で、Docs固有の範囲指定とは別のものです。Docs APIの insertComment は、本文の Range（開始・終了の位置）を直接受け取ります。位置を指定したコメントを付けたいなら、Docs API側の操作を前提に設計するほうが素直です。

AIの修正を人の承認に回す設計（編集部の提案）

コメントと提案モードが揃うと、自動化の結果を「確定した変更」ではなく「人が判断する候補」として文書に残せます。ここからは公式資料をもとにした編集部の提案です。実際のAPI呼び出しでは確かめていません。

1. AIやスクリプトの変更は SUGGEST で書く。 人が提案を承認するまで本文は確定しません。エディタ上では、人が付けた提案と同じ流れで確認できるはずです
2. 判断を求める箇所はコメントと担当者で示す。 本文を変えずに指摘だけしたい箇所は insertComment にし、assigneeEmailAddress で確認者を指定します
3. 書き込む前に版を固定する。 writeControl.requiredRevisionId を付けると、読み込んだ後に文書が変わっていた場合は400で止まります。人の編集を上書きしないための既存の仕組みです
4. 応答の commentUpdateState を必ず記録する。 失敗していたら、文書を読み直して本文とコメント・提案の状態を確かめ、担当者に知らせる手順を用意しておきます
5. スコープを絞る。 Docsの batchUpdate は documents・drive・drive.file のいずれかのスコープで呼べます。対象がアプリで作成・選択したファイルに限られるなら、drive.file が最も範囲が狭くなります

コメントがたまった文書をGeminiに読ませて返信を下書きする使い方は、GoogleドキュメントのGeminiでコメントを処理する手順で整理しています。APIで自動化する場合は、どのアカウントで動かし、どこで人が承認するかを先に決めておきます。Apps Scriptで組んだ自動化の引き継ぎについては前任者のGASを立て直す記事も参考になります。

落とし穴

• 提案モードを全APIで使えると思い込む。 writeMode があるのはDocs APIだけです。スプレッドシートの値の変更は、これまでどおり即時に反映されます
• 9月30日にすぐ全員が使えると思う。 展開には最大15日かかります。動かない場合は、展開が済んでいない可能性も考えます
• 自動化用アカウントのコメントを人が消せないと詰まる。 削除できるのは作成者だけなので、後始末の手順もスクリプトに用意しておきます
• 読み込み時にコメントが返らないのを不具合と思う。 既定は COMMENTS_VIEW_MODE_OMITTED です

2026年10月5日に、Google Workspace Updatesの告知（9月30日）、Docs・Sheets・Slides APIのリリースノート、ガイド「Work with comments and suggestions」「Manage comments」（Sheets・Slides）、Docs・Sheets・SlidesのAPIリファレンス、Apps Scriptの高度なサービス（Docs）の説明ページ、Docs・Sheets・Slides API（いずれもrevision 20260928）のDiscoveryドキュメント、npmの googleapis 183.0.0と @googleapis/docs 14.1.0の型定義を直接開いて照合しました。Drive APIのコメントの記述は、10月3日に取得したDrive API v3のDiscoveryドキュメントによります。実際のAPI呼び出し、Apps Scriptからの利用、エディタでの表示は検証していません。

Google Workspaceの文書業務の自動化や、AIに持たせる権限の設計は、IT・Google Workspaceのご相談からお問い合わせください。

Sources

• Programmatic comment and suggestion support now available in the Google Docs, Sheets, and Slides APIs — Google Workspace Updates
• Google Docs API release notes
• Google Sheets API release notes
• Google Slides API release notes
• Work with comments and suggestions — Google Docs API
• Manage comments — Google Sheets API
• Manage comments — Google Slides API
• Method: documents.batchUpdate — Google Docs API
• Advanced Docs Service — Apps Script
• Google Docs API v1 — Discovery document
• Google Drive API v3 — Discovery document
• googleapis — npm registry