Google Cloud 專案設定

本頁面提供有關建立及設定 Classroom 外掛程式 Google Cloud 專案的相關資訊。Google Cloud 專案可用於透過 OAuth 2.0 實作 Google 單一登入 (Google SSO)、授權外掛程式提出的要求，以及管理 Google Workspace Marketplace 商店中的外掛程式資訊。

如要進一步瞭解如何將外掛程式發布至市集，請參閱「發布應用程式」。

建立 Google Cloud 專案

您可以建立兩種類型的專案：用於開發的私人專案，以及可供使用者存取的公開專案。「公開」和「私人」標籤是指應用程式在 Google Workspace Marketplace 中的瀏覽權限；私人 Marketplace 應用程式只能由建立該應用程式的網域中的使用者安裝，而公開 Marketplace 應用程式則可供任何 Google Workspace 網域使用。這兩者必須是兩個獨立的應用程式，因為專案不能同時是公開和私人專案。公開應用程式必須通過審查並獲准，才能在市集中推出。

如需一般 Google Cloud 專案建立資訊，請參閱「建立 Google Cloud 專案」。

建立公開的 Google Cloud 專案

這個專案代表可供管理員、老師和學生存取的擴充應用程式。公開專案必須經過 Google Workspace Marketplace 團隊審查並核准，才能發布或安裝。

  1. 在正式網域中建立新的 Google Cloud 專案。

    建立 Google Cloud 專案

  2. 在 Cloud 專案中啟用 Classroom API。

    啟用 Classroom API

  3. 在 Cloud 專案中啟用 Google Workspace Marketplace SDK。

    啟用 Google Workspace Marketplace SDK

  4. 將 Marketplace SDK 應用程式設定 應用程式顯示設定設為「公開」，並勾選「不公開」方塊。

  5. 填妥 Marketplace SDK 的「商店資訊」頁面中的必填欄位，然後按一下「發布」PUBLISH。

  6. Google Workspace Marketplace 團隊會審查您的應用程式。這些供應商會透過 Marketplace SDK 中指定的開發人員電子郵件地址與您聯絡。應用程式獲准後，請清除「未列入清單」方塊，讓老師和管理員能在市集中找到該應用程式。

建立私人 Google Cloud 專案

這個私人專案代表用於開發作業的外掛程式應用程式。網域外的使用者無法存取其建立網域，但在安裝前無須經過核准。因此，Google 建議您使用這個專案，在受控環境中開發及測試外掛程式。

您必須使用 Teaching & Learning 或 Plus 授權，才能存取 Google Workspace for Education 網域，並建立私人專案。如果尚未取得這類網域的存取權，請按照下列步驟設定 Google Workspace for Education 示範網域、升級至 Plus 授權，並允許該網域存取 Classroom 外掛程式 API：

  1. 完成取得開發人員測試網域的步驟。

  2. 以示範網域中的管理員身分登入，建立新的 Google Cloud 專案。

    建立 Google Cloud 專案

    如果您無法存取 Google Cloud 控制台，也無法建立 Cloud 專案，請在 管理控制台中檢查以下項目：

    • 前往「帳戶設定」>「以年齡為依據的存取權設定」頁面，然後選取「這個群組或機構單位中的所有使用者均年滿 18 歲」選項。
    • 在「應用程式」>「額外的 Google 服務」下方：
    • Google Cloud Platform 已為所有人啟用。
    • 專案建立設定為「允許使用者建立專案」。
    • Cloud Shell 存取權設定已設為「允許存取 Cloud Shell」。

  3. 填寫並提交測試網域升級申請表。提交這份表單後，Google 會將您的示範網域升級為 Google Workspace for Education Plus，其中有 10 個授權，並允許您的 Cloud 專案加入 Classroom 外掛程式 API。

    升級和許可清單程序完成後，您會收到電子郵件通知。在 管理控制台中將 Plus 授權指派給測試的老師帳戶。在「目錄」>「使用者」下方，建立或選取測試教師帳戶。在每位老師的「授權」中，確認 Google Workspace for Education Plus 已「指派」。

  4. 在 Cloud 專案中啟用 Classroom API。

    啟用 Classroom API

  5. 在 Cloud 專案中啟用 Google Workspace Marketplace SDK。

    啟用 Google Workspace Marketplace SDK

  6. 將 Marketplace SDK 的「App Configuration」(應用程式設定) 設為「private」(私人)。

  7. 填妥 Marketplace SDK 的「商店資訊」頁面中的必填欄位，然後按一下「發布」PUBLISH。應用程式資訊發布後，網域中的使用者便可在 Google Workspace Marketplace 中找到並安裝應用程式，也可以造訪商店資訊頁面顯示的應用程式網址來尋找並安裝應用程式。

