UrlFetchAppで外部APIを呼び出す方法｜GET/POSTの基本

GASから外部APIを呼ぶときは、URLが合っているだけでは足りません。読み取るGETと、データを送るPOSTでは指定する内容が違い、応答にエラーが含まれる場合もあります。UrlFetchApp のリクエストと、返ってきた結果を分けて見ていきます。

GETでページを読み取る

次は公開ページを1回取得し、HTTPステータスと本文の先頭をログへ出す例です。APIではなくHTMLページを読むため、応答をJSONとして解釈する処理は入れていません。

function fetchExamplePage() {
  const response = UrlFetchApp.fetch('https://example.com/', {
    method: 'get',
    muteHttpExceptions: true
  });
  console.log(response.getResponseCode());
  console.log(response.getContentText().slice(0, 120));
}

muteHttpExceptions: true は、失敗を成功に変える指定ではありません。HTTPエラーの応答も受け取り、ステータスや内容を確認するための指定です。接続やその他の問題まで、すべて例外なしで返るという意味でもありません。

POSTのJSONを送信前に組み立てる

JSONを受け取るAPIでは、contentType と、JSON文字列にした payload を指定します。次の例は getRequest() でリクエストを組み立てるだけで、外部への送信はしません。

function inspectJsonRequest() {
  const request = UrlFetchApp.getRequest(
    'https://api.example.invalid/items',
    {
      method: 'post',
      contentType: 'application/json',
      payload: JSON.stringify({ name: '練習用', count: 1 })
    }
  );
  console.log(request.method);
  console.log(request.payload);
}

実際に送る場合は、自分が利用を許可されたAPIのURLと仕様へ合わせます。POSTによってレコード作成や通知が行われるAPIもあるので、実行のたびに何が増えるかを先に確認してください。認証用のトークンをログへ出す例にはしない方が扱いやすくなります。

レスポンスをJSONとして読む条件

getContentText() が返すのは本文の文字列です。JSONを返すAPIと分かっている場合に JSON.parse() を使います。認証エラーのHTMLや空の本文に対して解析すると、JSONの解析エラーになり、元のHTTPエラーを見失うことがあります。

まず応答コードを見て、APIの成功条件に合うかを確かめます。そのうえで本文を解析し、必要な項目があるかを確認します。ステータスが成功でも、期待したデータが返ったかは別に確かめてください。

失敗したときの確認順

URLとHTTPメソッド、認証情報の付け方、送信形式をAPIの説明と照合します。403なら権限や利用条件、429なら呼び出し頻度などを確認し、同じリクエストを連打して解決しようとしないでください。

APIキーの保存にはScript Propertiesのような設定管理を検討できます。ただし、保存場所を変えることと、プロジェクトへのアクセス権を制限することは別です。

設定項目と getRequest() の仕様はUrlFetchAppの公式リファレンスで確認できます。GASの基本と、AI APIキーの扱い方も、接続先を増やす前の整理に使えます。