チュートリアル

この一連のチュートリアルでは、動作する Classroom アドオンのすべての要素について説明します。各チュートリアル ステップでは、特定のコンセプトを取り上げ、単一のウェブ アプリケーションに実装します。機能的なアドオンの設定、構成、リリースを支援することを目的としています。

アドオンは Google Cloud プロジェクトとやり取りする必要があります。Google Cloud に慣れていない場合は、スタートガイドをご覧ください。認証情報、API アクセス、Google Workspace Marketplace SDK は、Google Cloud コンソールで管理します。Marketplace SDK の詳細については、Google Workspace Marketplace の掲載ガイドのページをご覧ください。

このガイドの内容は次のとおりです。

• Google Cloud を使用して、Classroom の iframe に表示するページを作成します。
• Google シングル サインオン（SSO）を追加して、ユーザーがログインできるようにします。
• API 呼び出しを実行して、アドオンを課題に添付します。
• アドオンの送信に関する主な要件と必須機能を説明します。

このガイドは、プログラミングと基本的なウェブ開発の概念に精通していることを前提としています。チュートリアルを開始する前に、プロジェクト構成ガイドを読むことを強くおすすめします。このページでは、チュートリアルでは説明されていない重要な構成の詳細について説明します。

実装の例

完全なリファレンス例は Python で確認できます。部分実装は Java と Node.js でも利用できます。これらの実装は、後続のページにあるサンプルコードのソースです。

ダウンロード先

Python と Java のサンプルは、次の GitHub リポジトリで入手できます。

• Python リポジトリ

• Java リポジトリ

Node.js サンプルは zip ファイルとしてダウンロードできます。

• Node.js アーカイブ

前提条件

新しいアドオン プロジェクトを準備するには、次のセクションをご覧ください。

HTTPS 証明書

アプリは任意の開発環境でホストできますが、Classroom アドオンは https:// でのみ使用できます。したがって、アプリをデプロイする場合や、アドオンの iframe 内でアプリをテストする場合は、SSL 暗号化を備えたサーバーが必須です。

localhost は SSL 証明書で使用できます。ローカル開発用の証明書を作成する必要がある場合は、mkcert を検討してください。

Google Cloud プロジェクト

これらの例で使用できるように Google Cloud プロジェクトを構成する必要があります。開始に必要な手順の概要については、 Google Cloud プロジェクトの作成ガイドをご覧ください。最初のチュートリアルの Google Cloud プロジェクトを設定するセクションでは、必要な構成アクションについても説明しています。

完了したら、OAuth 2.0 クライアント ID を JSON ファイルとしてダウンロードします。この認証情報ファイルは、解凍したサンプル ディレクトリに追加する必要があります。特定のロケーションについては、ファイルを理解するをご覧ください。

OAuth 認証情報

キーポイント: ウェブアプリは、Google Cloud で管理されている OAuth 2.0 認証情報を使用する必要があります。

新しい OAuth 認証情報を作成する手順は次のとおりです。

• [Google Cloud 認証情報] ページに移動します。画面上部で、正しいプロジェクトが選択されていることを確認します。
• [認証情報を作成] をクリックし、プルダウンから [OAuth クライアント ID] を選択します。
• 次のページで、以下の操作を行います。
  • [アプリケーションの種類] を [ウェブ アプリケーション] に設定します。
  • [承認済みのリダイレクト URI] の下の [URI を追加] をクリックします。アプリケーションのコールバック ルートの完全なパスを追加します。たとえば、https://my.domain.com/auth-callback や https://localhost:5000/callback です。このルートは、このチュートリアルの後半で作成して処理します。このようなルートはいつでも編集または追加できます。
  • [作成] をクリックします。
• 新しく作成された認証情報がダイアログに表示されます。[DOWNLOAD JSON] オプションを選択します。ダウンロードした JSON ファイルをサーバー ディレクトリにコピーします。

言語固有の前提条件

前提条件の最新のリストについては、各リポジトリの README ファイルを参照してください。

PythonNode.jsJava

Python のサンプルでは、Flask フレームワークを使用しています。完全なソースコードは、提供されているリンクからダウンロードできます。

必要に応じて Python 3.7 以降をインストールし、pip が使用可能であることを確認します。

python3 -m ensurepip --upgrade

また、新しい Python 仮想環境を設定して有効にすることをおすすめします。

python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate

ダウンロードしたサンプルの各チュートリアル サブディレクトリには requirements.txt があります。必要なライブラリは pip を使用してすばやくインストールできます。次のコマンドを使用して、最初のチュートリアルに必要なライブラリをインストールします。

cd flask/01-basic-app
pip install -r requirements.txt

Node.js の例では、Express フレームワークを使用しています。ソースコード全体は、提供されているリンクからダウンロードできます。

この例では、Node.js v16.13 以降が必要です。

