この一連のチュートリアルでは、機能する Classroom アドオンの可動部分について説明します。各チュートリアル ステップでは特定のコンセプトを取り上げ、1 つのウェブ アプリケーションに実装します。目標は、機能的なアドオンの設定、構成、リリースを支援することです。
アドオンは Google Cloud プロジェクトとやり取りする必要があります。Google Cloud に慣れていない場合は、スタートガイドをご覧ください。認証情報、API アクセス、GWM SDK は Google Cloud コンソールで管理します。GWM SDK の詳細については、Google Workspace Marketplace リスティング ガイドのページをご覧ください。
このガイドの内容は次のとおりです。
- Google Cloud を使用して、Classroom で iframe に表示するページを作成します。
- Google シングル サインオン(SSO)を追加して、ユーザーがログインできるようにします。
- API 呼び出しを行ってアドオンを課題に添付します。
- アドオンの主な提出要件と必須機能に対処する。
このガイドは、プログラミングとウェブ開発の基本的なコンセプトを理解していることを前提としています。チュートリアルを開始する前に、プロジェクト構成ガイドをお読みになることを強くおすすめします。このページには、このチュートリアルでは完全には説明していない重要な構成の詳細が記載されています。
実装の例
リファレンス サンプルの全文は、JavaScript、Python、Java で入手できます。これらの実装は、後続のページに記載されているサンプルコードのソースです。
ダウンロード先
事例の完全なアーカイブは、以下のリンクからダウンロードできます。
前提条件
以下のセクションを確認して、新しいアドオン プロジェクトを用意します。
HTTPS 証明書
アプリはどの開発環境でもホストできますが、Classroom アドオンは https://
でのみ使用できます。したがって、アプリをデプロイしたり、アドオン iframe 内でテストしたりするには、SSL 暗号化を使用したサーバーが必要です。
SSL 証明書では localhost
を使用できます。ローカル開発用の証明書を作成する必要がある場合は、mkcert を検討してください。
Google Cloud プロジェクト
これらの例で使用するために、Google Cloud プロジェクトを構成する必要があります。開始するために必要な手順の概要については、 Google Cloud プロジェクトの作成ガイドをご覧ください。最初のチュートリアルの Google Cloud プロジェクトを設定するセクションでも、必要な構成操作の手順について説明しています。
完了したら、OAuth 2.0 クライアント ID を JSON ファイルとしてダウンロードします。この認証情報ファイルを、解凍したサンプル ディレクトリに追加する必要があります。具体的な場所については、ファイルについてをご覧ください。
OAuth 認証情報
新しい OAuth 認証情報を作成する手順は次のとおりです。
- Google Cloud の [認証情報] ページに移動します。画面上部で正しいプロジェクトが選択されていることを確認します。
- [認証情報を作成] をクリックし、プルダウンから [OAuth クライアント ID] を選択します。
- 次のページで、次の操作を行います。
- [アプリケーションの種類] を [ウェブ アプリケーション] に設定します。
- [承認済みのリダイレクト URI] で、[URI を追加] をクリックします。アプリケーションのコールバック ルートのフルパスを追加します。たとえば、
https://my.domain.com/auth-callback
やhttps://localhost:5000/callback
です。このルートはこのチュートリアルの後半で作成して処理します。このような経路はいつでも編集または追加できます。 - [作成] をクリックします。
- 新しく作成した認証情報を含むダイアログが表示されます。[JSON をダウンロード] オプションを選択します。ダウンロードした
.json
ファイルをサーバー ディレクトリにコピーします。
言語固有の前提条件
最新の前提条件については、各アーカイブの README ファイルをご覧ください。
Python
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
Node.js の例では、Express フレームワークを使用しています。上記のリンクから完全なソースコードをダウンロードできます。
この例では、Node.js v16.13 以降が必要です。
npm
を使用して必要なノード モジュールをインストールします。
npm install
Java
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/
ディレクトリには、アドオンの作成のチュートリアルの最終的な実装が含まれています。
ディレクトリの内容
ディレクトリの内容は、実装言語によって異なります。
Python
ディレクトリ ルートには、次のファイルが含まれています。
main.py
- Python アプリケーションのエントリ ポイント。このファイルで使用するサーバー構成を指定し、それを実行してサーバーを起動します。requirements.txt
- ウェブアプリの実行に必要な Python モジュール。pip install -r requirements.txt
を使用して自動的にインストールできます。client_secret.json
- Google Cloud からダウンロードされたクライアント シークレット ファイル。これはサンプル アーカイブには含まれていません。ダウンロードした認証情報ファイルの名前を変更し、各ディレクトリ ルートにコピーする必要があります。
config.py
- Flask サーバーの構成オプション。webapp
ディレクトリには、ウェブ アプリケーションのコンテンツが含まれています。次のツールが含まれています。さまざまなページの Jinja テンプレートを含む
/templates/
ディレクトリ。画像、CSS、補助的な JavaScript ファイルを含む
/static/
ディレクトリ。routes.py
- ウェブ アプリケーション ルートのハンドラ メソッド。__init__.py
-webapp
モジュールのイニシャライザ。このイニシャライザは Flask サーバーを起動し、config.py
で設定された構成オプションを読み込みます。特定のチュートリアル ステップで必要な追加のファイル。
Node.js
チュートリアルの各ステップは、それぞれの <step>
サブフォルダにあります。各ステップには以下が含まれます。
- JavaScript、CSS、画像などの静的ファイルは
./<step>/public
フォルダにあります。 - Express ルーターは
./<step>/routes
フォルダにあります。 - HTML テンプレートは
./<step>/views
フォルダにあります。 - サーバー アプリケーションは
./<step>/app.js
です。
Java
プロジェクト ディレクトリには、以下が含まれています。
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 ラッパーの構成が含まれています。
サンプル サーバーを実行する
テストするには、サーバーを起動する必要があります。以下の手順に沿って、選択した言語でサンプル サーバーを実行します。
Python
Oauth 認証情報
上記の手順に従って、OAuth 認証情報を作成してダウンロードします。.json
ファイルは、アプリケーションのサーバー起動ファイルとともにルート ディレクトリに配置します。
サーバーを構成する
ウェブサーバーを実行するにはいくつかの方法があります。Python ファイルの末尾に、次のいずれかを追加します。
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)
localhost
を保護します。ssl_context
引数には、SSL 鍵ファイルのタプルを指定する必要があります。if __name__ == "__main__": # Run the web app at https://localhost:5000. app.run(host="localhost", ssl_context=("localhost.pem", "localhost-key.pem"), debug=True)
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")
サーバーを起動する
Python アプリケーションを実行して、前の手順で構成したサーバーを起動します。
python main.py
表示された URL をクリックして、ウェブアプリがブラウザに表示され、正しく実行されていることを確認します。
Node.js
サーバーを構成する
HTTPS 経由でサーバーを実行するには、HTTPS 経由でアプリケーションを実行するために使用する自己証明書を作成する必要があります。これらの認証情報は、リポジトリのルートフォルダに sslcert/cert.pem
と sslcert/key.pem
として保存する必要があります。ブラウザでこれらの鍵を受け入れるには、OS キーチェーンへのキーの追加が必要になる場合があります。
ファイルを git に commit しないため、*.pem
が .gitignore
ファイルに含まれていることを確認します。
サーバーを起動する
次のコマンドを使用して、次のコマンドでアプリケーションを実行できます。step01
はサーバーとして実行するステップに置き換えます(たとえば、01-basic-app は step01
、02-sign-in は step02
です)。
npm run step01
を選択します。
npm run step02
これにより、ウェブサーバーが https://localhost:5000
で起動します。
ターミナルで Control + C
を使用してサーバーを終了することもできます。
Java
サーバーを構成する
HTTPS 経由でサーバーを実行するには、HTTPS 経由でアプリケーションを実行するために使用する自己証明書を作成する必要があります。
ローカルでの開発には mkcert の使用を検討してください。mkcert
をインストールすると、次のコマンドによって、HTTPS 経由で実行するためのローカルに保存された証明書が生成されます。
mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>
この例では、リソース ディレクトリにキーストア ファイルが含まれています。このパスは任意の場所に保存できますが、そのパスに応じて application.properties
ファイルを更新してください。ドメイン名は、プロジェクトを実行するドメインです(例: localhost
)。
ファイルを git に commit しないため、*.p12
が .gitignore
ファイルに含まれていることを確認します。
サーバーを起動する
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
で指定したポートでサーバーが起動します。