🎒 Kadai Store API

devoirs-core を使用して Microsoft Teams(Microsoft 365 Education) で出されている課題の情報を取得し、APIを提供します。 この場をお借りして devoirs-core、Devoirs の開発に関わった方々に感謝申し上げます。

⚠ 注意

Kadai Store API は TCJ2 Kadai Store API が大幅改良され、改名されたものです。前のバージョンのAPIを使用する場合は、TCJ2 Kadai Store APIのレポジトリを参照してください。

👨‍💻 API利用方法 (クライアント)

課題一覧を取得 — GET /get

Parameters (Option)

Parameter
due	提出期限が過ぎているものを除く場合は、futureを入れてください。
timezone	予め設定されているタイムゾーンから、タイムゾーンを指定して取得することができます。それ以外はUTCとなります。
subject	予め設定されている教科IDから、教科を指定して取得することができます。複数ある場合はコンマで区切ってください。

タイムゾーンや教科IDは、api-config.yamlで指定できます。API提供者は、クライアントにそれらをお伝えください。

Curl Example

$ curl http://example.com/get?due=future&timezone=Asia/Tokyo&subject=math4,circuit2,ai-basic \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

{
  "acquisition": "2020-04-01T12:34:56+09:00",
  "homeworks": [
    {
      "course": "[099] 2年生 AI基礎",
      "subject": "AI基礎",
      "subject_id": "ai-basic",
      "name": "第7回課題 (Deep Q Network)",
      "id": "abcdefgh-0123-4567-8910-ijklmnopqrst",
      "due": "2020-04-13T23:59:59+09:00"
    }
  ]
}

acquisition はMS Teamsから取得した時刻です。

教科ID一覧を取得 — GET /subjects

Curl Example

$ curl http://example.com/subjects \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

{
  "subjects": [
    "hr",
    "japanese",
    "math3",
    "physics-b",
    "law2",
    "le1",
    "eikaiwa1",
    "algorithm",
    "web",
    "circuit",
    "dog",
    "cat"
  ]
}

✔ 前提 (サーバー)

• Node.js 11.7.0+ (Recommend: 14.0.0+)

🛠 環境構築 (サーバー)

1. Node.js を実行できる環境を用意します。

Node.js のコードを実行・運用できる環境（サーバーやホスティングなど）を用意してください。

2. Kadai Store API をインストールします。

Releasesから最新版のソースコードをダウンロードして、展開してください。

3. インストールしたディレクトリに移動します。

移動してください。

4. api-config.yaml で基本的な設定を行います。

Keys
update_duration	MS Teamsから課題情報を取得する、時間の間隔(分)
update_offtimes	MS Teamsから課題情報を取得しない、時(hour)
get_limit	1つのトークンが、get_limit_durationで指定する期間内に、このAPI(/get)にGETできる回数
get_limit_duration	get_limitの期間(分)
tmp-dir	一時的なデータを保管するディレクトリ
timezones	UTC(協定世界時)以外に扱うタイムゾーン
subjects	取得する課題が格納されているチーム名、教科名、教科ID
allow-tokens	APIにアクセスを許可するトークン (ここで定めてください)

5. 環境変数を設定します。

Variables
PORT	サーバーが使用するポート番号 (HerokuやGAE等のホスティングサービスを使用する場合は設定不要です)
MICROSOFT_EMAIL	課題情報を取得するMS Teamsのアカウントのメールアドレス
MICROSOFT_PASSWORD	課題情報を取得するMS Teamsのアカウントのパスワード

6. JavaScriptにコンパイル

npm installを実行して、必要なモジュールをインストールしてください。(少々時間がかかります)

次に、npm run buildを実行して、src内のTypeScriptのコードをJavaScriptにコンパイルし、実行できる状態にしましょう。

7. (HerokuやGAE等のホスティングサービスを使用する場合) デプロイします。

デプロイに必要なファイルを追加して、デプロイしてください。

Google App Engine を使用する際の例

🔎 デブロイが失敗する場合

Chromium(Puppeteer)を使用しているので、ホスティングサービスによっては、デプロイが失敗することがあります。想定される理由として、メモリ不足や、必要なアドオンが導入されていないことが考えられます。

最小メモリ	512MB
推奨メモリ	1024MB

7. (ホスティングサービスを使用しない場合) 実行します。

npm startを実行して、サーバーを起動します。

ts-nodeを使用してTypeScriptを直接実行できる方は、npm run devでもサーバーを起動することができます。

8. アクセスできるかを確かめる

アクセスしてみてください。Kadai Store API - v1.0.2と表示されたら成功です。