本頁面提供建立及設定 Classroom 外掛程式的 Google Cloud 專案須知。Google Cloud 專案可用來透過 OAuth 2.0 (Google 單一登入) 實作 Google 單一登入、授權您的外掛程式提出的要求，以及管理 Google Workspace Marketplace 商店中的外掛程式清單。
如需在 Marketplace 中發布外掛程式的一般資訊，請參閱「發布應用程式」。
建立 Google Cloud 專案
您可建立的專案有兩種類型：用於開發的 private 專案和可由使用者連線的公開專案。「公開」和「私人」標籤是指您的應用程式 Google Workspace Marketplace 中的瀏覽權限；私人 Marketplace 應用程式只能由在其建立的網域內安裝，而任何 Google Workspace 網域皆可使用公開的 Marketplace 應用程式。兩者必須是兩個不同的應用程式，因為一項專案不能同時是公開和私人。公開應用程式必須先經過審查並獲得核准，才能在市集上架。
如需 Google Cloud 專案的一般建立資訊，請參閱「建立 Google Cloud 專案」一文。
建立公開的 Google Cloud 專案
這項專案代表外掛程式，可供管理員、老師和學生存取。公開專案必須先經過 Google Workspace Marketplace 團隊的審查與核准，才能啟動或安裝。
在實際工作環境網域中建立新的 Google Cloud 專案。
在 Cloud 專案中啟用 Classroom API。
在 Cloud 專案中啟用 Google Workspace Marketplace SDK。
將 Marketplace SDK 的「App Configuration」(應用程式設定) 設為「Public」(公開)，然後勾選「不公開」方塊。
填妥 Marketplace SDK 的「商店資訊」頁面中的必填欄位，然後按一下「發布」。
Google Workspace Marketplace 團隊將會審查您的應用程式。這些供應商會透過 Marketplace SDK 中指定的開發人員電子郵件地址與您聯絡。應用程式獲準後，請清除「不公開」方塊，讓老師和管理員可在 Marketplace 中找到該應用程式。
建立私人 Google Cloud 專案
這項 private 專案代表用於開發作業的外掛程式應用程式。網域外的使用者無法存取其建立網域，但在安裝前無須經過核准。因此，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，其中有 10 個授權，並允許您的 Cloud 專案加入 Classroom 外掛程式 API。
升級和許可清單程序完成後，您會收到電子郵件通知。在 管理控制台中將 Plus 授權指派給測試的老師帳戶。在「Directory」>「Users」下方，建立或選取測試老師帳戶。在每位老師的「授權」中，確認 Google Workspace for Education Plus 已已指派。
在 Cloud 專案中啟用 Classroom API。
在 Cloud 專案中啟用 Google Workspace Marketplace SDK。
將 Marketplace SDK 的「App Configuration」(應用程式設定) 設為「private」(私人)。
填妥 Marketplace SDK 的「商店資訊」頁面中的必填欄位，然後按一下「發布」。應用程式資訊發布後，網域中的使用者便可在 Google Workspace Marketplace 中找到並安裝應用程式，也可以造訪商店資訊頁面顯示的應用程式網址來尋找並安裝應用程式。
OAuth 2.0
您必須同意使用者資料存取權，才能使用 Classroom API。藉由為已登入的使用者要求 Google 存取 OAuth 範圍，並取得可用來後續對 Google Classroom 發出 API 呼叫的權杖，即可取得這類憑證。您必須在 Google Workspace Marketplace 商店資訊中設定範圍，以便網域管理員在安裝外掛程式時，代表網域使用者提供同意聲明。
如需所有可用範圍及用途的詳細清單，請參閱「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 商店資訊會指定向使用者顯示的應用程式名稱和說明。您可以在「App Details」下方使用多種語言提供這些詳細資料。
請在商家資訊中遵循下列規範：
在「App Details」下方：
避免在應用程式名稱中使用標點符號。舉例來說，請使用「My Add-on by My Company」(我的公司：我的外掛程式) 而不是「My Company: My Add-on」(我的公司：我的外掛程式) 或「My Add-on, by My Company」。
「簡短說明」和「詳細說明」的文字不應相同。
+ 確認您已為「價格」欄位選取值。這個欄位包括「免費」、「付費免費試用」、「付費功能付費」和「付費」定價的選項。您不需要在 Marketplace 產品資訊中指定費用金額。
確認您已在「Category」欄位中選取值。 「學術資源」或「老師和管理工具」可能是適用於 Classroom 外掛程式的選項。
詳情請參閱 Marketplace 的應用程式詳細資料說明中列出的項目。
在「圖像資源」下方：
您提供的任何圖像資源都不會模糊不清，且符合 Google Workspace Marketplace 標準中的指定大小
您提供的任何螢幕截圖均能準確反映您的附加服務體驗。
在「支援連結」下方：
- 確認您已提供應用程式服務條款的連結。
請務必遵守 Google API 品牌宣傳規範，其中涵蓋了允許的名稱和說明。
如果您提及商店資訊中的任何 Google 產品，請使用商標清單中提供的格式名稱。請務必加上商標 (TM) 符號 (如有)。請使用「Google DocsTM」，而非「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 所示)。
- 輸入使用者資訊，並指派適當角色。
圖 1.管理控制台中「新增使用者」連結的位置。
請按照以下程序建立新的測試群組：
- 登入管理控制台。
- 前往「群組」。
- 按一下「建立群組」 (請見圖 2)。
- 輸入群組成員和擁有者。
圖 2.管理控制台中建立群組連結的位置。