Google Apps Scriptを利用してWeb APIを取得する方法を試してみた

こんにちは、コンサル部＠大阪オフィスのTodaです。

CloudOneやaqua、mackerelなどWebサービスには情報の取得、登録、変更、削除を外部ツールでおこなえるようにWeb APIが用意されている事が多くあります。
ここ最近私の方で業務最適化をするにあたりGoogleスプレッドシートとGoogle Apps Script（GAS）を利用して情報を集中管理する対応がありGASを利用したWeb APIの通信方法について学びましたので内容をまとめてみました。

Google Apps Script（GAS）とは？

Google Apps Script（GAS）とは、Googleが開発しているプログラミング言語です。
JavaScriptというWebブラウザ上で動作するプログラミング言語をベースに作成されています。

■ Google Apps Script
https://workspace.google.co.jp/intl/ja/products/apps-script/

Web APIについて

APIはプログラムからアプリケーションを操作することができる仕組みになり、Web APIはAPIをHTTP／HTTPSベースのやり取りで実現したものになります。
APIは提供元が開発したSDKやライブラリを利用しておこなうためプログラム言語の制限がありますが、Web APIはHTTP／HTTPSベースのためプログラム言語の制限がHTTP/HTTPS通信のリクエスト/レスポンス受け取りができれば対応が可能になります。
Web APIには「REST（Representational State Transfer）」と「SOAP（SimpleObject Access Protocol）」があります。

■ Web 2.0時代のWebServices ～SOAP/REST使い分けの指針
http://xmlconsortium.org/wg/web2.0/teigensho/4--REST-SOAP.html

GASを利用したHTTP/HTTPS通信プログラム

GASにはHTTP/HTTPS通信をおこなうようにUrlFetchAppクラスとレスポンス処理にHTTPResponseクラスが用意されています。
上記を利用して通信プログラムを作成します。

■ Class UrlFetchApp (GAS)
https://developers.google.com/apps-script/reference/url-fetch/url-fetch-app

■ Class HTTPResponse (GAS)
https://developers.google.com/apps-script/reference/url-fetch/http-response

GETの場合

fetch関数にURLを渡します。URLパラメータ(QueryString)を追加する場合は、記述をします。
情報が正常に取得できているかはgetResponseCodeにてステータスの番号を確認します。
情報の取得はgetContentTextにて情報取得ができます。

var requestUrl = '[http or httpsから始まるURL][(任意)URLパラメータ?query1=XXXX&query2=XXXXX]'
var response = UrlFetchApp.fetch(requestUrl)
var responseCode = response.getResponseCode()
var responseText = response.getContentText()

プログラム例

var requestUrl = 'https://example.com/get_config?id=123&no=123'
var response = UrlFetchApp.fetch(requestUrl)
var responseCode = response.getResponseCode()
var responseText = response.getContentText()

POSTの場合(通常)

POSTをおこなう場合はfetch関数の引数にオプションを追加してmethodをpostに変更して送信するパラメータを設定します。

// POSTのパラメータ
var requestPayload = {
    '[パラメータ名]': '[値]',
    '[パラメータ名]': '[値]'
}
// リクエストヘッダー
var requestOptions = {
    'method' : 'post',
    'payload' : requestPayload
}
var requestUrl = '[http or httpsから始まるURL]'
var response = UrlFetchApp.fetch(requestUrl, requestOptions)
var responseCode = response.getResponseCode()
var responseText = response.getContentText()

プログラム例

// POSTのパラメータ
var requestPayload = {
    'items': '100',
    'sort': 'asc'
}
// リクエストヘッダー
var requestOptions = {
    'method' : 'post',
    'payload' : requestPayload
}
var requestUrl = 'https://example.com/get_config'
var response = UrlFetchApp.fetch(requestUrl, requestOptions)
var responseCode = response.getResponseCode()
var responseText = response.getContentText()

POSTの場合(JSON形式)

APIによってはPOSTのパラメータをJSON形式で送信する場合があります。
JSON形式で送信する場合はヘッダー情報に application/json の記載とpostをJSON形式に変更する操作が必要です。

// POSTの値
var requestPayload = {
    '[パラメータ名]': '[値]',
    '[パラメータ名]': '[値]'
}
// リクエストヘッダー
var requestHeaders = {
    'Content-Type': 'application/json'
}
// リクエストオプション
var requestOptions = {
    'method' : 'post',
    'payload' : JSON.stringify(requestPayload),
    'headers' : requestHeaders
}
var requestUrl = '[http or httpsから始まるURL]'
var response = UrlFetchApp.fetch(requestUrl, requestOptions)
var responseCode = response.getResponseCode()
var responseText = response.getContentText()

