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

Đây là phần hướng dẫn thứ bảy trong loạt bài hướng dẫn về tiện ích bổ sung cho Lớp học.

Trong phần 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. Hãy sử dụng hành vi này để cho phép người dùng tạo tệp đính kèm của tiện ích bổ sung từ trang web hoặc sản phẩm 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 có thể chuyể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 thiện do tiện ích bổ sung của bạn cung cấp mà không cần thay đổi quy trình của họ. Quy trình được đề xuất được trình bày trên 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 có 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 để nộp bài tập sau khi học viên hoàn thành một hoạt động, báo hiệu cho giáo viên rằng các nhiệm vụ được giao đã hoàn tất và bài làm 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 thuộc loại nội dung hoặc loại hoạt động. Tệp đính kèm thuộc 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

Trước đây, bạn không cần phạm vi classroom.coursework.students và phạm vi này được dùng để tạo hoặc sửa đổi bài tập CourseWork. Thêm phạm vi này vào danh sách phạm vi trong SDK Google Workspace Marketplace của dự án trên Google Cloud , màn hình xin phép bằng OAuth và mã máy chủ của bạn.

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 nhúng iframe

Quy trình được mô tả trong phần 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 đường mới thực hiện quy trình được đề xuất CourseWorkđể 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 bạn 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 phần hướng dẫn đăng nhập đă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 hướng dẫn đầu tiê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.

<!-- /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ụ được 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 điều kiện tạo tệp đính kèm của người dùng

Có một số điều kiện tiên quyết mà người dùng phải đáp ứng trước khi bạn có thể tạo tệp đính kèm của tiện ích bổ sung thay mặt 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 bước kiểm tra điều kiện vào quá trình triển khai tuyến đường 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 của tiện ích bổ sung tệp đính kèm. Nếu không, hãy tạo 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, chúng tôi sử dụng một giá trị được mã hoá cứng 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 của 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ủa 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 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 của tiện ích bổ sung trên 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ủa 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, thu hồi hoặc trả lại bất kỳ mục luồng 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 luồng đó. Mục luồng là bất kỳ Announcement, CourseWork bài tập hoặc CourseWorkMaterial.

Để minh hoạ điều này, bạn sẽ thêm một tuyến đường để sửa đổi một mục luồng nhất định. 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 luồng do bạn tạo bằng API 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 phần hướng dẫn này. Đường liên kết hoặc nút đó 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 phần 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. Tuyến đường này nằm trong tệp coursework_routes.py trong ví dụ được 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ử dụng mã 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 mã nhận dạng này bằng cách đưa ra yêu cầu có thông tin xác thực của giáo viên đối với các phương thức getlist của tài nguyên coursescourseWork. Các mã nhận dạng 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ủ, sau đó chuyển đến trang chỉ mục và đăng nhập với tư cách người dùng là 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 miền kiểm thử Bảng điều khiển dành cho quản trị viên.Nhấp vào nút Tạo bài tập CourseWork, 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 sẽ hiển thị tiêu đề của trang web được liên kết và một 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 và đăng nhập với tư cách người dùng là 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 CourseWork, 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 của tiện ích bổ sung đã được tạo. Tệp đính kèm sẽ hiển thị tên của ứng dụng tiện ích bổ sung và tiêu đề được chỉ định trong mã của bạn.

Kiểm thử việc sửa đổi bài tập

Quay lại trang chỉ mục và đảm bảo rằng bạn đã đăng nhập với tư cách người dùng là 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 CourseWork, 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 tất loạt bài hướng dẫn.