GASから外部APIを呼び出してデータを取り込む仕組み(UrlFetchApp・中級編)

GASから外部APIを呼び出してデータを取り込む仕組み(UrlFetchApp・中級編) GAS

こんにちは!ともです。外部サービスのデータを、ブラウザで開いて、コピーして、スプレッドシートに貼り付けて。件数が少ないうちは手作業でも回りますが、毎日・毎週の作業になると、この「運ぶ」部分こそプログラムに任せたいところです。

GASには、外部のAPIを呼び出すための UrlFetchApp という仕組みが用意されています。この記事では、取得(データを取り込む)と投稿(データを送る)の両方を扱いながら、APIキーの置き場所や、失敗したときの再試行と記録まで含めた、中級編としての運用の形をまとめます。

【この記事で分かること】

この記事で分かること
この記事で分かること
  • 完成品で何ができるようになるか
  • 必要なものとコスト(無料で使える範囲と上限)
  • プロジェクトの作成と、外部接続の権限承認の手順
  • APIキーをスクリプトプロパティに分離する方法
  • 取得(GET)と投稿(POST)のコードの骨格
  • エラー時の再試行と、失敗を記録に残す考え方

【完成品のイメージ:実行すると、最新データがシートに増えていく】

完成品のイメージ:実行すると、最新データがシートに増えていく
完成品のイメージ:実行すると、最新データがシートに増えていく

完成すると、関数を実行するたびに、外部APIから最新のデータを取得して、スプレッドシートの末尾へ1行ずつ追加していきます。この記事の題材は、練習用に公開されているダミーのAPIと、自分で用意したダミーデータです。

前回のトリガーの作例と組み合わせれば、「毎朝決まった時刻にAPIを呼び出して、その日のデータを記録する」という形にも広げられます。取得の部分はこの記事、実行のタイミングはトリガー、という役割分担です。

【必要なものとコスト】

必要なものとコスト
必要なものとコスト

GAS自体は無料で使えます。外部API側の料金はサービスごとに異なるため、使うAPIの料金体系を先に確認してください。この記事で関係するGAS側の上限の目安は次のとおりです(2026年11月確認時点)。

項目内容
使うツールGoogle Apps Script(UrlFetchApp)/Googleスプレッドシート(記録先)/題材となる外部API
料金の目安GASは無料(約0円)。外部APIはサービスにより異なる(無料枠のあるものも多い)。有料APIを使う場合は、その料金が別にかかる
呼び出し回数の上限UrlFetchAppの呼び出しは、無料のGoogleアカウントで1日20,000回まで(Google Workspaceでは1日100,000回まで)
前提Googleアカウント/APIの利用登録とAPIキー(必要なサービスの場合)/題材はダミーデータか、利用規約で許可された範囲のデータだけを使う

APIの利用規約はサービスごとに違います。取得したデータの保存や再利用が許されているか、呼び出し頻度の制限(レート制限)があるかは、組み込む前に公式の案内で確認してください。上限の数値はGoogle側の都合で変わることがあるため、設計の前に最新の案内を確認しておくのが安全です。

【難易度と進め方の目安】

難易度と進め方の目安
難易度と進め方の目安

難易度は中くらいです。コードの量は多くありませんが、「認証(APIキーの渡し方)」「エラーの扱い方」という、外部と通信する処理ならではの考え方が出てきます。目安の所要時間は、API側の登録を除いて1時間前後です。

進め方は「プロジェクトの用意→APIキーをプロパティに保存→取得のコード→投稿と再試行のコード→動作確認」の順番です。題材のAPIは、まず練習用のダミーAPIで肩慣らしをしてから、本命のAPIに差し替える進め方が安全です。

【初期設定:プロジェクトの作成とAPIキーの置き場所】

初期設定:プロジェクトの作成とAPIキーの置き場所
初期設定:プロジェクトの作成とAPIキーの置き場所

プロジェクトの作成と初回の権限承認は、トリガーの作例と同じ流れです。スプレッドシートにひも付ける場合は「拡張機能」メニューから「Apps Script」を開き、初回実行時に表示される承認の手順を最後まで進めてください。UrlFetchAppを使うコードでは、承認の内容に「外部サービスへの接続」が含まれます。求められている許可の範囲を確認してから承認してください。