PUT、DELETE、PATCHをおこなう場合

REST APIをご利用頂くときにPUT、DELETEというメソッドを利用する場合がございます。
PUT、DELETEにて通信をおこなう場合は、POSTをおこなう場合のプログラムをご利用頂きmethodの設定を変更します。

// PUTの場合
var requestOptions = {
    "method" : "put",
    "payload" : requestPayload
}

// DELETEの場合
var requestOptions = {
    "method" : "delete",
    "payload" : requestPayload
}

// PATCHの場合
var requestOptions = {
    "method" : "patch",
    "payload" : requestPayload
}

認証の対応について

Web APIをご利用頂く場合、ヘッダー情報にAPIキーを付与する場合やBASIC認証が必要な場合があります。
それぞれ設定方法を確認いたいます。
サンプルプログラム内でAPIキーやBASICの認証情報を記入しておりますが認証情報の管理はプロパティストアをご利用頂くことが推奨されます。

ヘッダー情報にAPIキー付与

ヘッダー情報にAPIキーを付与する場合の例になります.
APIキーのパラメータ名はシステム仕様により変わりますのでご利用頂くWeb APIの仕様書をご確認ください。
下記はGETの場合になります。

// リクエストヘッダー
var requestHeaders = {
    '[APIキーのパラメータ名]': '[APIキーなど認証文字列]' // ※プロパティストアから取得が推奨
}
// リクエストオプション
var requestOptions = {
    "method" : "get",
    "headers" : requestHeaders
}
var requestUrl = "[http or httpsから始まるURL][(任意)URLパラメータ?query1=XXXX&query2=XXXXX]"
var response = UrlFetchApp.fetch(requestUrl, requestOptions)
var responseCode = response.getResponseCode()
var responseText = response.getContentText()

BASIC認証

BASIC認証のユーザ、パスワードで認証をおこなう例になります。
下記はGETの場合になります。

// BASIC認証
var basic_user = '[BASIC認証ユーザ]'   // ※プロパティストアから取得が推奨
var basic_pass = '[BASIC認証パスワード]' // ※プロパティストアから取得が推奨
// リクエストヘッダー
var requestHeaders = {
    'Authorization': 'Basic ' + Utilities.base64Encode(basic_user + ":" + basic_pass)
}
// リクエストオプション
var requestOptions = {
    'method' : 'get',
    'headers' : requestHeaders
}
var requestUrl = "[http or httpsから始まるURL][(任意)URLパラメータ?query1=XXXX&query2=XXXXX]"
var response = UrlFetchApp.fetch(requestUrl, requestOptions)
var responseCode = response.getResponseCode()
var responseText = response.getContentText()

その他オプション

UrlFetchAppのオプションについてよく利用する物をピックアップしています。

// リクエストオプション
var requestOptions = {
    'method' : 'get',
    'muteHttpExceptions' : 'true',
    'validateHttpsCertificates' : 'false',
    'followRedirects' : 'false'
}
var requestUrl = "[http or httpsから始まるURL][(任意)URLパラメータ?query1=XXXX&query2=XXXXX]"
var response = UrlFetchApp.fetch(requestUrl, requestOptions)
var responseCode = response.getResponseCode()
var responseText = response.getContentText()

muteHttpExceptions

muteHttpExceptionsを有効化することで404などエラーの場合でもレスポンスを返すようになります。
true : 404などエラーが発生した場合でも処理を継続します。レスポンスコードを確認して処理を判定します。
false : 404などエラーが発生した場合、処理中でエラーとなります。

validateHttpsCertificates

SSL証明書のエラーを回避するかを設定します。
無効の場合は証明書エラーが発生した場合、処理中でエラーとなります。
true : 証明書エラーが発生した場合でも処理を継続します。
false : 証明書エラーが発生した場合、処理中でエラーとなります。

followRedirects

参照先にてリダイレクトが発生した場合、リダイレクト先を参照するかを設定します。
true : リダイレクトあり。
false : リダイレクトなし。

さいごに

今回はGoogle Apps Script（GAS）でWeb APIと通信をする場合に抑えておきたい方法についてご案内させていただきました。
少しでもお客様の作りたい物の参考になればと考えております。