npm を使用して、必要なノード モジュールをインストールします。

npm install

この Java の例では、Spring Boot フレームワークを使用しています。ソースコード全体は、提供されているリンクからダウンロードできます。

Java 11 以降がマシンにまだインストールされていない場合は、インストールします。

Spring Boot アプリケーションでは、Gradle または Maven を使用してビルドを処理し、依存関係を管理できます。この例には、Maven 自体をインストールしなくてもビルドが成功することを保証する Maven ラッパーが含まれています。

プロジェクトをダウンロードまたはクローン作成したディレクトリで、次のコマンドを実行して、プロジェクトを実行するための前提条件があることを確認します。

java --version
./mvnw --version

Windows の場合:

java -version
mvnw.cmd --version

ファイルについて

以降のセクションでは、サンプル ディレクトリのレイアウトについて説明します。

ディレクトリ名

各リポジトリには、名前が数字で始まる複数のディレクトリ（/01-basic-app/ など）が含まれています。番号は、特定のチュートリアルの手順に対応しています。各ディレクトリには、特定のチュートリアルで説明されている機能を実装した、完全に機能するウェブアプリが含まれています。たとえば、/01-basic-app/ ディレクトリには、アドオンを作成するチュートリアルの最終的な実装が含まれています。

ディレクトリの内容

ディレクトリの内容は、実装言語によって異なります。

PythonNode.jsJava

• ディレクトリのルートには、次のファイルが含まれています。

  • main.py - Python アプリケーションのエントリ ポイント。このファイルで使用するサーバー構成を指定し、ファイルを実行してサーバーを起動します。
  • requirements.txt - ウェブアプリの実行に必要な Python モジュール。これらは pip install -r requirements.txt を使用して自動的にインストールできます。

  • client_secret.json - Google Cloud からダウンロードしたクライアント シークレット ファイル。これはサンプル アーカイブには含まれていません。ダウンロードした認証情報ファイルの名前を変更して、各ディレクトリのルートにコピーする必要があります。

    重要: サンプルを実行する前に、Google Cloud プロジェクトのクライアント シークレット ファイルを指定する必要があります。

• config.py - Flask サーバーの構成オプション。

• webapp ディレクトリには、ウェブ アプリケーションのコンテンツが含まれています。次のツールが含まれています。

• さまざまなページの Jinja テンプレートを含む /templates/ ディレクトリ。

• 画像、CSS、補助的な JavaScript ファイルを含む /static/ ディレクトリ。

• routes.py - ウェブ アプリケーション ルートのハンドラ メソッド。

• __init__.py - webapp モジュールのイニシャライザ。このイニシャライザは、Flask サーバーを起動し、config.py で設定された構成オプションを読み込みます。

• 特定のチュートリアルの手順で必要となる追加ファイル。

チュートリアルの各ステップは、それぞれ <step> サブフォルダにあります。各ステップには次のものが含まれます。

• JavaScript、CSS、画像などの静的ファイルは、./<step>/public フォルダにあります。
• Express ルータは ./<step>/routes フォルダにあります。
• HTML テンプレートは ./<step>/views フォルダにあります。
• サーバー アプリケーションは ./<step>/app.js です。

プロジェクト ディレクトリには、以下が含まれます。

