> Blog > 技術 > サスケ Works｜外部APIから情報取得する方法

小原 達也/ 2023年 12月 13日/ 技術

こんにちは！小原です。

外部APIを使えるようになると、サスケWorksでできることが一気に広がります。

実際、NorthTorchでもサスケWorksで作った蔵書管理アプリに「国会図書館API」を使ってISBNから書籍情報を取得しています。
>> 参考：社内の蔵書管理にサスケWorksを使い始めました

書籍情報のほかにも、世の中には様々なAPIがあります。

  • 天気予報
  • 翻訳
  • 株価情報の取得
  • Googleの商品情報を取得

これらの機能をイチから作ろうとすると膨大な開発時間が必要です。
一方で、APIなら基本的に「ただ呼び出すだけ」で機能追加ができます。
※受け取ったデータの加工などは別途必要

本記事ではサスケWorksでAPIを使った機能追加をする方法をご紹介します。

サスケWorksのアプリ制作を始めたばかりの方でもご理解いただけるよう、「APIとは何か？」といった基本的な内容から解説します。

※1. 本カスタマイズにはサスケWorksプレミアムプランへの加入が必要です。
※2. 基礎的なJavaScriptの知識が必要です。

APIとはどのようなものか？

厳密な定義は抜きにして、APIについてのざっくりとしたイメージからお伝えします。

APIは自動販売機と似ている

一言で表現すると「API = ほしい情報を簡単に取得できる装置」のことです。

APIを身近なもので例えるなら「自動販売機」が近いです。

自動販売機は、ボタンを押すとほしい飲み物が出てきます。

APIもこれと似ています。
つまり「ほしい情報を要求すると、そのほしい情報が返ってくる」という動きをします。

ただしAPIには自動販売機のように物理的なボタンはありません。
そこで、あらかじめ決められたURLにアクセスすることで情報が取得できるようになっています。

この「あらかじめ決められたURL」が、「自動販売機のボタン」にあたるとイメージいただくと分かりやすいかもしれません。

APIの種類

そこで気になるのが、APIの種類です。

冒頭でも触れましたが、例えば以下のようなものがあります。

  • 書籍情報取得
  • 天気予報
  • 翻訳
  • 株価情報の取得
  • Googleの商品情報を取得

もちろん上記は一例であって、ほかにもたくさんのAPIが存在しています。

例えば無料APIでお探しであれば、以下のページは詳しいです。
>> 今すぐ使える無料WebAPIまとめ【2023年最新版】

ぜひ、Google検索などで「ほしい機能名 + API」で検索してみてください。

【重要】API利用時の注意点

以下の点に注意する必要があります。

  1. 利用規約を読む
  2. 過剰なアクセスはしない

1.利用規約を読む

利用規約にはAPIを使うときの「決まりごと」が書かれています。

うっかり禁止事項に触れないためにも、必ず利用規約に目を通すようにしてください。

2.過剰なアクセスはしない

プログラムは、API提供元のサーバーで動作しています。
そのためAPIに対して短時間で過剰にアクセスするとAPI側に負荷がかかってしまうので、過剰なアクセスは避けなければなりません。

どの程度が「過剰」かについては利用規約などに載っている場合もあります。
例えば本記事で取り上げる天気予報APIは、注意事項として以下の記載があります。

あまり強いサーバーではないので、API に連続してアクセスする場合は最低でも 0.5 秒以上間隔を空けてから行ってください。
短時間に連続してアクセスした場合、この API だけでなく気象庁 HP にも負荷をかけてしまうことになるため、絶対にやめてください。
出典：https://weather.tsukumijima.net/

このAPIでは、0.5秒以上の間隔をあけてアクセスするように制御する必要があります。

判断に迷う場合には、API提供元に連絡を取ってみることも有効です。

サスケWorksへの実装方法

ここからはサスケWorksに対してAPI連携させる方法をお伝えします。
サスケWorksの「カスタムコード」という機能を使って、JavaScriptコードを追加していきます。

ここでは具体例として、サスケWorksで「天気予報の情報」を取得する機能を加えてみます。
利用させていただいたAPIはこちらです。
>> 天気予報 API（livedoor 天気互換）

JavaScriptコードを追加する

まずはアプリの右上のスパナマークをクリックします。

サイドバーから「カスタムコード」を選択します。

右上の「新規登録」ボタンをクリックして、設定画面に進みます。

続いての設定は、以下を参考にしてみてください。

  • 状態: 公開
  • 名称: 天気予報取得（分かりやすいものでOKです）
  • 適用画面: レコード一覧画面
  • コード種別: JavaScript

今回はレコード一覧画面で天気予報を表示させるため、「適用画面: レコード一覧画面」としました。
別のページにAPIの結果を表示させたい場合には、適宜変更してください。

