這是 Classroom 外掛程式逐步操作說明系列中的 seventh 逐步操作說明。
在本逐步操作說明中，您將在網頁應用程式中新增行為，以從 Google Classroom 以外的位置建立外掛程式連結。請使用這項行為，讓使用者從您現有的產品或網站建立外掛程式附件。這也很適合做為 CourseWork 整合，因為您可以在不變更流程的情況下，將現有流量導向外掛程式提供的改善使用者體驗。如要瞭解相關建議程序，請參閱「在 Classroom 以外建立附件」指南頁面。
此外，您也可以在外掛程式中新增行為，透過程式輔助方式修改含有外掛程式附件的作業。您可以修改任何含有外掛程式附件的指派作業，無論指派者是誰。這特別適合在學生完成活動後繳交作業，告知老師指派的工作已完成，且學生的作業已準備好進行審查。
您擴充支援 content-type 或活動類型附件的外掛程式的最終版本。本指南會使用 content-type 附件。
新增指派管理 OAuth 範圍
請確認您的應用程式要求下列範圍：
https://www.googleapis.com/auth/classroom.addons.teacherhttps://www.googleapis.com/auth/classroom.addons.studenthttps://www.googleapis.com/auth/classroom.coursework.students
先前不需要 classroom.coursework.students 範圍，可用來建立或修改 CourseWork 指派作業。將此範圍新增至 Cloud 專案的 Google Workspace Marketplace SDK、OAuth 同意畫面和伺服器程式碼中的範圍清單。
Python
SCOPES = [
"https://www.googleapis.com/auth/classroom.addons.teacher",
"https://www.googleapis.com/auth/classroom.addons.student",
"https://www.googleapis.com/auth/classroom.coursework.students",
]
在 Classroom 中建立作業
在非 iframe 網頁中加入按鈕
本逐步操作說明所述的流程可讓使用者從非 Google 產品建立 Google Classroom 作業和附件。實際上，這可能是您現有的網站或應用程式。在本例中，您需要建立模擬網頁做為外部網站使用。您需要按鈕或連結，點選後會開啟新路徑，以便執行建議的 CourseWork 流程建立新的指派作業。
如果您沒有按鈕或連結，您還必須新增按鈕或連結讓使用者登入帳戶。您需要使用者憑證才能發出後續 API 要求，因此這些要求必須完成 OAuth 2.0 握手程序。如需詳細指南，請參閱登入逐步操作說明。
Python
提供的 Python 範例會修改第一個逐步操作說明中引入的 /index 路徑。
<!-- /webapp/templates/index.html -->
<a href="clear-credentials.html">Logout</a>
<a href="start-auth-flow.html">Login</a>
<br>
<a href="create-coursework-assignment.html">Create a CourseWork Assignment</a>
新增 HTML 範本來代表網站上的目的地。本頁面將代表會附加至 CourseWork 指派的內容。
<!-- /webapp/templates/example-coursework-assignment.html -->
<h1>CourseWork assignment loaded!</h1>
<p>You've loaded a CourseWork assignment! It was created from an external web page.</p>
建立新的 Python 模組檔案，以處理 CourseWork 相關路徑。這是我們提供的範例中的 coursework_routes.py。新增以下三個路徑。請注意，您稍後會填入部分內容。
# /webapp/coursework_routes.py
@app.route("/create-coursework-assignment")
def create_coursework_assignment():
"""
Completes the assignment creation flow.
"""
# Check that the user is signed in. If not, perform the OAuth 2.0
# authorization flow.
credentials = get_credentials()
if not credentials:
return start_auth_flow("coursework_assignment_callback")
# Construct the Google Classroom service.
classroom_service = get_classroom_service()
pass # To be completed later.
@app.route("/example-coursework-assignment/<assignment_type>")
def example_coursework_assignment(assignment_type):
"""
Renders the "example-coursework-assignment.html" template.
"""
return flask.render_template(
"example-coursework-assignment.html", assignment_type=assignment_type
)
@app.route("/coursework-assignment-callback")
def coursework_assignment_callback():
"""
Completes the OAuth 2.0 handshake and stores credentials in the session.
This is identical to the callback introduced in the sign-in walkthrough,
but redirects the user to the index page instead of the attachment
discovery page.
"""
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
CLIENT_SECRETS_FILE,
scopes=SCOPES,
state=flask.session["state"],
redirect_uri=flask.url_for("coursework_assignment_callback", _external=True),
)
flow.fetch_token(authorization_response=flask.request.url)
credentials = flow.credentials
flask.session["credentials"] = session_credentials_to_dict(
credentials
)
# Close the current window and redirect the user to the index page.
return flask.render_template("close-me.html", redirect_destination="index")
確認使用者的外掛程式建立資格
您必須符合幾項必要條件，才能代表他們建立外掛程式連結。為了方便起見，Google 提供 courses.checkAddOnCreationEligibility 方法，判斷使用者是否符合這些先決條件。符合必要條件的使用者稱為「符合資格」的使用者。
將資格檢查加入 CourseWork 建立路徑實作中。然後測試回應中的 isCreateAttachmentEligible 欄位。針對符合資格的使用者，請按照邏輯建立含有外掛程式連結的指派作業。否則，請建立連結 Material。您需要知道使用者要在其中建立作業的課程 ID。通常情況下，系統會提示使用者指定要使用的課程。為求簡單起見，在此範例中使用硬式編碼值。
Python
# /webapp/coursework_routes.py
@app.route("/create-coursework-assignment")
def create_coursework_assignment():
"""
Completes the assignment creation flow.
"""
# ... Check that the user is signed in and get the Classroom service ...
# The ID of the course to which the assignment will be added.
course_id = 1234567890 # TODO(developer) Replace with an actual course ID.
# Check whether the user can create add-on attachments.
eligibility_response = (
classroom_service.courses()
.checkAddOnCreationEligibility(courseId=course_id)
.execute()
)
is_create_attachment_eligible = eligibility_response.get("isCreateAttachmentEligible")
if is_create_attachment_eligible:
# See the "Create an assignment with add-on attachment for eligible users" section for implementation.
if not is_create_attachment_eligible:
# See the "Create a Link Material" section for implementation.
為符合資格的使用者建立含有外掛程式附件的作業
如果使用者符合建立外掛程式附件的資格，請按照下列步驟操作：
- 傳送 API 要求，在 Google Classroom 中建立具有無附件的
courseWork作業。 - 擷取新建立作業的
id。 - 建構新的 CourseWork
AddOnAttachment。 - 傳送要求，在 Google Classroom 中新建立的作業上建立外掛程式附件。
Python
# /webapp/coursework_routes.py
if is_create_attachment_eligible:
# Create an assignment.
coursework = {
"title": "My CourseWork Assignment with Add-on Attachment",
"description": "Created using the Classroom CourseWork API.",
"workType": "ASSIGNMENT",
"state": "DRAFT", # Set to 'PUBLISHED' to assign to students.
}
# Issue a request to create the assignment.
create_assignment_response = (
classroom_service.courses()
.courseWork()
.create(courseId=course_id, body=coursework)
.execute()
)
# Create an add-on attachment that links to the selected content and
# associate it with the new assignment.
content_url = flask.url_for(
"example_coursework_assignment",
assignment_type="add-on-attachment",
_scheme="https",
_external=True,
)
# Construct an AddOnAttachment instance.
attachment = {
"teacherViewUri": {"uri": content_url},
"studentViewUri": {"uri": content_url},
"title": f'Test Attachment for Assignment {create_assignment_response.get("id")}',
}
# Issue a request to create the attachment.
add_on_attachment_response = (
classroom_service.courses()
.courseWork()
.addOnAttachments()
.create(
courseId=course_id,
itemId=create_assignment_response.get("id"), # ID of the new assignment.
body=attachment,
)
.execute()
)
建立連結資料
如果使用者「不符合」建立外掛程式附件的資格，請改為建立連結 Material，步驟如下：
Python
if not is_create_attachment_eligible:
coursework = {
"title": "My CourseWork Assignment with Link Material",
"description": "Created using the Classroom CourseWork API.",
"workType": "ASSIGNMENT",
"state": "DRAFT", # Set to 'PUBLISHED' to assign to students.
# Specify the URL for your content as a Link Material.
"materials": [
{
"link": {
"url": flask.url_for(
"example_coursework_assignment",
assignment_type="link-material",
_scheme="https",
_external=True,
)
}
}
],
}
# Issue a request to create the assignment.
assignment_response = (
classroom_service.courses()
.courseWork()
.create(courseId=course_id, body=coursework)
.execute()
)
修改已建立的作業
您可以存取、修改、繳交、收回或傳回任何含有至少一個外掛程式附件的 Google Classroom 串流項目，無論該串流項目是由誰建立皆然。串流項目可以是任何 Announcement、CourseWork 指派作業或 CourseWorkMaterial。
為示範此操作，您必須新增路徑來修改特定串流項目。請使用這個方法確認您可以存取及修改自己透過 API 建立的串流項目，以及老師透過 Google Classroom UI 建立的串流項目。
在本逐步操作說明中首次編輯的網頁，新增一個連結或按鈕。系統應開啟新的路徑，才能修改 CourseWork 指派作業。
Python
提供的 Python 範例會修改先前在本逐步操作說明中修改的 /index 路徑。
<!-- /webapp/templates/index.html -->
<a href="modify-coursework-assignment.html">Create a CourseWork Assignment</a>
建立新路徑來處理 CourseWork 相關路線。這位於我們提供的範例的 coursework_routes.py 檔案中。
# Check that the user is signed in.
credentials = get_credentials()
if not credentials:
return start_auth_flow("coursework_assignment_callback")
# Get the Google Classroom service.
classroom_service = get_classroom_service()
# The ID of the course to which the assignment will be added.
# Ordinarily, you'll prompt the user to specify which course to use. For
# simplicity, we use a hard-coded value in this example.
course_id = 1234567890 # TODO(developer) Replace with an actual course ID.
assignment_id = 1234567890 # TODO(developer) Replace with an actual assignment ID.
# Retrieve details about the CourseWork assignment.
get_coursework_response = (
classroom_service.courses()
.courseWork()
.get(courseId=course_id, id=assignment_id)
.execute()
)
# Alter the current title.
assignment_title = f"{get_coursework_response.get('title')} (Modified by API request)"
# Issue a request to modify the assignment.
modify_coursework_response = (
classroom_service.courses()
.courseWork()
.patch(
courseId=course_id,
id=assignment_id,
updateMask="title",
body={"title": assignment_title},
)
.execute()
)
測試外掛程式
為求簡單起見，我們提供的範例使用了硬式編碼課程和指派 ID。如要取得這些 ID，您可以向 courses 和 courseWork 資源的 get 和 list 方法提出使用老師憑證的要求。建立 courseWork 指派作業時，也會在回應中傳回這些權杖。
測試連結素材建立作業
執行伺服器，前往索引頁面，然後以老師身分登入「沒有 Google Workspace for Education Teaching and Learning 或 Plus 授權」。您可以在測試網域的管理控制台中切換使用者的授權狀態。按一下「Create a CourseWork Assignment」按鈕，開啟 Google Classroom UI，並確認已建立含有連結 Material 附件的作業。附件應顯示連結網頁的標題和網址。
測試外掛程式附件建立作業
返回索引頁面，然後以老師身分登入具備 Google Workspace for Education Teaching and Learning 或 Plus 授權的老師。按一下 [Create a CourseWork Assignment] 按鈕，開啟 Google Classroom UI，並確認已建立含有外掛程式附件的作業。該附件應會顯示外掛程式應用程式名稱以及程式碼中指定的標題。
測試作業的修改內容
返回索引頁面，確認您已以老師身分登入，並擁有 Teaching and Learning 或 Plus 授權。按一下「Modify a CourseWorkAssignment」按鈕，返回 Google Classroom UI，確認作業標題已變更。
恭喜！您已完成逐步操作說明系列課程。