Office Scriptsのエラーハンドリング入門！API通信エラーの原因と再試行処理をやさしく解説

1. Office Scriptsとは？API連携でExcel自動化

1. Office Scriptsとは？API連携でExcel自動化

Office Scriptsは、Excel Onlineで動作する自動化ツールです。Excelの操作をコードで記述することで、毎日の作業を効率化できます。 特に最近は、API連携によって外部サービスとデータをやり取りする使い方が増えています。

APIとは「アプリケーション同士をつなぐ窓口」のことです。たとえば、天気情報を取得するWebサービスや、社内システムのデータを取得する仕組みなどがあります。 Office ScriptsからAPI通信を行うことで、最新データをExcelに自動反映できます。

しかし、API通信ではエラーが発生することがあります。そのため、エラーハンドリングと再試行処理の知識が重要です。

2. API通信エラーの主な原因とは？

2. API通信エラーの主な原因とは？

API通信エラーとは、Excelと外部サーバーとの通信がうまくいかない状態です。 原因はいくつかあります。

• インターネット接続が不安定
• APIのURLが間違っている
• サーバー側が停止している
• アクセス制限や認証エラー

たとえば、電話をかけたときに相手が圏外だとつながりませんよね。それと同じで、サーバーが応答できないとAPI通信エラーになります。

エラーメッセージには「404」や「500」などの数字が表示されることがあります。これはHTTPステータスコードと呼ばれる通信結果の番号です。 404は「見つからない」、500は「サーバー内部エラー」を意味します。

3. Office Scriptsでの基本的なAPI通信コード

3. Office Scriptsでの基本的なAPI通信コード

Office Scriptsではfetch関数を使ってAPI通信を行います。まずは基本的な書き方を見てみましょう。

async function main(workbook: ExcelScript.Workbook) {
  const response = await fetch("https://example.com/api/data");
  const data = await response.json();

  const sheet = workbook.getActiveWorksheet();
  sheet.getRange("A1").setValue(data.message);
}

このコードはAPIからデータを取得し、Excelのセルに表示する例です。 しかし、通信が失敗するとエラーが発生します。

4. try-catchでエラーハンドリングを行う方法

4. try-catchでエラーハンドリングを行う方法

エラーハンドリングとは、エラーが発生したときにプログラムを安全に止めたり、別の処理を行ったりする仕組みです。 Office Scriptsではtry-catch構文を使います。

async function main(workbook: ExcelScript.Workbook) {
  try {
    const response = await fetch("https://example.com/api/data");
    const data = await response.json();
    workbook.getActiveWorksheet().getRange("A1").setValue(data.message);
  } catch (error) {
    workbook.getActiveWorksheet().getRange("A1").setValue("通信エラーが発生しました");
  }
}

tryの中でエラーが起きると、catchの中が実行されます。 これにより、Excelにエラーメッセージを表示できます。

5. HTTPステータスコードを確認する方法

5. HTTPステータスコードを確認する方法

API通信では、response.okを確認することで成功か失敗かを判断できます。 通信自体は成功しても、ステータスコードがエラーの場合があります。

async function main(workbook: ExcelScript.Workbook) {
  const response = await fetch("https://example.com/api/data");

  if (!response.ok) {
    workbook.getActiveWorksheet().getRange("A1")
      .setValue("エラーコード: " + response.status);
    return;
  }

  const data = await response.json();
  workbook.getActiveWorksheet().getRange("A1").setValue(data.message);
}

これにより、API通信エラーの原因を調査しやすくなります。

6. 再試行処理（リトライ）の実装方法

6. 再試行処理（リトライ）の実装方法

再試行処理とは、通信が失敗したときにもう一度API通信を行う仕組みです。 一時的なネットワーク不具合なら、再試行で成功する場合があります。

async function fetchWithRetry(url: string, retries: number) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(url);
      if (!response.ok) throw new Error("HTTPエラー");
      return await response.json();
    } catch (error) {
      if (i === retries - 1) throw error;
    }
  }
}

