【GAS入門#51】Googleドキュメントを自動操作!DocumentApp.openById()の使い方とDocsの階層構造(Body・Paragraph)を徹底解説

スプレッドシートの操作やGmail連携、Google Driveのファイル管理を学んできた本連載。

いよいよ今回からは「フェーズ6:Google Docs(ドキュメント)操作編」に突入します!

Googleドキュメントは、報告書や契約書、請求書やマニュアルなどの文章作成に欠かせないツールですよね。

GASを使えば、Googleドキュメントのテンプレートを開き、文字を自動で書き換えたり、PDF化して顧客にメール送信したりといった「文書作成の全自動化」が実現できます。

その第一歩となる第51回では、特定のGoogleドキュメントをプログラムから開く超基本命令 DocumentApp.openById() を解説します!

さらに、ドキュメントを自由自在に操作する上で絶対に避けては通れない「Google Docsの階層構造(Document、Body、Paragraphなどの関係性)」についても、「家・部屋・家具」の例えを使いながらどこよりも分かりやすく紐解いていきます。

「札幌オフィスの請求書テンプレート」を題材に、実際にコードを動かしながらマスターしていきましょう!

1. そもそも DocumentApp.openById() とは?

これまでスプレッドシートを操作するときは SpreadsheetApp を使ってきましたよね。

Googleドキュメントを操作するときは、親玉(クラス)が DocumentApp(ドキュメント・アップ) に変わります。

そして、指定したGoogleドキュメントファイルをID(固有の識別番号)でピンポイントに開く命令が DocumentApp.openById() です。

DocumentApp.openById("ここにドキュメントIDを入力");

コードの構造を分解してみよう

  • DocumentApp(ドキュメント・アップ)
    Googleドキュメントに関する機能をまとめて管理している親玉(クラス)です。GASに対して「今からGoogleドキュメントの操作をするよ!」と宣言する役割を果たします。
  • .openById(id)(オープン・バイ・アイディー)
    DocumentApp に対する命令(メソッド)です。カッコの中にドキュメントの「ID文字列」を渡すことで、該当するGoogleドキュメントファイルを特定してプログラム内に読み込みます。

getActiveDocument() と openById() の違い

スプレッドシート編を思い出してみてください。

スプレッドシートには SpreadsheetApp.getActiveSpreadsheet() という「今開いているファイルを取得する命令」がありましたよね。

Googleドキュメントにも DocumentApp.getActiveDocument() という似た命令が存在します。

しかし、実務の自動化においては openById() の方が圧倒的に良く使われます。

命令(メソッド)特徴主な用途
getActiveDocument()コンテナバインドスクリプト(ドキュメントの「拡張機能」から作成したGAS)で、現在開いているドキュメント自身を取得する。ドキュメント側につけたカスタムメニューやボタンから処理を動かすとき
openById(id)ドキュメントのIDを指定して、外部から特定のドキュメントをピンポイントで開く。スプレッドシートの顧客リストをもとに、Docsの請求書テンプレートを自動生成するとき など

実務で一番多い「スプレッドシートに入力されたデータから、Googleドキュメントの帳票を自動作成する」というシステムを作る場合、スプレッドシート側のGASからドキュメントを開く必要があるため、openById() が必須になります!

「ドキュメントID」ってどこにあるの?

GoogleドキュメントのIDは、ブラウザのアドレスバー(URL)を見ると一目で分かります。

Googleドキュメントを開いたときのURLは、以下のような形式になっています。

https://docs.google.com/document/d/1A2B3C4D5E6F7G8H9I0J_ExampleID_1234567/edit

このURLの中にある、/d/ と /edit に挟まれた英数字の長い文字列(上記でいう 1A2B3C4D5E6F7G8H9I0J_ExampleID_1234567 の部分)が、そのファイル固有の「ドキュメントID」です。

このIDをコピーして openById("ID文字列") のカッコ内に渡すことで、GASは目的のドキュメントを正確に見つけ出すことができます。

2. 超重要!Google Docsの階層構造(Document・Body・Paragraph)をマスターしよう

