【API】詳説 Google Classroom API（第３回 Guides：ガイド）

前回はトップページの見方について解説しました。
今回は、ガイドのページについて見ていきます。

Google Classroom API Guides

https://developers.google.com/classroom/guides/get-started

ガイドのトップページ

ページ左側の各カテゴリについて解説します。

・Get Started

    Google Classroomの概要、APIを利用できるドメイン、APIの概要、コースのエイリアス、リスト（コース名簿）の管理、課題の管理と学生の提出などが説明されています。

・Share to Classroom

    クラスルームの共有ボタンを作成できます。作成した共有ボタンをご自身のWebサイトに追加することで、ユーザーがコンテンツをクラスで共有し、サイトへのトラフィックを増やすことができます。

・Quickstart

    ガイドのページで最も大切な項目です。Go,Google Apps Script, Java、Pythonなど各言語ごとにAPIのセットアップおよびサンプルコードが記載されています。Google Apps Scriptのサンプルコードを実行すると、自身が所属している10コースの「コース名とコースID」が出力されます。

コース名とIDを取得するサンプルコード

・Using the API

    Quickstartの次に大切な項目といえます。以下のカテゴリごとに、サンプルコードが示されています。

    ①Manage Courses：コースを管理する

    コースは「M.スミスの第四期の数学」などのクラスを表します。各コースは、割り当てられた一意のIDによって識別されます。また、ページにある courses.create() メソッドを使用したサンプルコードを実行すると、新しいコースを作成できます。

コースを追加するサンプルコード（GAS）

    ②Manage Aliases：コースエイリアスを管理する

        Googleは、SIS（Student Information Systems：生徒情報システム）からコースを作成する場合やSISとコースをリンクする場合は常に、SISのコースIDをコースエイリアスとして使用することを推奨しています。SISやコースのエイリアスについては、別記事にて解説したいと思います。

    ③Manage Teachers and Students：教師と生徒を管理する

        ここではGASのサンプルコードが記載されていませんが、各メソッドの紹介があります。

    invitations.create() ：招待状を送信します。招待者の参加同意が必要です。

    teachers.create() ：ドメイン内に教師を直接追加できます（管理者のみ）。

    students.create() ：ドメイン内に生徒を直接追加できます（管理者のみ）。

    students.delete() ：指定したコースから学生を削除できます。

    courses.list() ：コースのリストを取得します。取得範囲は教師と学生で異なります。

    userProfiles.get() ：ユーザーID、メールアドレスなどの情報を取得します。

    ④Manage Classwork：授業課題を管理する

       Google Classroomは課題、テスト付き課題、質問等、５種類の授業方法があります。Classroom APIでは現在、３つ（課題、質問、資料）の操作が可能です。

        ここではGASのサンプルコードが記載されていませんが、この機能にアクセスするためのメソッドを解説しています。また、課題の割当管理については、studentSubmissionsで行います（詳細はリファレンスの回で解説します）。

    courses.courseWork.get() ：特定の課題や質問を取得します。

    courses.courseWork.list() ：全ての課題または質問を取得します。

    ⑤Manage Topics：トピックを管理する

        トピックとは、例えば課題や資料の類似度によって分類分けすることです。各トピックは、サーバーによって割り当てられた一意のIDによって識別されます。なお、GASのサンプルコードはありません。

    ⑥Managing Guardians：保護者を管理する

        保護者を設定すると、学生に与える課題等の情報をメールで受信できます。通常、学生ドメインのメンバーに属さない保護者は、保護者になるために自身のメールアドレスを使用して招待する必要があります。

       次の表は、ユーザーのタイプに応じて、保護者に対して実行できるアクションを示しています。

	保護者の情報		招待
	閲覧	変更	閲覧／変更	説明
学生	〇	×	×	学生自身の保証人のみ可。
教師	〇	〇	〇	クラスの生徒については、管理者がドメインコンソールで有効にしている場合に可。
管理者	〇	〇	〇	ドメイン内の全ての学生に対して可。
注：保護者のメールアドレスは、管理者のみがアクセス可能です。

    ⑦Authorizing Requests：リクエストを承認する

        OAuth2.0のリクエスト承認について説明しています。

・Best Practices

    Classroom APIのプッシュ通知、バッチリクエスト、APIエラーの処理、API処理性能の向上について説明しています。

