本頁面提供有關建立及設定 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 團隊審查並核准，才能發布或安裝。
在正式網域中建立新的 Google Cloud 專案。
在 Cloud 專案中啟用 Classroom API。
在 Cloud 專案中啟用 Google Workspace Marketplace SDK。
將 Marketplace SDK 的 App Configuration App Visibility 設為「公開」，並勾選「Unlisted」方塊。
Google Workspace Marketplace 團隊會審查您的應用程式。他們會透過市集 SDK 中指定的開發人員電子郵件地址與您聯絡。應用程式獲准後，請清除「未列入清單」方塊，讓老師和管理員能在市集中找到該應用程式。
建立私人 Google Cloud 專案
這個私人專案代表用於開發作業的外掛程式應用程式。只有建立該應用程式的網域中的使用者才能存取，但安裝前不需要核准。因此，Google 建議您使用這個專案，在受控環境中開發及測試外掛程式。
您必須具備 Teaching & Learning 或 Plus 授權，才能存取 Google Workspace for Education 網域，並建立私人專案。如果您尚未有此網域的存取權，請按照下列步驟設定 Google Workspace for Education 示範網域，並將其升級為 Plus 授權，讓該網域存取 Classroom 外掛程式 API：
- 完成取得開發人員測試網域的步驟。
以示範網域中的管理員身分登入，建立新的 Google Cloud 專案。
如果您無法存取 Google Cloud 控制台或建立 Cloud 專案，請在 管理控制台中檢查下列項目：
- 前往「帳戶設定」>「以年齡為依據的存取權設定」頁面，然後選取「這個群組或機構單位中的所有使用者均年滿 18 歲」選項。
- 在「應用程式」>「額外的 Google 服務」下方：
- Google Cloud Platform 適用於所有人。
- 專案建立設定為「允許使用者建立專案」。
- Cloud Shell 存取設定為「允許存取 Cloud Shell」。
填寫並提交測試網域升級申請表。提交這份表單後，Google 會將您的示範網域升級為 Google Workspace for Education Plus，並提供十個授權，讓您的 Cloud 專案可使用 Classroom 外掛程式 API。
升級和許可清單程序完成後，您會收到電子郵件。在 管理控制台中，將 Plus 授權指派給測試教師帳戶。在「目錄」>「使用者」下方，建立或選取測試教師帳戶。在每位老師的「授權」中，確認 Google Workspace for Education Plus 已「指派」。
在 Cloud 專案中啟用 Classroom API。
在 Cloud 專案中啟用 Google Workspace Marketplace SDK。
將 Marketplace SDK 的「App Configuration」「App Visibility」設為「private」。
在 Marketplace SDK 的「商店資訊」頁面中填寫必填欄位，然後按一下「發布」。應用程式資訊發布後，網域中的使用者就能在 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 會指定應用程式的名稱和供最終使用者閱讀的說明。您可以在「應用程式詳細資料」下方以多種語言提供這些詳細資料。
請在商家資訊中遵循下列規範：
在「應用程式詳細資料」下方：
請勿在應用程式名稱中使用標點符號。例如，請使用「My Add-on by My Company」而非「My Company: My Add-on」或「My Add-on, by My Company」。
簡短說明和詳細說明不得包含完全相同的文字。
+ 確認您已為「Pricing」欄位選取值。這個欄位提供「免費」、「付費但可免費試用」、「付費但提供免費功能」和「付費」價格選項。您不需要在 Marketplace 產品資訊中指定費用金額。
確認您已為「Category」欄位選取值。學習資源或老師和管理員工具，可能是 Classroom 外掛程式的理想選擇。
如需進一步瞭解詳情，請參閱 Marketplace 的應用程式詳細資料說明中列出的項目。
在「圖像資源」下方：
提供的所有圖形素材資源都不會模糊，且符合 Google Workspace 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.teacher@<你的示範網域>
- Sam Student，sam.student@<你的示範網域>
- Sally Student, sally.student@<你的示範網域>
請按照以下步驟建立新的測試帳戶：
- 登入管理控制台。
- 前往「使用者」。
- 按一下「新增使用者」 (如圖 1 所示)。
- 輸入使用者資訊，並指派適當的角色。
圖 1. 管理控制台中的「新增使用者」連結位置。
如要建立新的測試群組，請按照下列步驟操作：
- 登入管理控制台。
- 前往「群組」。
- 按一下「建立群組」 (如圖 2 所示)。
- 輸入群組成員和群組擁有者。
圖 2. 管理控制台中的「建立群組」連結位置。