入力が終わったら「保存」ボタンをクリックして設定を終了します。

次に以下の画面に遷移するので、「ソースコードの入力」をクリックして先に進みましょう。

黒い画面が表示されたら、すでに書かれているコードを削除してまっさらな状態にします。

そのうえで以下のコードをコピーして、先ほどの画面に貼り付けてみてください。

/*!
 * SaaskeSDK
 * Copyright (c) North Torch Co.,ltd. 2023
 * Released under the MIT License.
 * ライセンスの全文は以下をご参照ください
 * LICENSE: https://github.com/northtorch/saaske-sdk/blob/main/LICENSE.md
 * README: https://github.com/northtorch/saaske-sdk/blob/main/readme.md
*/

async function fetchData(url, method) {
    try {
        const response = await fetch(url, { method: method });
        // レスポンスが異常
        if (!response.ok) {
            throw new Error(`HTTP error: ${response.status}`);
        }
        // レスポンスが正常
        return await response.json();
    } catch (error) {
        // エラー
        console.error(`Fetch error: ${error}`);
        return null;
    };
};

async function main(url, method) {
    // APIから受け取ったデータを格納
    const data = await fetchData(url, method);
    if (data) {
        // データをすべてアラートとして表示
        alert(JSON.stringify(data));
    } else {
        console.log('データの取得に失敗しました');
    };
};

const url = `https://weather.tsukumijima.net/api/forecast/city/016010`;
const method = 'GET';

main(url, method);

少しわかりにくいですが、以下の部分が取得した天気予報の内容を表示させている部分になります。

alert(JSON.stringify(data));

サスケWorksの設定はこれで完了です。

アクセス先のURLを探す方法

ところで、先ほどのコードでは以下のURLにアクセスしました。

`https://weather.tsukumijima.net/api/forecast/city/016010`;

このURLは、札幌市の天気予報を返してくれるURLです。
つまり、ここにアクセスすると札幌市の天気予報情報が手に入ります。

では、このURLはどのように知ることができるのでしょうか？

URL特定までの流れは次の通りです。

  1. ベースとなるURLを調べる
  2. ベースURLで不十分なら、さらに必要な情報を調べる

今回の天気予報APIを例にして解説します。

1.ベースとなるURLを調べる

ベースとなるURLは、API提供元サイトの「リクエストパラメータ」という場所に書いてありました。

以下、該当部分の引用です。

JSON データをリクエストする際のベースとなる URL は以下になります。
https://weather.tsukumijima.net/api/forecast
(出典) 天気予報API: リクエストパラメータ

つまり、ベースとなるURLは以下であることが分かりました。

https://weather.tsukumijima.net/api/forecast

ただし、「パラメータを加え」とあることから、単に上のURLにアクセスすればよいだけではないことが分かります。

2.ベースURLで不十分なら、さらに必要な情報を調べる

先ほどのページを少し読み進めると、ベースURLの後に続けて天気予報を取得する地域のコードを付け足す必要があることが分かります。

（例）「福岡県・久留米の天気」を取得する場合
下記 URL にアクセスして JSON データを取得します。
http:// でのアクセスも可能です。
基本 URL + 久留米の ID (400040)
https://weather.tsukumijima.net/api/forecast/city/400040
クエリで取得することもできます。
https://weather.tsukumijima.net/api/forecast?city=400040
(出典) 天気予報API: リクエストパラメータ

つまり、「どの地域の天気予報を取得するか？」という補足情報が必要ということになりそうです。
例えば福岡県・久留米市の情報が欲しい場合は、/city/400040 をベースとなるURLに付け足します。

その他の都市のデータを取得したい場合には、自分でIDを調べに行く必要がありそうです。
IDは以下のページを参照するよう記載がありましたので、見に行ってみましょう。
>> 都市別ID一覧

今回は「札幌市」を探してみます。

ありました！
以下、内容をテキストで再掲します。

<city title="札幌" id="016010" source="http://weather.livedoor.com/forecast/rss/area/016010.xml"/>

札幌の id は "016010" なので、/city/016010 をベースURLに加えればよいことになります。

最終的なURLは以下となります。

https://weather.tsukumijima.net/api/forecast/city/016010

ということは、このURLにアクセスすることで札幌市の天気予報を取得できることになります。

では、Chromeなどのブラウザからアクセスして結果を見に行ってみましょう。
結果は以下のようになります。

テキストだけが表示されるので分かりづらいですが、どうやら札幌の天気予報が表示できていることが分かります。

これでブラウザから情報が取得できていることは確認できました。

動作確認

続いてサスケWorks上で動作を確認してみましょう。

サスケWorksのレコード一覧画面を表示すると、以下のようなアラートメッセージが表示されるようになります。