・Tutorials

    「Share to Classroom」にて説明のあったクラスルームの共有ボタンとCourseWork APIの違いについて説明しています。主に、両者における課題の割り当てに関する内容になります。

以上、今回はGoogle Classroom APIのガイドのページについて見ていきました。次回は、いよいよReference：リファレンスのページについて、解説したいと思います。

【API】詳説 Google Classroom API（第２回：トップページの見方）

第１回では、ClassroomサービスとAPIのアクセス方法について紹介しました。今回は、Google Classroom APIトップページの見方を解説します。

なお、Google Classroom APIのページは全体に渡って日本語未対応なので、適宜ページを翻訳することもオススメです。

トップページ（HOME）にアクセスすると、Classroomの概要と説明動画が表示されます。

Google Classroom APIトップページ

トップページにはHome、「Guides：ガイド」、「Reference：リファレンス（参照）」、「Support：サポート」のタブがあり、それぞれアクセスできます。

またトップページの下部には、Google Classroom APIで出来ることがまとめられています。

ここから各ガイド、リファレンスにもアクセス可能

・Manage courses and aliases

新しいコースの作成や既存のコース内容を更新、コースにエイリアスを割り当てることができます。

・Manage course invitations
　教師や生徒宛にコースの招待状を作成し、送信できます。

・Manage teachers and students
　コースへの教師の割り当て、生徒の追加、コース名簿の作成、コースのリストを取得することなどが可能です。

・Manage coursework and submissions
　課題の作成、生徒の提出物を管理、コースにあるコンテンツの検索ができます。

・Subscribe to push notifications
　コース名簿に変更（教師や生徒の参加、除外）があった場合や、生徒から新しい提出物があった場合などの通知管理ができます。

・Add the Classroom share button
　教師や生徒がコンテンツを簡単に共有できる「クラスルームシェアボタン」をWebサイトに追加できます。

・Manage guardians
　保護者へのコースの招待状を送信することや、コースを閲覧可能な保護者のユーザー管理ができます。

リンク先のサンプルコードは全てGoogle Apps Scriptというわけではなく、例えば「Manage guardians：保護者の管理」はPythonのみサンプルコードが示されています。サンプルコードの紹介と見方については、「リファレンス：参照」の回で取り上げたいと思います。

次回は「Guides：ガイド」について取り上げます。

【API】詳説 Google Classroom API（第１回：アクセス方法）

 Google Classroom APIを使用したGASの紹介、Google Classroom の利用方法についてはあらゆるWebサイトで取り上げられています。Classroom.jpではGoogle Classroom API に焦点を置き、それ自体を取り上げ、１つひとつ解説していきます。

・Classroom API（Classroomサービスとは）

Google Classroom APIのトップ画面

Classroomサービスは、GASでClassroomを操作するためのクラスと、そのメンバーを提供するサービスです。Classroomサービスを使用することで、コース*固有の情報を取得したり、コースに課題を設定することや、参加者（メンバー）の操作ができます。

Classroomサービスで提供されている主なオブジェクトは、次のとおりです。

オブジェクト	説明
Classroom	Classroomサービスのトップレベルオブジェクト
courses	コースを操作する機能を提供する主なオブジェクト
courses.students	コースに参加している生徒の情報を操作するオブジェクト
invitations	コースへの招待に関する招待状を操作するオブジェクト

*Classroomの１クラスを指します。たとえばコース固有の「クラスコード」など、Googleはコースを「クラス」と呼称することがありますが、本連載ではGASのクラスと峻別するために「コース」といいます。

・Google Classroom APIへのアクセス方法

Google Classroom APIの直リンクはこちらです。また、Googleの公式からアクセスする方法は２通りあります。（この他にもアクセスする方法をご存知の方がいらっしゃれば情報をお寄せください）

1. 「Classroom API の概要」からアクセスする

Classroomヘルプ ＞ Classroomの拡張 ＞ Classroom API の概要 にあるClassroom API からアクセスできます。

APIの概要

2.「Google APIs Explorer」からアクセスする

Google APIs Explorerの［Type to filter APIs］に「Google Classroom」と入力し、検索した結果からアクセスできます。

Explorerの画面

次回はGoogle Classroom APIのページ構造について解説したいと思います。

【GAS】指定したコースの情報を取得する方法

先日、すべてのClassroomからクラスコードを一括でスプレッドシートに自動出力する方法 を取り上げました。
今回はすべてのコースではなく「指定した１つのコース情報を取得する方法」について、考えてみます。