コードを書き始める前に、Googleドキュメントがどのような構造(組み立て)になっているかを理解しておきましょう。ここを理解しておくと、今後のDocs操作でエラーに悩まされることがなくなります!

スプレッドシート編でおなじみだった「家・部屋・家具」の例えを使って比較してみましょう。

スプレッドシートとGoogleドキュメントの階層構造対比表

概念スプレッドシート(SpreadsheetApp)Googleドキュメント(DocumentApp)★今回現実世界での例え
親玉SpreadsheetAppDocumentApp不動産屋さん
ファイルSpreadsheet(ファイル全体)Document(ドキュメント全体)家(建物)
部屋・エリアSheet(個別のワークシート)Body(本文エリア)
(その他 Header / Footer など)
部屋(リビングなど)
要素・中身Range(セル・マス目)Paragraph(段落)
Table(表)
Image(画像)
家具(引き出しや本棚)
データ本体.getValue() / .setValue()Text(文字・文字列)家具の中のメモ・本
【Google Docsの階層イメージ】

 Document (ドキュメントファイル全体=家)
    │
    ├── Body (本文エリア=主要な部屋) ★文字や表が入るメインの場所
    │    ├── Paragraph (第1段落=家具) ── Text ("札幌オフィス 請求書")
    │    ├── Paragraph (第2段落=家具) ── Text ("ご請求金額:¥100,000")
    │    ├── Table (明細表=家具)
    │    └── InlineImage (社印画像=家具)
    │
    ├── Header (ヘッダーエリア=屋根裏部屋)
    └── Footer (フッターエリア=地下室)

なぜ Body や Paragraph を理解する必要があるの?

初心者の方が最も陥りやすい罠が、「ドキュメント(Document)を取得したから、そのまま文字を書き換えられるだろう!」 と思ってしまうことです。

例えば、ドキュメントを開いていきなり doc.replaceText() や doc.getText() と書こうとしても動かなかったり、思い通りにいかなかったりします。

なぜなら、Googleドキュメントには「本文(Body)」のほかに「ヘッダー(Header)」「フッター(Footer)」という別のエリアが存在するからです。

  • Document:ファイルそのものの名前変更や保存、権限管理などを行う「ファイル全体の枠組み」
  • Body:実際にユーザーが文字や表を書き込む「本文エリア」
  • Paragraph:本文の中にある「1つの段落(改行で区切られた文章のかたまり)」

つまり、「ファイル(Document)を開き ➡ 本文エリア(Body)に入り ➡ 指定の段落(Paragraph)やテキスト(Text)を操作する」 という順番でドキュメント内部へ潜っていく必要があるのです!

3. STEP1:準備!「札幌オフィス請求書テンプレート」を作成しよう

それでは、実際にGASから操作するための練習用Googleドキュメントを作成していきましょう!

今回は札幌オフィスの業務を想定した「請求書テンプレート」を作成します。

手順

  1. Googleドライブを開く
    ブラウザでGoogleドライブを開き、「新規」>「Googleドキュメント」をクリックして新しいドキュメントを作成します。
  2. ファイル名を変更する
    画面左上の「無題のドキュメント」をクリックし、札幌オフィス請求書テンプレート と入力します。
  3. 本文にサンプルテキストを入力する
    ドキュメントの本文(Body)に、以下のように適当なテキストを入力しておきます。請求書株式会社札幌スープカレー本舗 御中いつも大変お世話になっております。札幌オフィスより、今月分のシステム保守費用をご請求申し上げます。
  4. ドキュメントIDをコピーする
    画面上部のアドレスバー(URL)から、/d/ と /edit の間にあるドキュメントID文字列をコピーしておきます。
例:https://docs.google.com/document/d/ 【1abc123456XYZ_thisIsMyDocumentID】 /edit
                                      ↑この部分をコピー!

4. STEP2:【実践】GASからドキュメントを開いて構造を解析してみよう!

準備ができたら、GASのプログラムを書いていきましょう!

今回は、コンテナバインドスクリプトでもスタンドアロンスクリプトでも構いません。