OAuth 2.0

您必須取得使用者的資料存取權同意聲明，才能存取 Classroom API。取得這些憑證的方式是為已登入的使用者要求 Google 存取 OAuth 範圍，並接收可用於之後向 Google Classroom 發出 API 呼叫的憑證。您必須在 Google Workspace Marketplace 商店資訊中設定範圍，以便網域管理員在安裝外掛程式時，代表網域使用者提供同意聲明。

由於 Classroom 範圍屬於敏感範圍，因此您必須先要求 OAuth 驗證，才能啟用外掛程式。否則，使用者會看到應用程式未經驗證的警告訊息，且只有少數使用者可以存取您的產品。如要進一步瞭解驗證程序，請參閱審查程序總覽。

如需所有可用範圍和用途的詳細清單，請參閱「Google API 適用的 OAuth 範圍」頁面。如需一般 OAuth 設定資訊，請參閱 Workspace 說明文件中的「設定 OAuth 頁面」。

使用者權限

您的網頁應用程式應要求至少一個以下權限範圍：

  • https://www.googleapis.com/auth/userinfo.email，可讓應用程式查看使用者的電子郵件地址。
  • https://www.googleapis.com/auth/userinfo.profile，允許應用程式查看個人資訊，例如大頭照、姓名和使用者公開提供的其他個人資訊。

使用者在外掛程式中授權上述其中一個範圍後，系統會使用 login_hint 查詢參數來識別這些範圍。開啟 iframe 時，這個參數會傳遞至任何網路應用程式的網址。如果使用者未獲授權，系統不會傳送 login_hint。

login_hint 是標準的 OpenID Connect 參數，在使用 Google 登入或要求 OAuth 權杖時，您可以視需要將參數傳送給 Google。這項功能旨在為使用者提供更順暢的授權體驗。

Classroom 外掛程式範圍

下列範圍專供 Classroom 外掛程式使用：

  • https://www.googleapis.com/auth/classroom.addons.teacher，可存取所有 API 方法。
  • https://www.googleapis.com/auth/classroom.addons.student：允許存取啟動驗證和附件讀取作業。

即使您使用有效的 OAuth 存取權杖表示使用者的憑證，API 呼叫仍會受到額外規定的限制：

  • 所有方法都要求使用者必須是要求中 courseId 指定課程的學生或老師。
  • 如要建立、更新、刪除及回傳附件，使用者必須是老師。
  • 對特定 Google Classroom 訊息發出的呼叫會受到下列檢查標準。
    • 如果加購項目在貼文中已有至少一個附件，便可提出以下要求：
      • iframe 啟動驗證
      • 附件讀取、更新和刪除作業
      • 該篇文章的成績更新
    • 首次開啟附件探索 iframe 時，外掛程式可能尚未在貼文中加入附件。系統會提供 addOnToken 查詢參數，可用來提出以下項目的要求：
      • 在貼文下方建立附件 (必須使用 addOnToken)
      • 啟動驗證 (如果提供 addOnToken 就會進行驗證，如果外掛程式在貼文中沒有現有附件，就必須提供)

OAuth 驗證

Classroom 外掛程式會使用 Google API 存取 Google 使用者的資料。

如要進一步瞭解驗證程序，請參閱 OAuth API 驗證常見問題。

Google Workspace Marketplace 產品資訊

如需 Google Workspace Marketplace SDK 的一般設定資訊，請參閱「啟用並設定 Google Workspace Marketplace SDK」和「建立 Google Workspace Marketplace 商店資訊」。

清單項目注意事項

您公開的 Google Cloud 專案的 Marketplace SDK Store Listing 會指定應用程式的名稱和供最終使用者閱讀的說明。您可以在「應用程式詳細資料」下方以多種語言提供這些詳細資料。

請在商家資訊中遵循下列規範：

  • 在「App Details」下方：

    • 請勿在應用程式名稱中使用標點符號。例如，請使用「My Add-on by My Company」而非「My Company: My Add-on」或「My Add-on, by My Company」。

    • 簡短說明和詳細說明不得包含完全相同的文字。

    + 確認您已為「Pricing」欄位選取值。這個欄位提供「免費」、「付費但可免費試用」、「付費但提供免費功能」和「付費」價格選項。您不需要在 Marketplace 產品資訊中指定費用金額。

    • 確認您已為「Category」欄位選取值。「學術資源」或「老師和管理工具」可能是適用於 Classroom 外掛程式的選項。

    • 如需進一步瞭解詳情，請參閱 Marketplace 的應用程式詳細資料說明中列出的項目。

  • 在「圖像資源」下方：

  • 在「支援連結」下方：

    • 確認您已提供應用程式服務條款的連結。

  • 請確認您符合 Google API 品牌規範，其中涵蓋允許使用的名稱和說明。

  • 如果你在產品資訊中提及任何 Google 產品，請使用商標清單中提供的格式使用產品名稱。請務必加入商標 (™) 符號 (如有指定)，使用「Google 文件™」，而非「Google 文件」。