次に、APIキーの置き場所です。APIキーは、コードの中に直接書き込むものではありません。コードは共有したり公開したりする機会があり、そのたびにキーが漏れる危険があるからです。GASには、コードとは別に値を保管できる「スクリプトプロパティ」という場所が用意されています。設定の手順は次のとおりです。

  1. エディタの左メニューから「プロジェクトの設定」(歯車のアイコン)を開く
  2. 「スクリプト プロパティ」の欄で「スクリプト プロパティを追加」を選ぶ
  3. プロパティ名(例:WEATHER_API_KEY)と、値(APIキーそのもの)を入力して保存する

値の欄に入れるのは、自分のキーだけです。この記事のコード例に出てくるキー名はダミーの名前で、実在のキーは一切載せていません。記事や画面の共有時にキーが写り込まないよう、扱いはパスワードと同じにしてください。

【作り方の骨格1:APIから取得してシートへ記録する】

作り方の骨格1:APIから取得してシートへ記録する
作り方の骨格1:APIから取得してシートへ記録する

最初に、外部APIからデータを取得し、必要な項目だけをシートへ記録する部分を作ります。

// 外部APIからデータを取得して、スプレッドシートへ書き込む
function fetchAndSave() {
  // APIキーはコードに直接書かず、スクリプトプロパティから読み込む
  const apiKey = PropertiesService.getScriptProperties().getProperty('WEATHER_API_KEY');

  // 取得先のURLを組み立てる(題材は練習用のダミーAPI)
  const url = 'https://example.com/api/weather?city=tokyo';

  // リクエストの条件をまとめる(APIキーはヘッダーで渡す)
  const options = {
    method: 'get',
    headers: { 'Authorization': 'Bearer ' + apiKey },
    // エラー時も例外で止めず、ステータスコードを自分で確認できるようにする
    muteHttpExceptions: true
  };

  // APIを呼び出して、レスポンスを受け取る
  const response = UrlFetchApp.fetch(url, options);

  // ステータスコードが200番台でなければ、内容をログに残して終了する
  const statusCode = response.getResponseCode();
  if (statusCode < 200 || statusCode >= 300) {
    console.error('APIの呼び出しに失敗しました: ' + statusCode);
    return;
  }

  // 受け取ったJSON文字列を、扱いやすいオブジェクトに変換する
  const data = JSON.parse(response.getContentText());

  // 必要な項目だけを取り出して、シートの末尾へ1行追加する
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('取得データ');
  sheet.appendRow([new Date(), data.city, data.temperature]);
}

ポイントは2つです。1つ目は muteHttpExceptions: true です。これを指定しないと、API側がエラーを返した時点でコードが例外で止まってしまい、「何番のエラーだったか」が分からなくなります。通信の処理では、成功したかどうかをステータスコードで自分で判断する形が基本です。

2つ目は、APIキーの渡し方です。ヘッダーで渡す形が一般的ですが、サービスによってはURLのパラメータで渡す形もあります。URLにキーを含めると、ログや履歴にキーが残りやすくなります。使うAPIの公式ドキュメントで指定された方法に従い、可能ならヘッダーで渡す形を選んでください。

なお、複数のURLをまとめて取得したい場合は、UrlFetchApp.fetchAll という、リクエストを配列で渡して一括で呼び出す方法もあります。並行して処理するため、1件ずつ呼ぶより処理が速くなります。ただし、呼び出し回数の上限に対してはリクエスト1件ごとに数えられるため、回数自体は減りません。件数が多い処理では、速度面でこちらへの置き換えを検討してください。

【作り方の骨格2:APIへ投稿する(再試行つき)】

作り方の骨格2:APIへ投稿する(再試行つき)
作り方の骨格2:APIへ投稿する(再試行つき)

次に、データを外部へ送る投稿(POST)の形です。投稿は「送れたつもりで送れていない」が一番困る処理なので、失敗したときの再試行と記録まで含めて組み立てます。