使い慣れたGoogleスプレッドシートの「拡張機能」>「Apps Script」からエディタを開くか、Googleドライブの「新規」>「その他」>「Google Apps Script」で新しいスクリプトを作成してください。

1. コードを入力する

エディタ画面のコードをすべて消して、以下のコードを貼り付けます。

YOUR_DOCUMENT_ID_HERE の部分には、先ほどコピーしたご自身のドキュメントIDを貼り付けてください("" で囲むのを忘れないようにしましょう!)。

function openAndAnalyzeDoc() {
  // ① コピーしたドキュメントIDを指定する
  var docId = "YOUR_DOCUMENT_ID_HERE";
  
  // ② DocumentApp.openById() で「家(ドキュメント全体)」を開く
  var doc = DocumentApp.openById(docId);
  
  // ③ ドキュメントのタイトル(ファイル名)を取得してログ出力
  var docName = doc.getName();
  Logger.log("■ ファイル名: " + docName);
  
  // ④ ドキュメントの「部屋(本文エリア:Body)」を取得する
  var body = doc.getBody();
  
  // ⑤ Body内にあるすべての「段落(Paragraph)」を配列として取得する
  var paragraphs = body.getParagraphs();
  Logger.log("■ 段落の総数: " + paragraphs.length + "件");
  
  // ⑥ 各段落のテキストを順番に取り出してログに表示してみる
  for (var i = 0; i < paragraphs.length; i++) {
    var text = paragraphs[i].getText();
    // 空行でなければログに出力
    if (text !== "") {
      Logger.log(" ・第 " + (i + 1) + " 段落: " + text);
    }
  }
}

2. コードを1行ずつ徹底解説!

  • var doc = DocumentApp.openById(docId);
    本日の主役です!指定したIDのGoogleドキュメントを開き、Document オブジェクトを取得して変数 doc に代入しています。
  • var docName = doc.getName();
    Document オブジェクトの .getName() メソッドを呼び出し、ファイル名(「札幌オフィス請求書テンプレート」)を取得しています。
  • var body = doc.getBody();
    Document から本文エリアである Body オブジェクトを取得しています。文章の追加や置換を行うときは、この body 変数に対して操作を行います。
  • var paragraphs = body.getParagraphs();
    Body 内に含まれているすべての段落(Paragraph オブジェクト)を配列(リスト)形式でまとめて取得します。
  • paragraphs[i].getText()
    1つひとつの段落オブジェクトに対して .getText() を呼び出すことで、その段落に入っている実際の文字列を取り出しています。

3. 初回実行時の「承認プロセス」を乗り越えよう

コードが入力できたら、上部の 「保存(フロッピーマーク)」 を押し、「実行」 ボタンをクリックしましょう。

スプレッドシートやGmailの時と同様に、初回実行時のみGoogleのセキュリティ権限確認ポップアップ(承認プロセス)が表示されます。

  1. 「権限を確認」 をクリック
  2. ログイン中の Googleアカウントを選択
  3. 「このアプリは Google で検証されていません」が出たら、左下の 「詳細」 をクリック
  4. 「〜(安全ではないページ)に移動」 をクリック
  5. 最後の画面で 「許可」 をクリック

※過去の第2回記事でも詳しく解説したGoogleの正常なセキュリティ手順ですので、安心して許可してくださいね。

4. 実行結果を確認する

承認が完了すると処理が実行されます。エディタ下部の「実行ログ」を確認してみましょう!

情報    ■ ファイル名: 札幌オフィス請求書テンプレート
情報    ■ 段落の総数: 5件
情報    ・第 1 段落: 請求書
情報    ・第 2 段落: 株式会社札幌スープカレー本舗 御中
情報    ・第 3 段落: いつも大変お世話になっております。
情報    ・第 4 段落: 札幌オフィスより、今月分のシステム保守費用をご請求申し上げます。

GASが指定したGoogleドキュメントを開き、ファイル名や本文の中身(段落ごとのテキスト)を完璧に読み取れていることが確認できましたね!

5. 初心者が絶対につまずく!5大トラップと解決策

