Đây là hướng dẫn thứ bảy trong loạt hướng dẫn về tiện ích bổ sung Lớp học.
Trong hướng dẫn này, bạn sẽ thêm hành vi vào một ứng dụng web để tạo tệp đính kèm tiện ích bổ sung bên ngoài Google Lớp học. Hãy sử dụng hành vi này để cho phép người dùng tạo tệp đính kèm tiện ích bổ sung từ sản phẩm hoặc trang web hiện có của bạn. Đây cũng là một điểm bổ sung tuyệt vời cho hoạt động tích hợp CourseWork
vì bạn chuyển hướng lưu lượng truy cập hiện tại đến trải nghiệm người dùng được cải thiện do tiện ích bổ sung của bạn cung cấp mà không làm thay đổi quy trình của họ. Quy trình được đề xuất có trong trang hướng dẫn Tạo tệp đính kèm bên ngoài Lớp học.
Bạn cũng có thể thêm hành vi vào tiện ích bổ sung để sửa đổi bài tập bằng tệp đính kèm tiện ích bổ sung theo phương thức lập trình. Bạn có thể sửa đổi mọi bài tập có một trong các tệp đính kèm tiện ích bổ sung của bạn, bất kể ai tạo bài tập đó. Tính năng này đặc biệt hữu ích khi học viên nộp bài tập sau khi hoàn thành một hoạt động, báo hiệu cho giáo viên rằng học viên đã hoàn thành các nhiệm vụ được giao và bài tập của học viên đã sẵn sàng để được xem xét.
Bạn mở rộng phiên bản cuối cùng của tiện ích bổ sung hỗ trợ content-type hoặc tệp đính kèm activity-type. Tệp đính kèm content-type được dùng trong hướng dẫn này.
Thêm phạm vi OAuth quản lý bài tập
Đảm bảo rằng ứng dụng của bạn yêu cầu các phạm vi sau:
https://www.googleapis.com/auth/classroom.addons.teacher
https://www.googleapis.com/auth/classroom.addons.student
https://www.googleapis.com/auth/classroom.coursework.students
Trước đây, bạn không cần đến phạm vi classroom.coursework.students
và phạm vi này được dùng để tạo hoặc sửa đổi các chỉ định CourseWork
. Thêm phạm vi này vào danh sách phạm vi trong Google Workspace Marketplace SDK, màn hình đồng ý OAuth và mã máy chủ của dự án trên đám mây.
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",
]
Tạo bài tập trong Lớp học
Thêm nút vào trang web không có iframe
Quy trình được mô tả trong hướng dẫn này cho phép người dùng tạo bài tập và tệp đính kèm trong Google Lớp học từ một sản phẩm không phải của Google. Trên thực tế, đây có thể là trang web hoặc ứng dụng hiện có của bạn. Đối với ví dụ này, bạn cần tạo một trang web mô phỏng để đóng vai trò là một trang web bên ngoài. Bạn cần một nút hoặc đường liên kết mà khi người dùng nhấp vào, sẽ mở một tuyến đường mới thực hiện quy trình đề xuấtCourseWork
để tạo một bài tập mới.
Bạn cũng cần thêm một nút hoặc đường liên kết để cho phép người dùng đăng nhập nếu chưa có. Bạn sẽ cần thông tin đăng nhập của người dùng để thực hiện các yêu cầu API tiếp theo, vì vậy, họ phải hoàn tất quy trình bắt tay OAuth 2.0. Hãy xem hướng dẫn từng bước về quy trình đăng nhập để biết hướng dẫn cụ thể.
Python
Ví dụ về Python được cung cấp sẽ sửa đổi tuyến đường /index
đã được giới thiệu trong bước đầu tiên của hướng dẫn.
<!-- /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>
Thêm một mẫu HTML để đại diện cho một đích đến trong trang web của bạn. Trang này sẽ đại diện cho nội dung sẽ được đính kèm vào bài tập CourseWork
của bạn.
<!-- /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>
Tạo một tệp mô-đun Python mới để xử lý các tuyến đường liên quan đến CourseWork.
Đây là coursework_routes.py
trong ví dụ mà chúng tôi cung cấp. Thêm 3 tuyến đường sau; lưu ý rằng bạn sẽ điền một số nội dung sau.
# /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")
Kiểm tra xem người dùng có đủ điều kiện tạo tệp đính kèm hay không
Người dùng phải đáp ứng một số điều kiện tiên quyết thì bạn mới có thể tạo tệp đính kèm bổ sung thay cho họ. Để thuận tiện, Google cung cấp phương thức userProfiles.checkUserCapability
để xác định xem người dùng có đáp ứng các điều kiện tiên quyết này hay không. Người dùng đáp ứng các điều kiện tiên quyết được gọi là người dùng đủ điều kiện.
Thêm quy trình kiểm tra điều kiện vào quá trình triển khai tuyến tạo CourseWork
.
Sau đó, hãy kiểm thử trường allowed
trong phản hồi. Đối với những người dùng đủ điều kiện, hãy làm theo logic để tạo một bài tập có tệp đính kèm bổ sung. Nếu không, hãy tạo một Link
Material. Bạn cần biết mã nhận dạng của khoá học mà người dùng muốn tạo bài tập. Thông thường, bạn sẽ nhắc người dùng chỉ định khoá học cần sử dụng. Để đơn giản, chúng ta sẽ sử dụng một giá trị được cố định trong mã trong ví dụ này.
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 ...
# Check whether the user can create add-on attachments.
eligibility_response = (
classroom_service.userProfiles()
.checkUserCapability(
userId="me",
capability="CREATE_ADD_ON_ATTACHMENT",
# The previewVersion is necessary while the method is available in the
# Workspace Developer Preview Program.
previewVersion="V1_20240930_PREVIEW",
).execute()
)
is_create_attachment_eligible = eligibility_response.get("allowed")
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.
Tạo bài tập có tệp đính kèm tiện ích bổ sung cho người dùng đủ điều kiện
Nếu người dùng đủ điều kiện tạo tệp đính kèm có tiện ích bổ sung, hãy làm như sau:
- Gửi yêu cầu API để tạo bài tập
courseWork
trong Google Lớp học không có tệp đính kèm. - Trích xuất
id
của bài tập mới tạo. - Tạo một CourseWork
AddOnAttachment
mới. - Gửi yêu cầu tạo tệp đính kèm tiện ích bổ sung cho bài tập mới tạo trong Google Lớp học.
Python
# The ID of the course to which the assignment will be added.
course_id = 1234567890 # TODO(developer) Replace with an actual course ID.
# /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()
)
Tạo một Tài liệu liên kết
Nếu người dùng không đủ điều kiện để tạo tệp đính kèm bổ sung, hãy tạo một Link Material thay thế bằng cách làm như sau:
Python
# The ID of the course to which the assignment will be added.
course_id = 1234567890 # TODO(developer) Replace with an actual course ID.
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()
)
Sửa đổi bài tập đã tạo
Bạn có thể truy cập, sửa đổi, nộp, lấy lại hoặc trả lại bất kỳ mục nào trên luồng trong Google Lớp học có ít nhất một tệp đính kèm bổ sung của bạn, bất kể ai đã tạo mục đó trên luồng. Mục trên bảng tin là bất kỳ Announcement
, CourseWork
bài tập hoặc CourseWorkMaterial
nào.
Để minh hoạ điều này, bạn sẽ thêm một tuyến đường để sửa đổi một mục cụ thể trong luồng. Sử dụng phương thức này để xác minh rằng bạn có thể truy cập và sửa đổi các mục trên luồng do bạn tạo bằng API và do giáo viên tạo thông qua giao diện người dùng Google Lớp học.
Thêm một đường liên kết hoặc nút khác vào trang web mà bạn chỉnh sửa lần đầu tiên trong hướng dẫn này. Thao tác này sẽ mở một tuyến đường mới để sửa đổi bài tập CourseWork
.
Python
Ví dụ về Python được cung cấp sẽ sửa đổi tuyến đường /index
đã được sửa đổi trước đó trong hướng dẫn này.
<!-- /webapp/templates/index.html -->
<a href="modify-coursework-assignment.html">Create a CourseWork Assignment</a>
Tạo một tuyến đường mới để xử lý các tuyến đường liên quan đến CourseWork. Đây là tệp coursework_routes.py
trong ví dụ mà chúng tôi cung cấp.
# 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()
)
Kiểm thử tiện ích bổ sung
Để đơn giản hoá, các ví dụ được cung cấp sẽ sử dụng mã nhận dạng khoá học và bài tập được mã hoá cứng. Bạn có thể nhận được các giá trị nhận dạng này bằng cách đưa ra yêu cầu bằng thông tin xác thực của giáo viên cho các phương thức get
và list
của tài nguyên courses
và courseWork
. Các giá trị này cũng được trả về trong phản hồi khi tạo bài tập courseWork
.
Kiểm thử việc tạo tài liệu liên kết
Chạy máy chủ của bạn, sau đó chuyển đến trang chỉ mục và đăng nhập với tư cách là người dùng giáo viên không có giấy phép Teaching & Learning hoặc Plus của Google Workspace for Education. Bạn có thể chuyển đổi trạng thái giấy phép của người dùng trong bảng điều khiển Quản trị của miền kiểm thử.Nhấp vào nút Tạo bài tập trên lớp, sau đó mở giao diện người dùng Google Lớp học và xác minh rằng một bài tập có tệp đính kèm Tài liệu liên kết đã được tạo. Tệp đính kèm phải cho thấy tiêu đề của trang web được liên kết và một URL.
Thử nghiệm việc tạo tệp đính kèm của tiện ích bổ sung
Quay lại trang chỉ mục rồi đăng nhập với tư cách là người dùng giáo viên có giấy phép Google Workspace for Education Teaching & Learning hoặc Plus. Nhấp vào nút Tạo bài tập trên lớp, sau đó mở giao diện người dùng Google Lớp học và xác minh rằng một bài tập có tệp đính kèm bổ trợ đã được tạo. Tệp đính kèm phải cho thấy tên của ứng dụng bổ trợ và tiêu đề được chỉ định trong mã của bạn.
Sửa đổi bài kiểm tra
Quay lại trang chỉ mục và đảm bảo bạn đã đăng nhập với tư cách là người dùng giáo viên có giấy phép Teaching & Learning hoặc Plus. Nhấp vào nút Sửa đổi bài tập trong khoá học, sau đó quay lại giao diện người dùng Google Lớp học và xác minh rằng tiêu đề bài tập đã được thay đổi.
Xin chúc mừng! Bạn đã hoàn thành chuỗi hướng dẫn này.