メッセージを一部抜粋すると、以下のような形です。

{
    "publicTime": "2023-12-07T05:00:00+09:00",
    "publicTimeFormatted": "2023/12/07 05:00:00",
    "publishingOffice": "札幌管区気象台",
    "title": "北海道 札幌 の天気",
    "link": "https://www.jma.go.jp/bosai/forecast/#area_type=offices&area_code=016000",
    "description": {
        "publicTime": "2023-12-07T10:35:00+09:00",
        "publicTimeFormatted": "2023/12/07 10:35:00",
        "headlineText": "",
        "bodyText": "　北海道付近は、７日は日本海を低気圧が発達しながら北東へ進み...",
        "text": "　北海道付近は、７日は日本海を低気圧が発達しながら北東へ進み、..."
    }
}

先ほどブラウザで確認したものと同じものが取得できています！

データのほしい部分だけを取得する方法

先ほどアラートで出力された内容では、色々な情報がごった煮になっているので扱いにくいです。
そのため、ほしい情報だけを抽出していきます。

基本的には、ほしい情報の項目名をドットで繋げていくことで絞り込みます。

1. publicTime を取得したい場合

例えば publicTime を取得したい場合は、以下になります。

alert(data.publicTime)

"data" の中に先ほどのすべてのデータが入っているので、これに対して ".publicTime" という形でドットで繋げて絞り込みます。

出力結果は以下になりました。

さきほどの publicTime の部分だけが抽出できていることが分かります。

2. description > bodyText を取得したい場合

description の中の bodyText が欲しい場合は、以下になります。

alert(data.description.bodyText)

階層構造になっているので、二か所をドットでつなぐことにご注意ください。

結果は以下のようになります。

bodyText の部分だけが取得できました。

要素の取り出し方

ここからは補足情報として、以下をお伝えします。

  • ドット記法以外の方法
  • データに配列が含まれる場合の対処法

ブラケット記法

ドット記法のほかに、ブラケット記法というデータの取り出し方があります。

ドット記法との違いを、以下に示します。

// ドット記法
alert(data.description.bodyText)

// ブラケット記法
alert(data["description"]["bodyText"])

最初の data はそのまま書くのは共通です。
続く絞り込みたい項目名をブラケット [] とクオテーション記号 '' で囲んで表現します。

取得結果は同じなので、使いやすい方を採用してみてください。

配列を含むデータの取り出し方

APIアクセスした結果、以下のような形式で返ってくる場合があります。
以下では、先ほどと違って波括弧 {} 以外に、角括弧 [] が含まれています。

{
    "response": [
        {
            "question1": "answer1",
            "question2": "answer2"  // これを取得したい場合
        }
    ]
}

この角括弧 [] は配列を表しています。

まずは結論として、answer2 という文字列を取得する場合のコードを示します。

// ブラケット記法
alert(data["response"][0]["question2"])

// ドット記法
alert(data.response[0].question2)

配列が混ざる場合には、ブラケット記法で書いた方が見やすいかもしれません。

ところで [0] は、配列の中の順番を表しています。

プログラムの世界では数字は 0 から始まるのが原則です。
そのため、最初の要素を指定する場合には「配列の 0 番目の要素」という意味で [0] と表現します。

例えば、次のようなデータがあるとします。

{
    "response": [
        {
            "question1": "answer1",
            "question2": "answer2"
        },
        {
            "question1": "answer3",
            "question2": "answer4"
        },
    ]
}

角括弧 [] の中に波括弧 {} が2つあるので、配列の中に2つの要素があるということになります。

先ほど、プログラムの世界では0から始まるのが原則とお伝えしました。

そのため、最初の要素を取得するには [0] とします。
一方で、二番目の要素を取得するなら [1] とすることになります。

先ほどのコードを例にとって、データの取得方法を以下に例示します。

// 最初の要素から取得する場合
alert(data["response"][0]["question2"])

// 二番目の要素から取得する場合
alert(data["response"][1]["question2"])

一つ目のコードでは、配列の1番目を見に行っているので、"answer2" という文字列が取得できます。
一方で二つ目のコードでは、配列の2番目の要素である "answer4" という文字列が取得できることになります。

まとめ

以上で、基本的なAPIからの情報取得はできると思います。

取得したデータは加工するなどして、アプリ開発にお役立ていただければと思います。

本ブログでは、サスケWorksのカスタマイズ系記事も順次アップしております。

NorthTorch - サスケWorks 関連記事

ぜひ、別記事の方もご覧ください！

ソースコード公開中

本記事で紹介したコードは、GitHubからもご覧いただけます。

https://github.com/northtorch/saaske-sdk/blob/main/fetchApi.js