DocumentApp.openById() やDocs操作を始める際、初心者が特によく遭遇するエラーやトラブルを5つ厳選しました。ここで予習しておけば、ハマって何時間も悩む心配はありません!

トラップ1:IDにURL全体を入れてしまい「Unexpected error」になる

// ✕ 間違い:URL全体を入れてしまっている
var doc = DocumentApp.openById("https://docs.google.com/document/d/1abc12345/edit");

// ◯ 正しい:IDの文字列だけを抜き出して入れる
var doc = DocumentApp.openById("1abc12345");

openById() に渡すのは、/d/ と /edit の間のID文字列のみです。URL全体を貼り付けてしまうと「Document is missing or the ID is invalid(ドキュメントが存在しないかIDが無効です)」というエラーが発生します。

トラップ2:doc.getText() や doc.replaceText() と書いてエラーになる

// ✕ 間違い:Documentオブジェクトに対して直接操作しようとしている
var text = doc.getText(); // TypeError: doc.getText is not a function

// ◯ 正しい:一度 getBody() を挟んでから操作する
var body = doc.getBody();
var text = body.getText();

先ほどの「階層構造」で解説した通り、getText() や replaceText() などのテキスト操作メソッドは Body(本文)が持っている命令 です。

必ず doc.getBody() で本文オブジェクトを取得してから呼び出すようにしましょう。

トラップ3:getParagraphs() の結果に直接 .getText() を使ってしまう

// ✕ 間違い:段落の「配列(リスト)」に対して直接 getText() を呼んでいる
var paragraphs = body.getParagraphs();
var text = paragraphs.getText(); // TypeError: paragraphs.getText is not a function

// ◯ 正しい:配列のインデックス [0] や forループで個別の段落を取り出して呼ぶ
var firstParagraphText = paragraphs[0].getText();

getParagraphs() の語尾に s がついている通り、返ってくる結果は複数形(配列)です。お弁当箱の中に複数の段落が詰まっている状態なので、paragraphs[0] やループ処理で1つずつの段落を取り出してから .getText() を呼び出す必要があります。

トラップ4:大文字・小文字のタイポ(DocumentApp と openById)

  • ✕ documentApp.openById() (先頭の d が小文字)
  • ✕ DocumentApp.openByID() (IDの D が大文字)
  • ◯ DocumentApp.openById() (App の A、By の B、Id の I のみ大文字)

GASは英大文字と小文字を厳密に区別します。タイポを防ぐためにも、エディタで DocumentApp. と入力した際に出てくる予測変換(補完機能)を Tab キーや Enter キーで決定して入力するのが確実です。

トラップ5:権限(アクセス権)のないドキュメントIDを指定している

自分自身がアクセス権限(閲覧権限や編集権限)を持っていない他人のGoogleドキュメントIDを指定すると、アクセス拒否エラー(Exception: You do not have permission to access the requested document.)が発生します。

操作したいドキュメントが自分のGoogleドライブ内にあるか、または共有されているかを確認しましょう。

6. 今回のまとめと次回予告

今回は、Google Docs自動化の第一歩として DocumentApp.openById() と Google Docsの階層構造 について学びました。

今日の重要ポイントおさらい

  1. DocumentApp.openById("ID") で指定のGoogleドキュメントを外部から開くことができる
  2. ドキュメントIDはURLの /d/ と /edit に挟まれた長い英数字
  3. Google Docsは Document(家) ➡ Body(部屋) ➡ Paragraph(家具・段落) という階層構造になっている
  4. 本文のテキストを操作するときは、必ず doc.getBody() で本文エリアを取得する

次回予告

ファイルを開いて本文(Body)構造を掴むことができたら、次はいよいよ「テンプレートの文字を自由自在に自動書き換えする」という超実践的なテクニックに入っていきます!

次回(第52回)は、Body.replaceText() × テンプレート内の「{請求先会社名}」や「{請求日}」を一括置換 をお届けします。

今回作成した「札幌オフィス請求書テンプレート」内のプレースホルダー文字({請求先会社名} など)を、GASから一瞬で本番の顧客名や金額に置き換える神機能を解説します。お楽しみに!