この一連のチュートリアルでは、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 リポジトリで入手できます。
Node.js サンプルは、zip ファイルとしてダウンロードできます。
前提条件
以下のセクションを確認して、新しいアドオン プロジェクトを準備します。
HTTPS 証明書
アプリはどの開発環境でもホストできますが、Classroom アドオンは https://
でのみ使用できます。したがって、アプリのデプロイやアドオン iframe 内でのテストには、SSL で暗号化されたサーバーが必要です。
localhost
で SSL 証明書を使用することもできます。ローカル開発用に証明書を作成する必要がある場合は、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>
サブフォルダ内にあります。各ステップには以下が含まれます。
./<step>/public
フォルダには、JavaScript、CSS、画像などの静的ファイルがあります。- 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
で指定したポートでサーバーが起動します。