Google Apps Scriptに以下のスクリプトをコピー＆ペーストしてください。

function getCourse() {
  const courseId = '312347346819'; //コースのIDを入力
  const course   = Classroom.Courses.get(courseId);
  console.log(course);
}

courseIdは、冒頭「すべてのClassroomからクラスコードを一括でスプレッドシートに自動出力する方法」を参考にしながら、オブジェクトのプロパティは「id」を指定してみてください。
実行ログの結果として、以下が表示されます。

これで、指定した１つのコース情報を出力することできました。

How can I export an one of course information?
After obtaining the course ID of Classroom, try running the script described above.
However, keep in mind about the courseId is differenet from classcode(enrollmentCode).

【GAS】スクリプトを実行して新しいコースを作成する方法

Google Apps Scriptで新しいコースを作成したい場合は、以下のスクリプトをコピー＆ペーストで実行してください。

function createCourse() {
  const course = {
    id: 'p:テストコース',
    name: 'テストコース',
    section: '前期',
    descriptionHeading: 'テストコースにようこそ！',
    description: 'こちらはGASで作成したテストコースです。',
    room: '503教室',
    ownerId: 'me',
    courseState: 'PROVISIONED'
  };

  const response = Classroom.Courses.create(course);
  console.log(`Course created:${course.id},${course.name}`);
}

以下、各プロパティの説明です。

 
  id  

Classroomによって割り当てられたこのコースの識別子です。対応するエイリアスを作成できます。たとえば、「p:微分積分学」でOKです。

 name 

コースの名前。たとえば「微分積分学」。必須項目です。

 section 

コースセクション、例えば「前期」や「後期」など。

 descriptionHeading 

説明のオプションの見出しです。たとえば、「微分積分学へようこそ」などです。

 description 

オプションの説明です。たとえば、「教科書、資料を使って授業を進めます」などです。

 room 

教室の場所を指します。

 ownerId 

コースの所有者の識別子です。①ユーザーの数値識別子、②ユーザーのメールアドレス、③"me"要求しているユーザーを示す文字列リテラルのいずれかになります。必須項目です。

 courseState 

コースの状態です。指定しない場合、デフォルトの状態はPROVISIONEDになります。

コースはオブジェクトから作成できますので、スプレッドシートに入力した情報をオブジェクトとして取得すれば一括で作成も可能です。
近日中に、Classroomコースを一括で作成する方法を紹介できればと思います。

-------------
For a description of each create field, please refer to the links below.
https://developers.google.com/classroom/reference/rest/v1/courses

The course can be created from an object, so if you get some data in the spreadsheet as an object, you can also create courses in bulk. Actually I plan on dealing with it within a few days in this blog.

【GAS】参加しているコースのクラスコードをスプレッドシートに自動で一括出力する方法

管理者がすべてのクラスコードを一括で自動出力したい場合や、自身が参加している全コースのクラスコードを一括出力したい場合には、以下のスクリプトを実行してください。
また、ログの出力はスプレッドシートに行いますので、スクリプトはスプレッドシートのコンテナバインドスクリプトとしてください。

function listCourses() {

  const response = Classroom.Courses.list();
  const courses = response.courses;

  const array = [['コース名','クラスコード','コースセクション']]; //※１
  const enrollmentCodes = [];
  for (let i = 0; i < courses.length; i++) {

    enrollmentCodes.push([courses[i].name, courses[i].enrollmentCode, courses[i].section]); //※２
  }

  const sheet = SpreadsheetApp.getActiveSheet();
  
  const midashirange = sheet.getRange(1, 1, array.length, array[0].length);
  midashirange.setValues(array);
  const range = sheet.getRange(2, 1, enrollmentCodes.length, enrollmentCodes[0].length);
  range.setValues(enrollmentCodes);

}

※１…スプレッドシートの１行目に出力されます。出力するメソッドにあわせて修正してください。
※２…このスクリプトでは、「コース名」、「クラスコード」、「コースセクション」を出力します。
上記以外の情報を出力したい場合には、Classroom APIのリファレンスを参照の上、適宜メソッドを修正してください。

出力結果のイメージは次のとおりです。

How to output about all classcodes belonging your domain?
For example, if you are an administrator of school or member of something classroom and want to automatically output all classroom codes, to do execute the above script.
That log will be output to the spreadsheet, so please use the spreadsheet's container-bound script.