⚠ 注意

このAPIを大幅に改良したバージョンを、別のレポジトリにて公開しています。 そのバージョンからKadai Store APIと名称が変更になりました。

🎒 TCJ2 Kadai Store API

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

(ツイートより画像を引用)

TCJ2 Kadai Store API は画像の左側の Google Compute Engine で提供されるAPIサーバーです。Google Compute Engine 環境以外でもご利用頂けます。

👨‍💻 API利用方法

課題一覧を取得 — GET /get

Parameters

Parameter
due	提出期限が過ぎているものを除く場合はfutureを入れてください。
timezone	Asia/Tokyoのみサポートしています。それ以外はUTCとなります。

Curl Example

$ curl https://example.com/get?due=future&timezone=Asia/Tokyo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

{
  "acquisition": "2020-04-01T12:34:56.000Z",
  "homeworks": [
    {
      "subject": "情報工学",
      "omitted": "情報",
      "name": "第1回課題",
      "id": "1234",
      "due": "2020-04-01T12:34:56.000Z"
    }
  ]
}

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

✔ 前提 (提供側)

• Node.js 13+
• npm
• Go

🛠 環境構築 (提供側)

1. WebサーバーとGUIアプリの実行環境を構築します。

デフォルトでApacheやNginxなどを用いてFastCGIとしてサーバーを開く設定になっています。 使用しない場合は、config.yamlのfcgi-serverをfalseにしてください。 Devoirs(v0.3.0以前)はCLIアプリですが、アカウントの認証時にGUIを用いるので、RDPやX転送などのGUIアプリを実行できる環境を構築してください。

2. Devoirs v0.3.0 のソースコードをインストールします。

実行ファイルを実行するときに出るログを使用するので、GUI版のDevoirs(v1.0.0以降)では動作しません。

3. このレポジトリをGOPATHの中にインストールします。

Releasesのから最新版のソースコードをダウンロードして展開してください。 また、GOPATH以外では正しく動作しない場合があります。

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

Keys
update-times	Devoirsを実行して情報を更新する時刻(分)
server-port	API提供サーバーのポート番号
fcgi-server	FastCGIとして動かすかどうか
get-limit	10分間にこのAPIにGETできる回数 (無制限なら-1を入れてください)
subjects/teams	その教科のTeamsのチーム名
subjects/syllabus	シラバスでの教科名
subjects/omitted	省略された教科名
discord/alarm	Discordでエラーを通知するかどうか
discord/admin-id	エラー通知するユーザーのID (alarmをtrueにした方のみ)
discord/message-format	メッセージフォーマット (alarmをtrueにした方のみ)
discord/command-prefix	ボットを呼び出すコマンドの接頭辞 (alarmをtrueにした方のみ)

5. token.yamlでトークンについての設定を行います。

Keys
allowed-tokens	当APIにアクセスを許可するトークン (ここで定めたものを利用者に教えてください)
discord-token	Discordボットのトークン (config.yamlのdiscordのalarmをtrueにした方のみ)

6. それぞれのファイルやフォルダを以下のディレクトリ管理下に配置します。

./
├─ devoirs/ ................................. devoirs v0.3.0
│  ├─ src ................................... devoirsのソースコード
│
└─ go/ ...................................... $GOPATH
   └─ kadai-store-api/ ...................... このレポジトリ
      ├─ main.go ............................ 主にWebアプリの処理
      ├─ config.yaml ........................ 基本的な設定
      ├─ token.yaml ......................... トークンの設定

├─ で終わってるものは、まだ続きがあることを示します。

7. devoirs/src/models/assignment.ts の内容を以下の内容に変更します。

import { ClassId } from './class';

export type AssignmentId = string;
export type DateTime = string;

export interface Assignment {
  id: AssignmentId;
  classId: ClassId;
  dueDateTime: DateTime;
  displayName: string;
  isCompleted: boolean;
}

export function compare(a: Assignment, b: Assignment): number {
  return a.dueDateTime.localeCompare(b.dueDateTime);
}

これをすることによって、課題の提出期限のデータを扱うことができるようになります。

8. devoirs/src/main.ts の20~26行目の次の構文を変更します。

for (const c of await client.getClasses()) {
	console.log(`-`, c.name);

	for (const a of await client.getAssignments(c.id)) {
		console.log('\t', a['isCompleted'] ? '✔' : '❗', a.displayName);
	}
}

を

for (const c of await client.getClasses()) {
	console.log(`-`, c.name);

	for (const a of await client.getAssignments(c.id)) {
		console.log("・" + a.displayName + "\t" + a.id + "\t" + a.dueDateTime);
	}
}

に書き換えます。 これをすることによって、課題のIDや提出期限も取得できるようになります。

9. GUI環境で devoirs/ でDevoirsを実行します。

$ npm install
$ npm start

Devoirsを初めて起動すると、学校で提供されているMicrosoftアカウントのログインを要求するためにGUIウィンドウが表示されます。 ログインした後は、自動認証が行われる1時間後までGUIが起動することは基本的にありません。

10. go/tcj2-kadai-store-api/ でgo buildを実行し、実行ファイルを生成します。

$ go build

tcj2-kadai-store-apiという名前で生成されます。Windowsだと拡張子がexeになります。

11. 生成された実行ファイルを実行します。

8080ポートでAPIが提供されます。

⌨️ Discordコマンド (オプションでDiscord関連の設定を行った方のみ)

DMやグループ、サーバーのどこでも実行することができます。

::kadai-store ping

サーバーが落ちていないかを確かめるコマンドです。 API管理者ユーザー以外でも実行できます。

::kadai-store version

TCJ2 Kadai Store APIのバージョンを確認するコマンドです。 API管理者ユーザー以外でも実行できます。

::kadai-store stop

サーバーを強制終了させるコマンドです。 API管理者ユーザーのみ実行可能です。