Go to Qiita Advent Calendar 2024 Top
LoginSignup
0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 1 year has passed since last update.

@blacklions20(DaisuK K)

10分で体感するAPI

Posted at

背景

社内で営業やカスタマーサポートなどの非開発部門メンバーがAPIについての理解が難しそうだと感じていました。
特に、APIを提供している側と、APIを利用する側の役割の違いが混乱するようです。
APIを提供している社内プロダクトにおいて、利用するお客様側でAPIを呼び出す実装すべき内容について、プロダクト側で実装するものだと思い込んだ質問が来たり、というようなことが度々ありました。
API利用時の登場人物とその役割の違いをイメージするのが難しいのだと思います。

そこで、特にAPIを提供している側と、APIを利用する側の役割を理解するために社内向けに資料を作成しました。
その資料が、社内に限定するような内容でもなかったため、Qiitaにも投稿しておこうと考えました。

前提

APIについてぼんやりしたイメージは持っているのが前提です。

(参考サイト)こちらのサイトの言っていることは理解できるけど実感できない、くらいのレベルだと以下の内容の理解が早いかと。
https://wa3.i-3-i.info/word12428.html

ぼんやりを、もうちょっとはっきりさせたい人向けです。

世の中には公開されているAPIがたくさんありますが、今回はサンプルとして日本郵便の郵便番号検索APIを使います。
※この記事作成時点からAPIの内容が変わっている可能性もありますのでご注意ください。

郵便番号検索APIは、

  • このURLに対してhttps://zipcloud.ibsnet.co.jp/api/search
  • 7桁の郵便番号(郵便番号検索APIのリクエストパラメータのzipcode)を送ると
パラメータ名 項目名
zipcode 郵便番号
  • 都道府県名など、住所に関する情報(郵便番号検索APIのレスポンスフィールドのresults部分)等を返してくれます
フィールド名 項目名
zipcode 郵便番号
prefcode 都道府県コード
address1 都道府県名
address2 市区町村名
address3 町域名
kana1 都道府県名カナ
kana2 市区町村名カナ
kana3 町域名カナ

このAPIを、非開発部門が馴染みやすいようにGoogleスプレッドシートを用いて、GoogleAppScriptを使って利用する演習を行います。
GoogleAppScriptを使ったことが無くても進められるよう意識しています。
このような関係になります。
image.png

演習

この章の実施時間が10分のイメージです。
実際に、APIの利用やプログラミングをしたことが無い非開発部門メンバーにやってもらって、10分くらいだろうとタイトルを付けました(短時間で終わるというイメージを付けて、社内でこの資料を参照してもらうハードルを下げるため)。
※この記事作成時点から、GoogleスプレッドシートやGoogle Apps Scriptの仕様変更で以下の流れとは変わっている可能性もありますのでご注意ください。

1.雛形シートのコピー

郵便番号検索APIお試しスプレッドシート雛形
をコピーします。

  • メニューバーファイル→コピーを作成→ドキュメントをコピー→好きな名前を付けてコピーを作成

2.Apps Script を開く

コピーしたスプレッドシートにおいて、Apps Script 画面を開きます

  • メニューバー拡張機能→Apps Script

※好みで無題のプロジェクトを好きな名前に変更してください
image.png

3.APIが動くプログラムを貼り付け

今回は実感するだけなので、以下のプログラムを全てコピーし、AppsScriptのコード.jsの// ここに貼り付けに貼り付けます。

貼り付けるプログラム(クリックで開きます)

