【GAS】GoogleAppsScriptを用いてClassroomに生徒を招待する方法(Invitations.create)

こんにちは！GoogleAppsScriptを使った業務効率化に夢中の初心者プログラマー、太郎です。

今日はGoogleAppsScript(GAS)を用いてClassroomに生徒を招待するプログラムについて書いていきたいと思います。

初心者向けですが、javascriptの基本的なルールは押さえておいた方が理解はしやすいと思いますので、まだの方はProgateでサクッとjavascriptの文法を学習してみてください。

また、初心者が手当たり次第にコードを書いてみて詰まったところやその時の心の声などもつらつらと書いています。やり方のみさっと知りたい方は、最後のまとめを参照ください。

また、ReferenceError: Classroom is not definedとエラーが出てしまった方は、こちらの記事を参考にしてみてください。
では、早速トライしていきましょう！

招待したいクラスルームのIDを名前から取得

こちらは今自分所属しているクラスルームです。

今回は、一番左の「生徒を招待するクラス」に招待していきたいと思います。
GoogleAppsScript(GAS)を用いてClassroomに所属している生徒の一覧を取得する方法の記事でも書きましたが、まずは招待したいクラスルームのIDを取得しましょう。コードはこのように書きます。詳しい解説が知りたければ、先のリンクをご参照ください。

function inviteStudent() {
  //所属しているクラスの一覧を配列で取得
  var myCourses = Classroom.Courses.list().courses;

  ////取得したいクラスのIDを、クラス名から取得
  var targetClassName = '生徒を招待するクラス'
  for (i = 0; i < myCourses.length; i++) {
    if (myCourses[i]['name'] === targetClassName) {//targetClassNameに一致するときのみ以下の処理を実施
      var inviteClassId = myCourses[i]['id'];
    } else {
      continue;
    }
  }
}

はい、これでお目当てのクラスを取得できました。公式ドキュメントを見ると、Studentsの中にcreateメソッドがあります。最終的にこれ使ったら良さそう。ということで、まずは追加したい生徒情報のまとまったオブジェクトを作成したいと思います。どんなメソッドがいいのか分からないので、いつも通り、「.(ドット)作戦」を実施したいと思います！！！
※.(ドット)作戦とは・・・どんなメソッドが用意されているのか分からない、というか公式ドキュメントを読みこなせないので、「.(ドット)」を入力したときに出る予測入力を利用して、使いたいメソッドを探す方法

そしたら、ほらClassroomと入力したそのすぐ後に、よさげなメソッド、newStudentを発見しましたよ！

student情報に格納できるのは、以下の情報です。

{
  "courseId": string,
  "userId": string,
  "profile": {
    object (UserProfile)
  },
  "studentWorkFolder": {
    object (DriveFolder)
  }
}

さて、、、あとはどこまで情報を足せばいいかですね。。。とりあえずメールアドレスだけで追加できないかを実験してみます。

var addStudent = Classroom.newStudent(userId='[e-mail]');
Classroom.Courses.Students.create(addStudent, inviteStudent);

はい、案の定エラーですね。addStudentを出力してみると、空のオブジェクトが出力されてしまいました。インスタンスの作り方が間違っているっぽいです。まず、何も情報を入れないstudentのインスタンスを作ります。

var addStudent = Classroom.newStudent();

そして、このインスタンスに情報を入れていきたいわけですが、はい、ここでも.(ドット)作戦です！

おお、なかなかいい情報が得られましたよ！
ひとまず、userIdのみメールアドレスを入れてみます。さっきとは書き方変えてます。それで追加できないか試してみましょう。

var addStudent = Classroom.newStudent();
addStudent.userId = '[e-mail]';

Classroom.Courses.Students.create(addStudent,inviteClassId);

はい、エラー出ました。う～～ん、このあたりの記事を読むとこれで十分できそうなんだけど。。。エラーメッセージはこんな感じ。
The caller does not have permission
おっ、こんな記事も見つけました！この記事によると、オーナー権限がない場合は、「追加」は出来ないみたいですね。ただ、たぶんオーナーなんですが、、、
というかあれですね。createメソッドは「追加」をするメソッドで「招待」ではないんですね。
二つの違いがよく分かっていないですが、さっきの記事にしたがって招待するやり方で書いてみます。

  var addStudent = Classroom.newStudent();
  addStudent.userId = '××××@gmail.com';
  addStudent.courseId = inviteClassId;
  addStudent.role = 'STUDENT';

この書き方がうまく格納できたので、生徒を招待してみます。

Classroom.Courses.Students.create(addStudent);

はい、上手くいきませんでした。。。
改めて公式ドキュメントを見てみると、Invitationsというクラスがあることが分かりましたので、そちらのやり方でやってみます。（ただここで文句を言いたいのは、newInvitationなんて記述が公式ドキュメントには一切ないこと。勝手に名付けた.(ドット)作戦をやってみてようやく発見したのですが、、、どっかに書いといてよ～～～）

Classroom.newInvitation();

上記の記述で行いたい招待が作ります。まだ情報は空っぽなので足していきましょう。公式ドキュメントを参照すると、invitationの中には以下の情報が格納できることが分かります。

{
  "id": string,
  "userId": string,
  "courseId": string,
  "role": enum (CourseRole)
}

最後のroleがけっこう重要で、これは生徒か先生か管理者かどれかを選べます。idはクラスルーム参加後に付与されるidなのでまだ取得してないはず。userIdはメールアドレスだから分かる。そんなわけで、userIdとcourseIdとroleの3つに値を指定して、Invitationのcreateメソッドを行いたいと思います。

var makeInvitation = Classroom.newInvitation();
var invitationData = {
  'userId': '[e-mail]',
  'courseId': inviteCourseId,
  'role': 'STUDENT'
}
  Classroom.Invitations.create(invitationData);

上記のコードを実行してみると、、、

ついにできました！！！
これは軽く感動ですね！！！何か詰まった時は、公式ドキュメントをしっかり読むこと＋.(ドット)作戦が大事ですね。では最後まとめます！

まとめ-Classroomに生徒を招待する方法

招待したいクラスのIDが分かっていれば、以下の記述でOKです！

function inviteStudent() {
  var inviteCourseId = '○○○○';// 招待したいコースのIDを入力
  var makeInvitation = Classroom.newInvitation();
  var invitationData = {
    'userId': '××××@××××',// 招待したいユーザーのメールアドレスを入力
    'courseId': inviteCourseId,//
    'role': 'STUDENT'
    };
  Classroom.Invitations.create(invitationData);
}

クラス名からクラスIDを取得して生徒を招待したい場合は以下のコードですね。

function inviteStudent() {
  //所属しているクラスの一覧を配列で取得
  var myCourses = Classroom.Courses.list().courses;

  ////取得したいクラスのIDを、クラス名から取得
  var targetCourseName = '生徒を招待するクラス';
  for (i = 0; i < myCourses.length; i++) {
    if (myCourses[i]['name'] === targetCourseName) {//targetClassNameに一致するときのみ以下の処理を実施
      var inviteCourseId = myCourses[i]['id'];
    } else {
      continue;
    }
  }

  var makeInvitation = Classroom.newInvitation();
  var invitationData = {
    'userId': '××××@××××',
    'courseId': inviteCourseId,// 招待したいユーザーのメールアドレスを入力
    'role': 'STUDENT'
    }

  Classroom.Invitations.create(invitationData);
}

以上、参考になれば嬉しいです。Google Classroom APIは日本語の情報が少ないため、今後も様々トライしてみた結果を記事に書いていきたいと思います！