【Googleドキュメント】Apps ScriptでDocs APIを直接呼出!REST API経由の操作

Google Apps Scriptを使ってGoogleドキュメントを操作する際、DocumentAppクラスだけではできない処理があります。例えば、段落の背景色を変えたり、ヘッダーやフッターに画像を挿入する操作は標準メソッドでは対応していません。そこでGoogle Docs REST APIを直接呼び出す方法を解説します。この記事では、Apps ScriptからUrlFetchAppを使ってAPIリクエストを送り、ドキュメントの細かな操作を実現する手順を紹介します。

なぜ直接REST APIが必要なのか?DocumentAppの限界

DocumentAppは便利なクラスですが、すべてのドキュメント要素を操作できるわけではありません。例えば、段落の背景色を変更するメソッドは存在しません。同様に、テーブルのセル結合を解除する操作や、カスタムスタイルを適用する処理もDocumentAppでは実現できません。一方、Google Docs REST APIはドキュメント内のすべての要素にアクセス可能です。APIを直接呼び出せば、DocumentAppでは不可能だった細かい調整が可能になります。ただし、認証情報の管理とHTTPリクエストの実装が必要です。

Google Docs APIを直接呼び出す実装手順

ステップ1:Google Cloud ConsoleでDocs APIを有効化する

1. Google Cloud Consoleを開きます
   ブラウザでGoogle Cloud Consoleにアクセスし、既存のプロジェクトを選択するか、新しいプロジェクトを作成します。
2. APIとサービスを有効にします
   「APIとサービス」から「ライブラリ」を選択し、「Google Docs API」を検索して有効にします。
3. 認証情報を作成します
   「認証情報」画面で「認証情報を作成」から「OAuth2クライアントID」を選択します。アプリケーションの種類は「ウェブアプリケーション」または「デスクトップアプリケーション」を選びます。

ステップ2:OAuth2認証を設定する

Apps Script内でOAuth2ライブラリを使用します。このライブラリはGoogle提供のものです。スクリプトエディタで「リソース」→「ライブラリ」から「1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF」を追加します。

// OAuth2ライブラリを初期化します
var CLIENT_ID = 'あなたのクライアントID';
var CLIENT_SECRET = 'あなたのクライアントシークレット';
var SCOPES = ['https://www.googleapis.com/auth/documents'];

function getDocsService() {
  return OAuth2.createService('docs')
    .setAuthorizationBaseUrl('https://accounts.google.com/o/oauth2/auth')
    .setTokenUrl('https://oauth2.googleapis.com/token')
    .setClientId(CLIENT_ID)
    .setClientSecret(CLIENT_SECRET)
    .setScope(SCOPES.join(' '))
    .setCallbackFunction('authCallback')
    .setPropertyStore(PropertiesService.getUserProperties());
}

function authCallback(request) {
  var docsService = getDocsService();
  var isAuthorized = docsService.handleCallback(request);
  if (isAuthorized) {
    return HtmlService.createHtmlOutput('認証に成功しました。このタブを閉じてください。');
  } else {
    return HtmlService.createHtmlOutput('認証に失敗しました。');
  }
}

ステップ3:UrlFetchAppでAPIリクエストを実行する

認証が完了したら、アクセストークンを取得してAPIエンドポイントにアクセスします。以下はドキュメントの内容を取得する関数です。

function getDocumentContent(documentId) {
  var docsService = getDocsService();
  if (!docsService.hasAccess()) {
    throw new Error('アクセストークンがありません。まず認証を実行してください。');
  }
  var accessToken = docsService.getAccessToken();
  var url = 'https://docs.googleapis.com/v1/documents/' + documentId;
  var options = {
    headers: {
      'Authorization': 'Bearer ' + accessToken
    },
    method: 'get',
    muteHttpExceptions: true
  };
  var response = UrlFetchApp.fetch(url, options);
  return JSON.parse(response.getContentText());
}

次に、特定の段落のテキストを置換する例です。APIのバッチ更新リクエストを使います。

function replaceTextInParagraph(documentId, paragraphIndex, newText) {
  var docsService = getDocsService();
  if (!docsService.hasAccess()) throw new Error('トークンがありません。');
  var accessToken = docsService.getAccessToken();
  var url = 'https://docs.googleapis.com/v1/documents/' + documentId + ':batchUpdate';
  var requests = [{
    replaceAllText: {
      containsText: { text: '{{置換対象}}', matchCase: true },
      replaceText: newText
    }
  }];
  var options = {
    headers: {
      'Authorization': 'Bearer ' + accessToken,
      'Content-Type': 'application/json'
    },
    method: 'post',
    payload: JSON.stringify({ requests: requests }),
    muteHttpExceptions: true
  };
  var response = UrlFetchApp.fetch(url, options);
  return JSON.parse(response.getContentText());
}

注意点とよくあるエラー

スコープが不足している場合のエラー

APIリクエスト時に403エラーが返ってくる場合、スコープの設定が正しいか確認します。ドキュメントの読み取りだけならhttps://www.googleapis.com/auth/documents.readonly、書き込みが必要ならhttps://www.googleapis.com/auth/documentsを指定します。OAuth同意画面でスコープを追加し、再度認証を実行してください。

レート制限を超えた場合の対処

Google APIにはレート制限があります。短時間に多数のリクエストを送ると429エラーが発生します。その場合はUtilities.sleep()で待機するか、リクエスト数を分散させる必要があります。

アクセストークンの有効期限切れ

OAuth2トークンは通常1時間で期限切れになります。有効期限が切れると401エラーが返ります。その場合は自動的にリフレッシュされるよう、OAuth2ライブラリの設定でsetTokenRefreshTimeを調整するか、reset()で強制的に再認証させます。

まとめ

この記事では、Apps ScriptからGoogle Docs REST APIを直接呼び出す方法を解説しました。標準のDocumentAppでは不可能な操作も、APIを使えば柔軟に実現できます。具体的には、Cloud ConsoleでのAPI有効化、OAuth2ライブラリを用いた認証、そしてUrlFetchAppによるHTTPリクエストの送信という流れです。最初は手間がかかりますが、一度仕組みを整えれば、ドキュメントの自動編集やデータ変換など、高度な自動化が可能になります。

📄

Googleドキュメントトラブル完全解決データベースこの記事以外にも、書式・共有・Apps Script・引用など様々な困りごとへの解決策をまとめています。逆引きに活用してください。