(上に空行が必要)

  // 郵便番号検索APIお試しシート を使うという宣言をする
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('郵便番号検索APIお試しシート');

  // 郵便番号検索APIお試しシートの　インプット：郵便番号　の中身を取得
  var postNo = String(sheet.getRange(1, 3).getValue());

  // 入力値が数字7桁かチェック
  if (postNo.match(/^[0-9]{7}$/)) {
    Browser.msgBox("郵便番号：" + postNo + "でAPIを実行します");
  // 入力値が999-9999かチェック
  } else if (postNo.match(/^[0-9]{3}-[0-9]{4}$/)) {
    Browser.msgBox("郵便番号：" + postNo + "でAPIを実行します");
  // 入力値が郵便番号の形式になっていない
  } else {
    Browser.msgBox("郵便番号の形式で入力してください");
    return;
  }

  try {
    var options = {
      'method': 'get',
      "muteHttpExceptions" : true
    }
    // 郵便番号検索APIを実行する
    var response = UrlFetchApp.fetch("https://zipcloud.ibsnet.co.jp/api/search?zipcode=" + postNo, options);

    // APIが正常に終了した場合の処理
    if(response.getResponseCode() == 200) {
      jsonData = JSON.parse(response);

      // シートの　郵便番号　にレスポンスの　郵便番号　をセット
      sheet.getRange(3, 3).setValue(jsonData["results"][0]["zipcode"]);
      // シートの　都道府県コード　にレスポンスの　都道府県コード　をセット
      sheet.getRange(4, 3).setValue(jsonData["results"][0]["prefcode"]);
      // シートの　都道府県名　にレスポンスの　都道府県名　をセット
      sheet.getRange(5, 3).setValue(jsonData["results"][0]["address1"]);
      // シートの　市区町村名	　にレスポンスの　市区町村名	　をセット
      sheet.getRange(6, 3).setValue(jsonData["results"][0]["address2"]);
      // シートの　町域名　にレスポンスの　町域名　をセット
      sheet.getRange(7, 3).setValue(jsonData["results"][0]["address3"]);
      // シートの　都道府県名カナ	　にレスポンスの　都道府県名カナ	　をセット
      sheet.getRange(8, 3).setValue(jsonData["results"][0]["kana1"]);
      // シートの　市区町村名カナ	　にレスポンスの　市区町村名カナ	　をセット
      sheet.getRange(9, 3).setValue(jsonData["results"][0]["kana2"]);
      // シートの　町域名カナ	　にレスポンスの　町域名カナ	　をセット
      sheet.getRange(10, 3).setValue(jsonData["results"][0]["kana3"]);
    // APIがエラーだった場合の処理
    } else {
      throw new Error(response.getResponseCode());
    }
  // APIがエラーだった場合の処理
  } catch(ex) {
    Browser.msgBox("fetch で失敗しました。:" + ex);
  }

貼り付けたら、保存します。
※保存方法は通常通り(WindowsならCtrl + s、MacならCommand + s、もしくはメニューバーのフロッピーのボタン、等)

4.実行準備

実行ボタンに先ほど保存したApps Scriptを紐付けます。

  • 実行ボタンを右クリック→点3つの部分をクリック→スクリプトを割り当て→myFunctionを入力してOKを押します。
    image.png
    image.png

5.入力

インプットの郵便番号に、半角7桁数字もしくは郵便番号の形式で調べたい郵便番号を入力してください。
それ以外の形式の場合は、ボタンを押した時にエラーメッセージが表示されます。
image.png

6.実行

①実行ボタンを押します。
image.png

(②〜④)最初に実行ボタンを押した時は、AppsScriptを実行するための権限の許可を求めらると思いますので、許可してください。

②続行
image.png

③自分のアカウントを選択
image.png

④' ※これが表示された場合は詳細、表示されない場合は④へ
image.png
（安全ではないページ）に移動
image.png

④許可
image.png

⑤OK
※これはプログラムで確認を求めるようにしたので、毎回出てきます。
image.png

7.結果の確認

アウトプットの欄に、インプットに入れた郵便番号の情報が出てくるのを確認できたら、完了です。
image.png

演習内容の解説

演習を通して、出てきた情報を紐付けてみます。

スプレッドシート → 郵便番号検索API の流れは、
　郵便番号検索APIの7桁の郵便番号のリクエストパラメータはスプレッドシートのインプットから取得
　　↓
　郵便番号検索APIのURLにくっつける
　　↓
　APIを実行(日本郵便のサーバに対して送信)
ということをしています。
image.png

郵便番号検索APIが返してくれた結果(レスポンス)は、スプレッドシートのアウトプットに入れています。
image.png

余談

実はブラウザのURL欄にこんな感じでzipcode付きで入力しても、
https://zipcloud.ibsnet.co.jp/api/search?zipcode=2200012
結果を返してくれます。
image.png

最後に

以上の演習と合わせて、

Webシステムを例とすると、人間がWebブラウザを通して、システムを使います。
しかし、人間じゃなく、とあるシステムが別のシステムを使いたい場合があります。
APIは、人間がWebブラウザを介するように、自身以外のシステムがAPIを介してシステムを使えるようにしたものです。(APIはApplication Programming Interfaceなので、何となくしっくり来るんじゃないでしょうか)

という説明をしています。

実際に手を動かしてみることで、そのようなイメージを具体化するのに役立てばと考えました。
自分自身においても、実際にAPIを利用するプログラムの実装をするまでは、ぼんやりとしか理解できていませんでした。

この資料を作成以降、社内でのAPIに関する質問の解像度が上がったような気がしなくもないので、いちおう作って良かったんじゃないかと思っています。

0
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?