與 Google 的授權和結帳系統服務整合

如果您想讓 Google Workspace Marketplace 應用程式與 Google 的授權和結帳服務整合，請參閱「 Marketplace API」相關說明。

安裝設定

外掛程式除了允許「管理員」安裝外，也可以允許「個人」安裝。本頁重點說明這兩種安裝類型的差異，但並非要宣傳任何一種安裝類型。您可以在 Google Workspace Marketplace SDK 應用程式設定頁面中選擇是否允許個別安裝。

管理員安裝

管理員安裝：管理員可為網域中的所有帳戶，或特定存取群組或機構單位新增外掛程式。只有網域管理員才能執行管理員安裝作業。管理員可以選擇代表網域中的所有使用者同意所有存取範圍；如果管理員選擇這麼做，系統就不會提示使用者同意任何存取範圍。

以下是有關管理員安裝作業的幾點注意事項。

  • 更嚴格的控管機制管理員可以限制哪些使用者可以存取外掛程式。
  • 與授權的相容性。如果您的應用程式需要授權，透過管理員進行發布安裝作業，或許有助於確保授權能夠發布，並搭配對應的機構正確使用。
  • 減輕使用者負擔：管理員安裝作業能減少老師和學生的設定負載。這樣一來，使用者體驗可能會更流暢，點擊次數和混淆情況也會減少。

如要進一步瞭解如何執行管理員安裝作業，請參閱「在網域內安裝 Marketplace 中的應用程式」一文；如要進一步瞭解機構單位和存取權群組，請參閱「機構架構的運作方式」。

個別安裝

個人安裝可以在使用者自己的帳戶中新增外掛程式。在安裝期間，系統會提示使用者同意外掛程式的存取權範圍。

以下是個別安裝作業的注意事項。

  • 促進採用率：更多使用者可以從 Google Workspace Marketplace 看到及安裝您的外掛程式。允許個別安裝功能，可能會促使更多老師採用或推廣您的產品。
  • 管理員測試。管理員可能會先個別安裝外掛程式，以便測試或評估，然後再為更廣泛的群組核准或安裝。

除了代表使用者安裝外掛程式，管理員也可以維護許可清單，允許使用者安裝可個別安裝的外掛程式。如果外掛程式不在許可清單中，使用者仍能在 Google Workspace Marketplace 中看到外掛程式清單，但無法安裝這個外掛程式；系統會改為顯示訊息，說明網域管理員不允許安裝該外掛程式。如要進一步瞭解這項行為，請參閱「管理許可清單中的 Google Workspace Marketplace 應用程式」。

詳情請參閱 Google Workspace Marketplace 安裝設定說明文件。

應用程式整合功能

您必須在「附件設定 URI」欄位中提供啟動 iframe 網址。這個網址會用於 附件探索 iframe 的 iframe src 值。附件探索 iframe 可讓老師尋找要附加至作業的內容或活動。

您也必須指定所有允許來自外掛程式的附件的 URI 前置字串。這項功能可防止來自未經授權來源的附件，進而提升安全性。

如要進一步瞭解這些欄位，請參閱 iframe 指南頁面。

測試帳戶

在示範網域中建立測試帳戶，以便驗證私人外掛程式的正確行為。您需要兩個學生帳戶，才能在學生作業評論 iframe 中測試切換學生。

建議的測試帳戶：

  • Tammy 老師，tammy.teacher@<您的示範網域>
  • Sam Student，sam.student@<你的測試網域>
  • Sally Student, sally.student@<你的示範網域>

請按照下列步驟建立新的測試帳戶：

  1. 登入管理控制台。
  2. 前往「使用者」。
  3. 按一下「新增使用者」 (如圖 1 所示)。
  4. 輸入使用者資訊，並指派適當的角色。

按一下「新增使用者」 圖 1. 管理控制台中「新增使用者」連結的位置。

如要建立新的測試群組，請按照下列步驟操作：

  1. 登入管理控制台。
  2. 前往「群組」。
  3. 按一下「建立群組」 (請見圖 2)。
  4. 輸入群組成員和擁有者。

按一下「建立群組」 圖 2.管理控制台中的「建立群組」連結位置。