Nộp tệp đính kèm bên ngoài và nộp

Đây là hướng dẫn hướng dẫn thứ bảy trong loạt hướng dẫn từng bước về tiện ích bổ sung trên Google 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 của tiện ích bổ sung từ bên ngoài Google Lớp học. 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 tính năng bổ sung tuyệt vời cho việc tích hợp CourseWork vì bạn hướng lưu lượng truy cập hiện có đến trải nghiệm người dùng được cải tiến do tiện ích bổ sung của bạn cung cấp mà không làm thay đổi luồng của chúng. Quy trình đề xuất được trình bày 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 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 của tiện ích bổ sung theo phương thức lập trình. Bạn có thể sửa đổi bất kỳ bài tập nào có một trong các tệp đính kèm của tiện ích bổ sung, bất kể ai đã tạo bài tập đó. Tính năng này đặc biệt hữu ích khi nộp bài tập sau khi học viên hoàn thành một hoạt động, cho giáo viên biết rằng các nhiệm vụ được giao đã hoàn tất và bài tập của học viên đã sẵn sàng để 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ợ tệp đính kèm loại nội dung hoặc tệp đính kèm loại hoạt động. Tệp đính kèm loại nội dung được sử 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

Phạm vi classroom.coursework.students trước đây không cần thiết và đượ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 SDK Google Workspace Marketplace, màn hình đồng ý OAuth và mã máy chủ của dự án trên Google Cloud.

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 một 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 trên Google Lớp học từ một sản phẩm không phải của Google. Trong 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 nhấp vào, sẽ mở một tuyến mới thực hiện quy trình CourseWork được đề xuất để 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 xác thực 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ề cách đă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 /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ẫ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.

<!-- /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 liên quan đến CourseWork. Đây là coursework_routes.py trong ví dụ chúng tôi cung cấp. Thêm ba tuyến 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 điều kiện tạo tệp đính kèm của người dù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ể thay mặt họ tạo tệp đính kèm tiện ích bổ sung. Để 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 bước 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 người dùng đủ điều kiện, hãy làm theo logic để tạo bài tập có các tệp đính kèm tiện ích bổ sung. Nếu không, hãy tạo một Tài liệu liên kết. Bạn cần biết mã 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 hoá, chúng tôi sử dụng một giá trị được cố định giá trị 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 bằng 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:

  1. Gửi yêu cầu API để tạo bài tập courseWork trong Google Lớp học mà không có tệp đính kèm.
  2. Trích xuất id của bài tập mới tạo.
  3. Tạo một CourseWork AddOnAttachment mới.
  4. Gửi yêu cầu tạo tệp đính kèm bằng 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()
  )

Nếu người dùng không đủ điều kiện để tạo tệp đính kèm có tiện ích bổ sung, hãy tạo Tài liệu liên kết 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ội dung phát trực tiếp nào trên Google Lớp học có ít nhất một tệp đính kèm của tiện ích bổ sung, bất kể ai đã tạo mục nội dung phát trực tiếp đó. Mục trong luồng là bất kỳ bài tập Announcement, CourseWork hoặc CourseWorkMaterial nào.

Để chứng minh điều này, bạn sẽ thêm một tuyến để 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 trong 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 trong hướng dẫn này. Thao tác này sẽ mở một tuyến đường mới để sửa đổi một nhiệm vụ CourseWork.

Python

Ví dụ về Python được cung cấp sẽ sửa đổi tuyến /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 mới để xử lý các tuyến liên quan đến CourseWork. Tệp này nằm trong 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, các ví dụ được cung cấp sẽ sử dụng giá trị nhận dạng khoá học và bài tập được mã hoá cứng. Bạn có thể lấy 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 đăng nhập của giáo viên vào phương thức get và list của các 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.

Chạy máy chủ của bạn, sau đó chuyển đến trang chỉ mục rồi đă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ể bật/tắt trạng thái giấy phép của người dùng trong Bảng điều khiển dành cho quản trị viên của miền thử nghiệm.Nhấp vào nút Tạo bài tập về 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 bạn đã tạo một bài tập có tệp đính kèm Tài liệu liên kết. Tệp đính kèm phải cho thấy tiêu đề của trang web được liên kết và URL.

Kiểm thử 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 dưới vai trò là người dùng giáo viên có giấy phép Teaching & Learning hoặc Plus của Google Workspace for Education. 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 bạn đã tạo một bài tập có tệp đính kèm tiện ích bổ sung. Tệp đính kèm phải hiển thị tên của ứng dụng bổ sung và tiêu đề được chỉ định trong mã của bạn.

Sửa đổi bài tập kiểm thử

Quay lại trang chỉ mục và đảm bảo rằng 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 and 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 loạt bài viết hướng dẫn.