async function main(workbook: ExcelScript.Workbook) {
  try {
    const data = await fetchWithRetry("https://example.com/api/data", 3);
    workbook.getActiveWorksheet().getRange("A1").setValue(data.message);
  } catch (error) {
    workbook.getActiveWorksheet().getRange("A1").setValue("再試行しても失敗しました");
  }
}

このコードでは最大3回までAPI通信を再試行します。 retry回数を調整することで、安定したExcel自動化が可能になります。

7. 待機時間を入れた安全な再試行処理

7. 待機時間を入れた安全な再試行処理

すぐに連続でAPI通信を行うと、サーバーに負荷がかかることがあります。 そのため、少し待ってから再試行する方法もあります。

function sleep(ms: number) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function main(workbook: ExcelScript.Workbook) {
  for (let i = 0; i < 3; i++) {
    try {
      const response = await fetch("https://example.com/api/data");
      if (!response.ok) throw new Error();
      const data = await response.json();
      workbook.getActiveWorksheet().getRange("A1").setValue(data.message);
      return;
    } catch {
      await sleep(1000);
    }
  }

  workbook.getActiveWorksheet().getRange("A1").setValue("一定時間後も通信失敗");
}

これをバックオフ処理と呼びます。安定したAPI連携を行うための重要なテクニックです。

まとめ

まとめ

今回は、Office Scriptsを使ったAPI通信エラーの原因と、その対策として重要になるエラーハンドリングや再試行処理について、基礎から丁寧に確認しました。Excel自動化を行ううえで、外部API連携は非常に便利な仕組みですが、インターネット通信を伴う以上、通信失敗やサーバー応答エラーは必ず起こり得ます。 そのため、単にfetch関数でデータ取得を行うだけでなく、trycatch構文による例外処理、responseokやresponse statusを活用したHTTPステータスコード確認、そして一定回数の再試行処理を組み込むことが重要です。 特にOffice ScriptsはTypeScriptで記述するため、非同期処理やawaitの理解も欠かせません。API通信エラー対策を正しく実装することで、Excel Online上で動作する自動化スクリプトの信頼性が大きく向上します。 また、再試行処理では単純な繰り返しだけでなく、待機時間を設けるバックオフ処理を導入することで、サーバー負荷軽減と成功率向上の両立が可能になります。安定したExcel自動化を実現するためには、エラー発生を前提とした設計が不可欠です。 API連携を活用した業務自動化、データ取得処理、外部システム統合などを行う際は、今回学んだOffice Scriptsエラーハンドリングの考え方を必ず取り入れてください。これにより、実務で使える堅牢なスクリプト設計ができるようになります。

再確認用サンプルプログラム

最後に、HTTPステータスコード確認と再試行処理、そして待機時間を組み合わせた実践的なサンプルをまとめて確認します。実務でのAPI通信エラー対策としてそのまま応用できる構成です。

function sleep(ms: number) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function fetchWithRetry(url: string, retries: number) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(url);

      if (!response.ok) {
        throw new Error("HTTPエラー: " + response.status);
      }

      return await response.json();
    } catch (error) {
      if (i === retries - 1) {
        throw error;
      }
      await sleep(1000);
    }
  }
}

async function main(workbook: ExcelScript.Workbook) {
  try {
    const data = await fetchWithRetry("https://example.com/api/data", 3);
    workbook.getActiveWorksheet().getRange("A1").setValue(data.message);
  } catch (error) {
    workbook.getActiveWorksheet().getRange("A1")
      .setValue("通信エラー発生 再試行後も失敗");
  }
}

このように、Office ScriptsでのAPI通信では、エラーハンドリング、HTTPステータスコード確認、再試行処理、待機時間設定という四つの要素を組み合わせることで、実用的で安定したExcel自動化が実現できます。 特に業務システム連携や外部データ取得処理では、通信失敗を想定した設計が必須です。API通信エラー対策を理解することは、Office Scriptsを実務レベルで活用するための重要なステップといえるでしょう。