• src.main ディレクトリには、アプリケーションを正常に実行するためのソースコードと構成が含まれています。このディレクトリには次のものがあります。 + java.com.addons.spring ディレクトリには、Application.java ファイルと Controller.java ファイルが含まれています。Application.java ファイルはアプリケーション サーバーの実行を担当し、Controller.java ファイルはエンドポイント ロジックを処理します。+ resources ディレクトリには、HTML ファイルと JavaScript ファイルを含む templates ディレクトリが含まれています。また、サーバーの実行ポート、キーストア ファイルのパス、templates ディレクトリのパスを指定する application.properties ファイルも含まれています。この例では、resources ディレクトリにキーストア ファイルを含めます。任意の場所に保存できますが、パスに応じて application.properties ファイルを更新してください。
  • pom.xml には、プロジェクトのビルドと必要な依存関係の定義に必要な情報が含まれています。
  • .gitignore には、git にアップロードしないファイル名が含まれています。この .gitignore にキーストアへのパスを追加してください。指定された例では、これは secrets/*.p12 です（キーストアの目的については、後のセクションで説明します）。チュートリアル 2 以降では、リモート リポジトリにシークレットを含めないように、client_secret.json ファイルのパスを指定する必要があります。チュートリアル 3 以降では、H2 データベース ファイルとファイル データストア ファクトリーのパスを追加する必要があります。これらのデータストアの設定の詳細については、リピーターの対応に関する 3 つ目のチュートリアルをご覧ください。
  • mvnw と mvnw.cmd は、それぞれ Unix と Windows 用の Maven ラッパー実行ファイルです。たとえば、Unix で ./mvnw --version を実行すると、Apache Maven のバージョンなどの情報が出力されます。
  • .mvn ディレクトリには、Maven ラッパーの構成が含まれています。

サンプル サーバーを実行する

キーポイント: ウェブアプリを開くことができるのは、HTTPS 経由の Google Classroom のみです。詳細については、HTTPS 証明書をご覧ください。

サーバーをテストするには、サーバーを起動する必要があります。次の手順に沿って、任意の言語でサンプル サーバーを実行します。

PythonNode.jsJava

Oauth 認証情報

前述の方法で OAuth 認証情報を作成してダウンロードします。JSON ファイルを、アプリケーションのサーバー起動ファイルと一緒にルート ディレクトリに配置します。

サーバーを構成する

ウェブサーバーを実行する方法はいくつかあります。Python ファイルの末尾に、次のいずれかを追加します。

1. 保護されていない localhost。これは、ブラウザ ウィンドウで直接テストする場合にのみ適しています。保護されていないドメインは、Classroom アドオンの iframe に読み込むことはできません。

   if __name__ == "__main__":
     # Disable OAuthlib's HTTPs verification.
     os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"
   
     # Run the web app at http://localhost:5000.
     app.run(debug=True)
   

2. localhost を保護します。ssl_context 引数には、SSL 認証鍵ファイルの Tuple を指定する必要があります。

   if __name__ == "__main__":
     # Run the web app at https://localhost:5000.
     app.run(host="localhost",
             ssl_context=("localhost.pem", "localhost-key.pem"),
             debug=True)
   

3. Gunicorn サーバー。これは、本番環境対応のサーバーまたはクラウド デプロイに適しています。この起動オプションで使用する PORT 環境変数を設定することをおすすめします。

   if __name__ == "__main__":
     # Run the web app at https://<your domain>:<server_port>.
     # Defaults to https://<your domain>:8080.
     server_port = os.environ.get("PORT", "8080")
     app.run(debug=True, port=server_port, host="0.0.0.0")
   

サーバーを起動する

警告: サーバーを起動する前に、Classroom API と必要な認証情報にアクセスできるように Google Cloud プロジェクトを設定する必要があります。

Python アプリケーションを実行して、前の手順で構成したようにサーバーを起動します。

python main.py

表示された URL をクリックして、ブラウザでウェブアプリを表示し、正しく動作していることを確認します。

サーバーを構成する

HTTPS でサーバーを実行するには、HTTPS でアプリケーションの実行に使用する自己証明書を作成する必要があります。これらの認証情報は、リポジトリのルート フォルダに sslcert/cert.pem と sslcert/key.pem として保存する必要があります。ブラウザでこれらの鍵を受け入れるには、OS キーチェーンにこれらの鍵を追加することが必要な場合があります。

ファイルを git に commit しないため、*.pem が .gitignore ファイルにあることを確認します。

サーバーを起動する

警告: サーバーを起動する前に、Classroom API と必要な認証情報にアクセスできるように Google Cloud プロジェクトを設定する必要があります。

次のコマンドを使用して、サーバーで実行する正しいステップに step01 を置き換えて、アプリケーションを実行できます（01-basic-app の場合は step01、02-sign-in の場合は step02 など）。

npm run step01

または

npm run step02

これにより、https://localhost:5000 でウェブサーバーが起動します。

ターミナルで Control + C を使用してサーバーを終了できます。

サーバーを構成する

HTTPS でサーバーを実行するには、HTTPS でアプリケーションの実行に使用する自己証明書を作成する必要があります。

ローカル開発には mkcert の使用を検討してください。mkcert をインストールしたら、次のコマンドを実行して、HTTPS で実行するローカルに保存された証明書を生成します。

mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>

この例では、リソース ディレクトリにキーストア ファイルが含まれています。任意の場所に保存できますが、パスに応じて application.properties ファイルを更新してください。ドメイン名は、プロジェクトを実行するドメインです（例: localhost）。

ファイルを git に commit しないため、*.p12 が .gitignore ファイルにあることを確認します。

サーバーを起動する

警告: サーバーを起動する前に、Classroom API と必要な認証情報にアクセスできるように Google Cloud プロジェクトを設定する必要があります。

Application.java ファイルで main メソッドを実行して、サーバーを起動します。たとえば IntelliJ では、src/main/java/com/addons/spring ディレクトリで Application.java > Run 'Application' を右クリックするか、Application.java ファイルを開いて main(String[] args) メソッド シグネチャの左側にある緑色の矢印をクリックします。または、ターミナル ウィンドウでプロジェクトを実行することもできます。

./mvnw spring-boot:run

Windows の場合

mvnw.cmd spring-boot:run

これにより、https://localhost:5000 または application.properties で指定したポートでサーバーが起動します。