Google Cloud 專案設定

本頁面提供建立及設定 Classroom 外掛程式適用的 Google Cloud 專案時，您需要瞭解的資訊。Google Cloud 專案會透過 OAuth 2.0 (Google 單一登入) 實作 Google 單一登入，授權外掛程式提出的要求，以及管理 Google Workspace Marketplace 商店中的外掛程式資訊。

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

建立 Google Cloud 專案

重點： 您必須在 Google Workspace Marketplace SDK 中，將正式版外掛程式應用程式的能見度設為「公開」。私人專案可用於開發及測試外掛程式，但您只需要公開專案。

您可以建立兩種專案：用於開發的私人專案，以及可供使用者存取的公開專案。「公開」和「私人」標籤是指應用程式在 Google Workspace Marketplace 中的瀏覽權限；私人 Marketplace 應用程式只能由建立該應用程式的網域使用者安裝，公開 Marketplace 應用程式則適用於任何 Google Workspace 網域。由於專案無法同時設為公開和私人，因此您必須分別提出申請。公開應用程式必須通過審查並獲准，才能在 Marketplace 上架。

重要事項： 私人專案無法轉換為公開專案。

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

建立公開的 Google Cloud 專案

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

1. 在生產環境網域中建立新的 Google Cloud 專案。

   建立 Google Cloud 專案

   重要事項：請確認專案屬於正式版網域，且您已以該網域的使用者身分登入 Google Cloud 控制台。
   警告：測試時必須使用專案的草稿版本。詳情請參閱「使用草稿更新應用程式資訊」。

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

   啟用 Classroom API

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

   啟用 Google Workspace Marketplace SDK

4. 將 Marketplace SDK 的「應用程式設定」「應用程式瀏覽權限」設為「公開」，並勾選「不公開」方塊。

   重點：您無法共用或轉換內部開發和測試期間使用的私人專案。
   重點：您無法透過瀏覽或搜尋，在 Google Workspace Marketplace 中找到未列出的應用程式。在 Marketplace SDK 設定中，你可以找到可用於安裝外掛程式的直接網址。只有 Google 和開發人員可以找到商店資訊。在您準備好向一般大眾發布應用程式前，請將應用程式設為未列出。您可以在 Marketplace SDK 的「應用程式設定」頁面中，切換外掛程式是否列出。

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

6. Google Workspace Marketplace 團隊會審查您的應用程式。他們會使用 Marketplace SDK 中指定的開發人員電子郵件地址與您聯絡。應用程式獲得核准後，請取消勾選「未列出」方塊，這樣老師和管理員就能在 Marketplace 中找到該應用程式。

建立私有 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 控制台。

   如果無法存取 Google Cloud 控制台或建立 Cloud 專案，請在 管理控制台中檢查下列事項：

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

3. 填寫並提交示範網域升級申請表單。提交這份表單後，Google 會將您的示範網域升級至 Google Workspace for Education Plus，並提供十個授權，同時允許您的 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」「App Visibility」設為「private」。

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

OAuth 2.0

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

重要事項： 如果外掛程式要求額外範圍，請將這些範圍納入 OAuth 同意畫面、Marketplace SDK 應用程式設定分頁，以及外掛程式的應用程式程式碼。如果這些位置的範圍不符，使用者在安裝外掛程式時可能會遇到問題。

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

警告： 如果您使用現有的 Google Cloud 專案開發外掛程式，請勿在現有產品的程式碼中要求新範圍，直到驗證完成為止。完成驗證前，請使用獨立的授權流程、測試環境，或設定功能旗標，只為外掛程式相關路徑要求這些範圍。

如需所有可用範圍及其用途的詳細清單，請參閱「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。

警告： 應用程式必須要求至少一個 userinfo.email 或 userinfo.profile 範圍，才能在同一位使用者後續造訪時收到 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 驗證

注意： 您無法建立示範影片，並在 OAuth 驗證程序中提交。請發布外掛程式，但不要驗證 OAuth。Google Workspace Marketplace 審查團隊收到通知後，就會代表您製作示範影片。審查團隊會將影片提供給您，以便納入 OAuth 驗證申請。

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

• 驗證品牌識別。
• 驗證機密 OAuth 範圍。

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

Google Workspace Marketplace 資訊

警告： 發布期間儲存瀏覽權限選項後，就無法再變更選取項目。

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

商店資訊注意事項

公開 Google Cloud 專案的 Marketplace SDK 商店資訊會指定應用程式名稱和說明，供使用者參考。你可以在「應用程式詳細資料」下方，以多種語言提供這些詳細資料。

請依照下列準則在商家資訊中進行設定：

• 在「應用程式詳細資料」下方：
  • 應用程式名稱中請勿使用標點符號。舉例來說，請使用「My Add-on by My Company」，而非「My Company: My Add-on」或「My Add-on, by My Company」。
  • 簡短說明和詳細說明不得包含完全相同的文字。
  • 確認已選取「價格」欄位的值。這個欄位包含「免費」、「須付費，但可免費試用」、「須付費，但提供免費功能」和「付費」價格選項。您不需要在 Marketplace 資訊中指定費用金額。
  • 確認已為「類別」欄位選取值。 學術資源或老師和管理員工具可能很適合做為 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 尋找要附加到作業的內容或活動。您可以在 Google Cloud 專案控制台中設定。

「可使用的附件 URI 前置字串」可用來驗證 AddOnAttachment 中使用 *.addOnAttachments.create 和 *.addOnAttachments.patch 方法設定的 URI。驗證是字串前置字元完全相符，不允許使用萬用字元。

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

請在 Google Cloud 專案的 Marketplace SDK「應用程式設定」頁面中，設定這兩個值。

測試帳戶

在示範網域中建立測試帳戶，確認私人外掛程式的行為是否正確。如要在「學生作業審查」iframe 中測試切換學生，需要兩個學生帳戶。

建議的測試帳戶：

• 譚老師 (tammy.teacher@<您的示範網域>)
• Sam Student，sam.student@<您的示範網域>
• Sally Student，sally.student@<您的示範網域>

請按照下列程序建立新的測試帳戶：

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

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

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

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

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