Google Classroom アドオンの一般提供が開始されました。詳しくは、アドオンのドキュメントをご覧ください。

このページは Cloud Translation API によって翻訳されました。

チュートリアル

この一連のチュートリアルでは、動作する 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 ファイルとしてダウンロードできます。

Node.js アーカイブ

前提条件

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

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 です。このルートは、このチュートリアルの後半で作成して処理します。このようなルートはいつでも編集または追加できます。
- [作成] をクリックします。
新しく作成された認証情報がダイアログに表示されます。[DOWNLOAD 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 からダウンロードしたクライアントシークレットファイル。これはサンプルアーカイブには含まれていません。ダウンロードした認証情報ファイルの名前を変更して、各ディレクトリのルートにコピーする必要があります。
  
  重要: サンプルを実行する前に、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 認証鍵ファイルの 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)

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 で指定したポートでサーバーが起動します。

チュートリアル

実装の例

ダウンロード先

前提条件

HTTPS 証明書

Google Cloud プロジェクト

OAuth 認証情報

言語固有の前提条件

Python

Node.js

Java

ファイルについて

ディレクトリ名

ディレクトリの内容

Python

Node.js

Java

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

Python

Node.js

Java

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