【徹底解説】初めてのAPI

この記事は初めてGASを使ってAPIを使いたいという人、APIを使ったことがあるが関連用語など理解が曖昧なままAPIを使用している人を対象に解説している。

対象者のプログラミングレベルはIF文, 配列、連想配列を理解していることを前提としている。

Gooラボのキーワード抽出APIを例に挙げて説明を進める。

■API（Application Programming Interface）とは何なのか？

ソフトウェアを外部から操作する手段のこと。
具体的にはソフトウェアからデータを取得したり、登録されている情報を更新したり、SNSなら自動で投稿を行ったりができる。

なぜ注目されているのか

一から開発しなくていい（コスト削減）
自分の作りたいプロダクトの機能を持つソフトウェアのAPIを使えばいちからプロダクトを作る必要がなくなる。

例）スプレッドシートで管理している予定のリマインドを行うプロダクトを作りたい場合
GoogleカレンダーAPIを使用すればスプレッドシートに記入している情報を自動でGoogleカレンダーに反映、Googleカレンダーのデフォルト機能で予定のリマインドを行うことが可能

プロダクト同士の連携が簡単にできる
既存のソフトウェアのいいところを組み合わせることができる。

例）API連携を行えば、すぐに返信したい、見逃したくないGmailが届いたときにSNSなどでリマインドを行える
LineのBot機能
https://note.com/learner/n/nb4045383f907

■GooラボのAPI使用例

Gooラボのキーワード抽出APIは入力した文書のキーワードを抽出するAPI

『桜の樹の下には』梶井基次郎
の文章を使用してキーワードを抽出してみた。

結果
※｛抽出されたキーワード＝入力された文章に対する関連度の高さを０～１で表したスコア。１に近い程関連が高い。｝

{桜の樹の下には=0.667}	
{安全剃刀=0.3178}
{音楽=0.3047}	
{いそぎんちゃく=0.2393}	
{維管束=0.2327}	
{水溜=0.1738}	
{変質者=0.128}	
{うぐいす=0.1149}	
{四十雀=0.1149}	
{日光=0.1149}

■テストスクリプト

function get_keyword(title,text) {

//誰（API操作行うサーバー）に対して支持を出すのかを定義
const endPoint = 'https://labs.goo.ne.jp/api/keyword';


//APIによる具体的な指示な指示内容を定義
const payload = {                                        
  "app_id": "自分で発行したAPI key",  　
  "title": title,                               
  "body": text
};


//具体的な指示内容（payload）をRest API で決められている指示形式に格納、定義
const options = {
  "contentType": ”application/json”,
  "method": "post",
  "payload": payload
};


//Gooラボのサーバーに対して実際に命令を行う
const response = UrlFetchApp.fetch(endPoint, options);


//取得したデータ（JSON）をGASで使用できる形に変更
const json    = JSON.parse(response.getContentText());
const keyword = json.keywords;
return keyword
}

スクリプト参考Note

以下はスクリプトの詳細説明ーーーーーーーーーー

■誰（API操作行うサーバー）に対して支持を出すのかを定義

const endPoint = 'https://labs.goo.ne.jp/api/keyword';

URL（endpoint）
インターネット上のリソース（資源）を特定するための形式的な記号の並び。（Wiki）

言い換えれば住所である。多くの場合リソースに値するものがWebページなのでWebページのリンクと理解している人が多い。

APIで使用するURLはそのAPIで利用できる機能（データの抽出・更新、通知など）を与えられたサーバーの住所を指している。
APIで使用するURLのことをエンドポイントと呼ぶ。

■APIによる具体的な指示な指示内容を定義

const payload = {
"app_id": "自分で発行したAPI key", 　
"title": title,
"body": text
};

payload
送信データのうち、メッセージ（指示本文）部分のこと
パラメータ（params）という事前にAPI提供側で用意された要素ごとに指示を行いpayloadを作成する。
今回のparamsについてはこちらページに説明あり。

API key
誰からの命令かを特定するための記号。これによって個人を特定し、APIの機能や指示しているデータへのアクセス権限があるかをサーバー側が判断する。
この情報が洩れるとほかの人でもデータが取得できたり、更新できたりするようになるので保管に細心の注意が必要。

■具体的な指示内容（payload）をRest API で決められている指示形式に格納、定義

const options = {
"contentType": ”application/json”,
"method": "post",
"payload": payload
};

method
これからどんな命令を行うかの宣言。
GET, POST, PUT, DELETEの4つのメソッドがよくつかわれる

GET： データの取得
例）Googleカレンダーから登録した予定の情報を取得する

POST：データの送信（新規に何か行う用）
例）LineやTwitterのBotで自動で通知（投稿）を行う

PUT：データの送信（既存データの更新）
例）Googleカレンダーの予定の時間やメンバーの変更

DELETE：データの削除
例）Googleカレンダーの予定の削除

※今回のGooのAPIでは新規データを送信してキーワード情報を抽出する機能を使用しているのでPOSTが使われる。

options内の要素はGoogleのfetch関数の説明で詳細を確認できる。

主要な要素

①contentType：やり取りするデータ型の指定。JSONの場合は”application/json”を格納。

②headers：API key など認証要素を格納。（Goo APIではpayloadに格納しているので必要ない）　　

③method：上記のGET, POST, PUT, DELETEを格納

④payload：使用するAPIのパラメータ要素を格納

■Gooラボのサーバーに対して実際に命令を行う

const response = UrlFetchApp.fetch(endPoint, options);

UrlFetchApp
Googleが提供しているRest API操作用のクラス（関数群）

公式ページ：https://developers.google.com/apps-script/reference/url-fetch/url-fetch-app

今回は fetch(url, params) という関数を使用している。

テストスクリプトに書いてあるように
urlにエンドポイント、paramsにoptionsを格納することで指示内容に基づいたAPI操作を行える。

■取得したデータ（JSON）をGASで使用できる形に変更

const json = JSON.parse(response.getContentText());
const keyword = json.keywords;

一般的にRest APIでデータのやり取りをする際はJSONというデータ形式が使用されている。今回もGooラボのサーバーから帰ってきたキーワード情報はJSON形式になっている。 JSON.parse関数でGASでJSON形式から連想配列にデータ型を変換している。

JSON
配列、連想配列などのオブジェクト情報を文字列化したもの。

例）const json = '{"result":true, "count":42}';
このサイトが JSON.parse()関数の挙動が分かりやすい。

感想

今まで何度もRest APIを利用してきた。
しかし基本的には一緒に乗っているテストスクリプトや使用方法を説明しているサイトなどをコピペしていたので、自分で一からスクリプトを書くことができなかった。
今回エンドポイントやJSONといった今まであやふやだった知識を調べ言語化できたことでテストスクリプトなどがないAPIにも手が出せるようになった。

おまけ：APIの種類（REST, SOAP）

オンラインデータ送信形式やデータ型によって種類がいくつか存在する。以下ではよく使われるRestとSOAPを紹介している。

REST（Representational State Transfer、RESTful API）
データの受け渡しはこういう風にしよう。というやり方をまとめたもの。（例：URLを使ってデータのやり取りを行いましょう）

詳細はこちらのQuitaが分かりやすい。

SOAP（Simple Object Access Protocol）
SOAPはプロトコルである。プロトコルとはコンピューター同士が通信をする際の手順や規約などの約束事。つまりSOAPによるAPIはデータ型・フォーマットなど指定されている形を使わないといけない。