// 外部APIへデータを送信する(失敗したら間隔を空けて再試行する)
function postWithRetry(url, payload) {
  // 送信の条件をまとめる(本文はJSON形式で送る)
  const options = {
    method: 'post',
    contentType: 'application/json',
    payload: JSON.stringify(payload),
    // エラー時も例外で止めず、ステータスコードで判断する
    muteHttpExceptions: true
  };

  // 最大で試す回数を決めておく
  const maxAttempts = 3;

  // 成功するか、上限回数に達するまで繰り返す
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    // APIを呼び出す
    const response = UrlFetchApp.fetch(url, options);
    const statusCode = response.getResponseCode();

    // 成功したら、レスポンスを返して終了する
    if (statusCode >= 200 && statusCode < 300) {
      return response;
    }

    // 失敗した事実とステータスコードをログに残す
    console.error('送信に失敗しました(' + attempt + '回目): ' + statusCode);

    // 最後の試行でなければ、少し待ってから再試行する(待つ時間は回数ごとに広げる)
    if (attempt < maxAttempts) {
      Utilities.sleep(2000 * attempt);
    }
  }

  // 上限回数まで試しても失敗したら、呼び出し元にエラーを伝える
  throw new Error('APIへの送信が' + maxAttempts + '回とも失敗しました');
}

待つ時間を回数ごとに広げているのは、相手のサーバーが一時的に混み合っている場合への配慮です。間隔を空けずに何度も叩くのは、相手側の制限(レート制限)に触れる原因にもなります。再試行は「3回まで」のように上限を決め、それでも失敗したらエラーとして表に出すのが基本形です。

失敗の記録も残しておきましょう。console.error のログは実行履歴から確認できますが、運用が長くなるとログだけでは追いづらくなります。「いつ・何を送ろうとして・何番のエラーで失敗したか」を、記録用のシートへ1行ずつ残す形にしておくと、あとから失敗分だけを送り直すこともできます。

【つまずきやすい点】

つまずきやすい点
つまずきやすい点

よくあるつまずきは5つです。1つ目は、APIキーをコードに直接書いてしまうことです。コードを共有・公開した瞬間にキーが漏れ、第三者に使われる危険があります。キーは必ずスクリプトプロパティに分離し、万が一漏れたら、発行し直して古いキーを無効化してください。2つ目は、エラーの中身が見えないことです。muteHttpExceptions を付けずに動かすと、失敗した時点で処理が止まり、原因の手がかりが残りません。通信のコードでは、ステータスコードとレスポンス本文を確認できる形にしておくことが先決です。3つ目は、呼び出し回数の上限です。UrlFetchAppの呼び出しは、無料のGoogleアカウントで1日20,000回までです。1件の処理で何度もAPIを呼ぶ設計だと、件数が増えたときに上限へ先に届きます。取得済みデータの使い回し(キャッシュ)や、取得の頻度・対象を絞ることで、呼び出し回数を抑える設計にしてください。4つ目は、相手側の制限です。APIには「1分間に何回まで」といったレート制限や、利用規約上の条件が付いているのが普通です。GAS側の上限の内側でも、相手側の制限を超えればエラーになります。再試行の間隔も含め、相手のルールに合わせることが前提です。5つ目は、受け取ったデータの形が想定と違うことです。APIの仕様変更で項目名が変わったり、値が空で返ってきたりすると、そのままシートへ書くと壊れた行が増えていきます。記録する前に、必要な項目がそろっているかを軽く確認する処理を挟んでおくと安全です。

【まとめ】

まとめ
まとめ

GASから外部APIを呼び出す形は、「APIキーはスクリプトプロパティに分離する→取得はステータスコードを見て判断する→投稿は再試行と記録つきにする」という3点を押さえれば、運用できる形になります。通信は失敗するものだという前提で組むことが、中級編のポイントです。

この取得の処理は、決まった時刻に自動で動かすトリガーと組み合わせると、定期的なデータ収集の仕組みになります。

GASを決まった時刻に自動で動かす仕組み

同じ「外部からデータを取得して記録する」作業は、Pythonのスクレイピングでも実現できます。対象や規模に合わせて選んでください。

Webサイトの新着を定期チェックしてスプレッドシートに記録する仕組み

GASそのものが初めての方は、入門のレシピ集から始めるのがおすすめです。

GASレシピ一覧(ショートマスター)

なお、「自分で作るのではなく、業務の自動化そのものを相談したい」という場合は、作ってもらう選択肢もあります。

\ 業務の自動化やAI活用を、代わりに作ってほしい方はこちら /

コメント

タイトルとURLをコピーしました