はじめに
はじめまして。新入社員の桑野です。
配属当初、APIについて理解するためにBacklogAPIを使用して実際にAPIの受け渡しを実践してみたので、今回はその内容についてお伝えしたいと思います。
当初の私はAPIについてあまり良く分かっておらず、「API？なんかPOSTとかGETとかしてるやつ？」程度の認識しか持っていませんでした。
実際にAPIについてネットで調べてみると、次のように定義されています。
「アプリケーション同士が情報をやり取りするためのプログラミング上の窓口」
「リクエストを送信し、レスポンスを受け取る形式でデータ交換を行い、ソフトウェア開発の効率化や統合を容易にします。」
しかし、APIについては触れたことがなかったので、「窓口？データ交換？😥」といった感じで、いまいちよく分からないという印象でした。
そんな状態だった私が、これから自分が参画しているプロジェクトでAPI設計に携わるかもしれないという状況になったので、まずは課題形式で学ぶことになりました。
この記事では、実際に手を動かして学んだ内容をお伝えします。
課題：お天気情報をAPIで受け取り、Backlogの課題に今日のお天気情報を表示させてみよう⛅
今回は実際にイメージを掴むために、身近で使用しているプロジェクト管理ツールであるBacklogと、お天気情報を取得する※気象庁のAPIを使用し、受け取ったお天気情報をBacklogの課題として追加するという実装を行いました。
※気象庁のAPIとは、気象庁のWebサイトから取得できるjson形式の天気情報ですが、公式にAPIとして提供されているサービスではないため、無保証かつ、アップデート等により使用不可になる可能性があります。 基本的には「政府標準利用規約」に準拠して利用可能です。
今回使用したツールとAPI：
- Postman：必要なAPIの選定に使用
- 気象庁API：お天気情報を取得するために使用
- BacklogAPI：課題を追加するために使用
参考にしたサイト：
今回の課題の内容は、お天気情報を取得し、Backlogの課題として追加するというものなので、 HTTPリクエストメソッドのGETメソッドとPOSTメソッドを使用してAPIのやり取りを行います。
GET：指定したリソースの表現をリクエストする。主にデータの取得を行う。
POST：指定したリソースに実体を送信するために使用するメソッド。新しくデータを作成するときに使用される。
このように、GETがデータの取得、POSTがデータの作成の役割を持っている事が分かります。
つまり、気象庁APIから情報をGETし、BacklogAPIに取得した情報をPOSTするという流れになります。
その１：Postmanを使って必要なAPIを選定しよう📮
Postmanとは何かというと、WebAPIのテストを行うことができるAPI管理ツールです。
フォームに値を入れてどのような結果が返ってくるかや、認証情報が有効かなどのリクエストに対するレスポンスを簡単に返してくれます。日本語にも対応しているので非常に使いやすいツールだと感じました。
今回はこのPostmanを使用して必要となるAPIを選定し、どのような結果が返ってくるかを見ていきたいと思います。
①気象庁APIから必要なAPIを選定しよう⛅
今回は気象庁が公開しているjsonデータから天気情報を取得します。
まず、以下のURLから天気予報エリアの情報を取得し、取得したいエリアのIDを選定します。
https://www.jma.go.jp/bosai/common/const/area.json
今回は東京都の天気予報を表示させたいので、東京のIDを探します。
PostmanでGETリクエストを送信すると、以下のように東京都のIDを確認する事ができました。
東京のIDが130000であることが分かったので、以下のURLに東京のIDを追加します。
https://www.jma.go.jp/bosai/forecast/data/forecast/130000.json
先ほどと同様にPostmanでGETリクエストを送信すると、以下のように東京の天気情報を取得する事ができました。
"timeDefines": [
"2025-01-07T11:00:00+09:00",
"2025-01-08T00:00:00+09:00",
"2025-01-09T00:00:00+09:00"
],
"areas": [
{
"area": {
"name": "東京地方",
"code": "130010"
},
"weatherCodes": [
"201",
"101",
"101"
],
"weathers": [
"くもり 時々 晴れ 所により 夕方 まで 雨",
"晴れ 時々 くもり",
"晴れ 時々 くもり"
],
"winds": [
"南西の風 ２３区西部 では 南西の風 やや強く",
"南西の風 ２３区西部 では 南西の風 やや強く",
"南の風 やや強く 後 南西の風 やや強く"
],
"waves": [
"０．５メートル 後 １メートル",
"１メートル",
"１メートル"
]
},
このように、Postmanを使用することでレスポンスの詳細を簡単に確認する事ができました。
今回は一部の情報のみを使用し表示させたいので、ここから表示させたいパラメータを整理していきます。
今回は、「場所名」「日付」「天気」「天気概要」「降水確率」の情報を取得したいので、 先ほど取得した情報から必要なパラメーターを選定します。
必要なパラメーターは以下になります。
"timeSeries": [
{
#本日の日付を取得
"timeDefines": [
"2025-01-07T11:00:00+09:00",
"2025-01-08T00:00:00+09:00",
"2025-01-09T00:00:00+09:00"
],
"areas": [
{
#場所名を取得
"area": {
"name": "東京地方",
"code": "130010"
},
#お天気を取得
"weathers": [
"くもり 時々 晴れ 所により 夕方 まで 雨",
"晴れ 時々 くもり",
"晴れ 時々 くもり"
],
#12時の降水確率
"pops": [
"20",
"10",
"0",
"0",
"10",
"0"
]
また、お天気概要は以下のURLから取得する事ができます。
https://www.jma.go.jp/bosai/forecast/data/overview_forecast/130000.json
{
"publishingOffice": "気象庁",
"reportDatetime": "2025-01-07T10:35:00+09:00",
"targetArea": "東京都",
"headlineText": "",
#お天気概要を取得
"text": " 日本海には低気圧があって、東北東へ進んでいます。\n\n 東京地方は、曇りや晴れで、雨の降っている所があります。\n\n ７日は、冬型の気圧配置となりますが、気圧の谷の影響を受ける見込みです。このため、曇り時々晴れで、夕方まで雨の降る所があるでしょう。\n\n ８日は、引き続き冬型の気圧配置となりますが、気圧の谷の影響を受ける見込みです。このため、晴れ時々曇りとなるでしょう。\n\n【関東甲信地方】\n 関東甲信地方は、曇りや晴れで、雨や雪の降っている所があります。\n\n ７日は、冬型の気圧配置となりますが、気圧の谷や低気圧の影響を受けるでしょう。このため、曇りや晴れで、雨や雪が降り、長野県では雷を伴う所がある見込みです。\n\n ８日は、引き続き冬型の気圧配置となりますが、気圧の谷や寒気の影響を受けるでしょう。このため、晴れや曇りで、長野県と関東地方北部では雪が降り、長野県では雷を伴う所がある見込みです。\n\n 関東地方と伊豆諸島の海上では、７日から８日にかけて、うねりを伴いしけるでしょう。船舶は高波に警戒してください。"
}
このようにして、必要な気象庁APIのパラメータを選定できました。
続いては、BacklogAPIで必要なAPIを選定していきます。
②BacklogAPIから必要なAPIを選定しよう📝
BacklogAPIでは、「プロジェクトに課題を追加する」という操作を行います。
そのためには、まず課題を追加したいプロジェクトのプロジェクトIDを取得する必要があります。
プロジェクトの設定ページのURLを見ると、URLの末尾にプロジェクトIDが書いてあることが分かるので、そこからプロジェクトIDを把握します。
また、Backlogの個人設定ページからAPIキーを登録し取得する事ができます。
PostmanでAPIキーと、取得したプロジェクトIDを設定し、課題一覧をGETするリクエストを送信します。
すると以下のように、課題一覧のパラメーターを確認する事ができるので、必要なパラメーターを選択することができます。
{
"id": 45848535,
"projectId": 123456,
"issueKey": "sample",
"keyId": 123,
"issueType": {
"id": 123456,
"projectId": 123456,
"name": "タスク",
"color": "#7ea800",
"displayOrder": 0
},
"summary": "タイトル",
"description": "本文",
"resolution": null,
"priority": {
"id": 3,
"name": "中"
},
今回課題を追加するために必須で設定しなければいけない項目は、「プロジェクトID」「タイトル」「課題種別ID」「優先順位」「本文」になるので、以下のパラメーターを使用します。
#プロジェクトid
"ProjectId"：xxxxxx
#タイトル
"summary"：xxxxx
#課題種別id
"issueType"：｛
"id": xxxxxxx
｝
#優先順位
"priority"：｛
"Id"：xxxxxx
｝
#本文
"description"：xxxxxx
これで、BacklogAPIで必要なパラメーターも選定する事ができました。
その２：Backlogの課題を追加しよう📋
今回はPythonで課題追加APIを呼びだすコードを実装していきます。
手順としては、以下の流れになります。
①気象庁APIから情報を取得する
②①で取得した情報を使ってBacklogAPIの課題追加APIを呼び出す
①気象庁APIから情報を取得する
必要なパラメーターを定義し、取得した情報を代入したら、課題のタイトルとなる文章と本文となる文章を定義していきます。
import requests
import json
#APIのURL
url1 = "https://www.jma.go.jp/bosai/forecast/data/forecast/130000.json"
url2 = "https://www.jma.go.jp/bosai/forecast/data/overview_forecast/130000.json"
#データを取得
tenki_data = requests.get(url1).json()
tenki_detail = requests.get(url2).json()
#日付を取得
date = tenki_data[0]["timeSeries"][0]["timeDefines"][0]
#場所名を取得
area = tenki_data[0]["timeSeries"][0]["areas"][0]["area"]["name"]
#お天気を取得
weather = tenki_data[0]["timeSeries"][0]["areas"][0]["weathers"][0]
#降水確率を取得
rain_chance = tenki_data[0]["timeSeries"][1]["areas"][0]["pops"][0]
#天気概要を取得
desc = tenki_detail["text"]
#課題のタイトルを設定
title = f"本日({date})の{area}のお天気"
#課題の本文を設定
total_text = f"#本日のお天気\n本日の{area}のお天気は{weather}です。\n#降水確率\n降水確率は{rain_chance}％です。\n#詳細情報\n{desc}"
②BacklogAPIの課題追加APIを呼び出す
APIキーとスペース名を設定し、課題を追加する関数を定義します。 create_issue関数に、先ほど天気予報APIから取得し定義したタイトルと本文の値を渡し、必要な「project_id」、「issue_type_id」、「priority_id」を設定します。
API_KEY = 'yourAPIkey' //自分のBacklogから取得したAPIキーを記載する
BacklogUrl = 'https://your.space.name.jp' //Backlogのスペース名を記載する
def create_issue(project_id, summary, description, issue_type_id, priority_id):
BACKLOG_URL = BacklogUrl+'/api/v2/issues?apiKey='+API_KEY
payload = {
'projectId': project_id,
'summary': title,
'description': total_text,
'issueTypeId': issue_type_id,
'priorityId': priority_id
}
response = requests.post(BACKLOG_URL, json=payload) //**APIリクエストの送信**
if response.status_code == 201:
return response.json()
else:
print(f'Error: {response}')
return None
# 課題の作成例
new_issue = create_issue(
project_id=123456, //取得したプロジェクトIDを記述します
summary='summary', //設定した課題タイトル
description='description', //設定した説明文
issue_type_id=123456, //設定したい課題のタイプidを設定
priority_id=3 //設定したい優先度を記述
)
if new_issue:
print(f'Created issue: {new_issue["id"]}, {new_issue["summary"]}')
このようにコードを記述し、実行すると・・・
本日のお天気情報が課題として追加されました！🤗
このように、気象庁APIから天気情報をGETし、BacklogAPIを用いて取得した情報をPOSTすることで、APIの受け渡しを簡単に実装する事ができました。
まとめ
今回使用したBacklogAPIには、課題を追加するだけではなく課題一覧取得や、ユーザー追加などの複数の機能が提供されています。
BacklogAPIを使えば、プログラムを経由してBacklogに関わる様々な業務を自動化することも可能になります。
APIのメリットは簡単に取り扱う事ができ、なおかつプログラム作成の手間を短縮してくれるところだと思います。
天気情報のデータを１から自分で作成していたら、途方もない時間がかかってしまうと思いますが、APIがあれば短期間で制作が可能になるので、非常に便利でありがたい存在だなと、この課題を通してAPIの有用さを実感することとなりました。
また、今回の課題を通じて、理解を深めるためにはまず実際に手を動かして学ぶことが非常に有効であると感じました。
課題に取り組む中で、「APIとは何か？」という曖昧な状態から抜け出し、GET/POSTメソッドの役割やその目的についても具体的に理解することができました。
理論だけではなく、実際に手を動かすことで知識を実践的に身につける大切さを改めて感じています。
今後も引き続き実践を重ねる中で知識を深め、業務に活かしていきたいと思いました。
