Tệp đính kèm loại nội dung

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

Trong hướng dẫn này, bạn sẽ tương tác với API Google Lớp học để tạo tệp đính kèm. Bạn cung cấp các tuyến đường để người dùng xem nội dung tệp đính kèm. Các chế độ xem khác nhau tuỳ thuộc vào vai trò của người dùng trong lớp học. Hướng dẫn này đề cập đến tệp đính kèm thuộc loại nội dung, không yêu cầu học viên nộp bài.

Trong quá trình thực hiện hướng dẫn này, bạn sẽ hoàn tất những việc sau:

  • Truy xuất và sử dụng các tham số truy vấn tiện ích bổ sung sau:
    • addOnToken: Mã thông báo uỷ quyền được truyền đến Chế độ xem khám phá tệp đính kèm.
    • itemId: Giá trị nhận dạng duy nhất cho CourseWork, CourseWorkMaterial hoặc Thông báo nhận tệp đính kèm tiện ích bổ sung.
    • itemType: "courseWork", "courseWorkMaterials" hoặc "announcement".
    • courseId: Giá trị nhận dạng duy nhất cho khoá học trên Google Lớp học mà bài tập đang được tạo.
    • attachmentId: Giá trị nhận dạng duy nhất do Google Lớp học chỉ định cho tệp đính kèm tiện ích bổ sung sau khi tạo.
  • Triển khai bộ nhớ liên tục cho tệp đính kèm thuộc loại nội dung.
  • Cung cấp các tuyến đường để tạo tệp đính kèm và phân phát iframe Chế độ xem của giáo viên và Chế độ xem của học viên.
  • Gửi các yêu cầu sau đến API tiện ích bổ sung cho Google Lớp học:
    • Tạo tệp đính kèm mới.
    • Nhận bối cảnh tiện ích bổ sung, xác định xem người dùng đã đăng nhập là học viên hay giáo viên.

Sau khi hoàn tất, bạn có thể tạo tệp đính kèm thuộc loại nội dung trên bài tập thông qua giao diện người dùng Google Lớp học khi đăng nhập với tư cách là giáo viên. Giáo viên và học viên trong lớp cũng có thể xem nội dung.

Bật API Lớp học

Bắt đầu gọi API Lớp học từ bước này. Bạn phải bật API cho dự án trên đám mây của Google thì mới có thể gọi API đó. Chuyển đến mục nhập thư viện API Google Lớp học rồi chọn Bật.

Xử lý các tham số truy vấn Chế độ xem khám phá tệp đính kèm

Như đã thảo luận trước đó, Google Lớp học sẽ truyền các tham số truy vấn khi tải Chế độ xem khám phá tệp đính kèm trong iframe:

  • courseId: Mã của khoá học hiện tại trên Lớp học.
  • itemId: Giá trị nhận dạng duy nhất cho CourseWork, CourseWorkMaterial hoặc Thông báo nhận tệp đính kèm tiện ích bổ sung.
  • itemType: "courseWork", "courseWorkMaterials" hoặc "announcement".
  • addOnToken: Mã thông báo dùng để uỷ quyền cho một số hành động của tiện ích bổ sung cho Lớp học.
  • login_hint: Mã Google của người dùng hiện tại.

Hướng dẫn này đề cập đến courseId, itemId, itemType và addOnToken. Giữ lại và truyền các tham số này khi đưa ra lệnh gọi đến API Lớp học.

Như trong bước hướng dẫn trước, hãy lưu trữ các giá trị tham số truy vấn đã truyền trong phiên của chúng ta. Điều quan trọng là chúng ta phải thực hiện việc này khi Chế độ xem khám phá tệp đính kèm được mở lần đầu tiên, vì đây là cơ hội duy nhất để Lớp học truyền các tham số truy vấn này.

Python

Chuyển đến tệp máy chủ Flask cung cấp các tuyến đường cho Chế độ xem khám phá tệp đính kèm (attachment-discovery-routes.py nếu bạn đang làm theo ví dụ mà chúng tôi cung cấp). Ở đầu tuyến đường đích của tiện ích bổ sung (/classroom-addon trong ví dụ mà chúng tôi cung cấp), hãy truy xuất và lưu trữ các tham số truy vấn courseId, itemId, itemType và addOnToken.

# Retrieve the itemId, courseId, and addOnToken query parameters.
if flask.request.args.get("itemId"):
    flask.session["itemId"] = flask.request.args.get("itemId")
if flask.request.args.get("itemType"):
    flask.session["itemType"] = flask.request.args.get("itemType")
if flask.request.args.get("courseId"):
    flask.session["courseId"] = flask.request.args.get("courseId")
if flask.request.args.get("addOnToken"):
    flask.session["addOnToken"] = flask.request.args.get("addOnToken")

Chỉ ghi các giá trị này vào phiên nếu chúng có mặt; các giá trị này sẽ không được truyền lại nếu người dùng quay lại Chế độ xem khám phá tệp đính kèm sau đó mà không đóng iframe.

Thêm bộ nhớ liên tục cho tệp đính kèm thuộc loại nội dung

Bạn cần có bản ghi cục bộ của mọi tệp đính kèm đã tạo. Điều này cho phép bạn tra cứu nội dung mà giáo viên đã chọn bằng cách sử dụng giá trị nhận dạng do Lớp học cung cấp.

Thiết lập lược đồ cơ sở dữ liệu cho Attachment. Ví dụ mà chúng tôi cung cấp trình bày các tệp đính kèm hiển thị hình ảnh và chú thích. Attachment chứa các thuộc tính sau:

  • attachment_id: Giá trị nhận dạng duy nhất cho tệp đính kèm. Do Lớp học chỉ định và trả về trong phản hồi khi tạo tệp đính kèm.
  • image_filename: Tên tệp cục bộ của hình ảnh cần hiển thị.
  • image_caption: Chú thích hiển thị cùng với hình ảnh.

Python

Mở rộng việc triển khai SQLite và flask_sqlalchemy từ các bước trước.

Chuyển đến tệp mà bạn đã xác định Bảng người dùng (models.py nếu bạn đang làm theo ví dụ mà chúng tôi cung cấp). Thêm nội dung sau vào cuối tệp bên dưới lớp User.

class Attachment(db.Model):
    # The attachmentId is the unique identifier for the attachment.
    attachment_id = db.Column(db.String(120), primary_key=True)

    # The image filename to store.
    image_filename = db.Column(db.String(120))

    # The image caption to store.
    image_caption = db.Column(db.String(120))

Nhập lớp Tệp đính kèm mới vào tệp máy chủ bằng các tuyến đường xử lý tệp đính kèm.

Thiết lập các tuyến đường mới

Bắt đầu bước hướng dẫn này bằng cách thiết lập một số trang mới trong ứng dụng của chúng ta. Các trang này cho phép người dùng tạo và xem nội dung thông qua tiện ích bổ sung của chúng ta.

Thêm các tuyến đường tạo tệp đính kèm

Bạn cần có các trang để giáo viên chọn nội dung và đưa ra yêu cầu tạo tệp đính kèm. Triển khai tuyến đường /attachment-options để hiển thị các lựa chọn nội dung cho giáo viên chọn. Bạn cũng cần có các mẫu cho các trang xác nhận việc chọn và tạo nội dung. Các ví dụ mà chúng tôi cung cấp chứa các mẫu cho các trang này và cũng có thể hiển thị các yêu cầu và phản hồi từ API Lớp học.

Xin lưu ý rằng bạn có thể sửa đổi trang đích Chế độ xem khám phá tệp đính kèm hiện có để hiển thị các lựa chọn nội dung thay vì tạo trang /attachment-options mới. Bạn nên tạo một trang mới cho mục đích của bài tập này để giữ nguyên hành vi Đăng nhập một lần (SSO) được triển khai trong bước hướng dẫn thứ hai, chẳng hạn như thu hồi quyền cho ứng dụng. Các trang này sẽ hữu ích khi bạn xây dựng và kiểm thử tiện ích bổ sung.

Giáo viên có thể chọn từ một nhóm nhỏ hình ảnh có chú thích trong ví dụ mà chúng tôi cung cấp. Chúng tôi đã cung cấp 4 hình ảnh về các địa danh nổi tiếng có chú thích được lấy từ tên tệp.

Python

Trong ví dụ mà chúng tôi cung cấp, nội dung này nằm trong tệp webapp/attachment_routes.py.

@app.route("/attachment-options", methods=["GET", "POST"])
def attachment_options():
    """
    Render the attachment options page from the "attachment-options.html"
    template.

    This page displays a grid of images that the user can select using
    checkboxes.
    """

    # A list of the filenames in the static/images directory.
    image_filenames = os.listdir(os.path.join(app.static_folder, "images"))

    # The image_list_form_builder method creates a form that displays a grid
    # of images, checkboxes, and captions with a Submit button. All images
    # passed in image_filenames will be shown, and the captions will be the
    # title-cased filenames.

    # The form must be built dynamically due to limitations in WTForms. The
    # image_list_form_builder method therefore also returns a list of
    # attribute names in the form, which will be used by the HTML template
    # to properly render the form.
    form, var_names = image_list_form_builder(image_filenames)

    # If the form was submitted, validate the input and create the attachments.
    if form.validate_on_submit():

        # Build a dictionary that maps image filenames to captions.
        # There will be one dictionary entry per selected item in the form.
        filename_caption_pairs = construct_filename_caption_dictionary_list(
            form)

        # Check that the user selected at least one image, then proceed to
        # make requests to the Classroom API.
        if len(filename_caption_pairs) > 0:
            return create_attachments(filename_caption_pairs)
        else:
            return flask.render_template(
                "create-attachment.html",
                message="You didn't select any images.",
                form=form,
                var_names=var_names)

    return flask.render_template(
        "attachment-options.html",
        message=("You've reached the attachment options page. "
                "Select one or more images and click 'Create Attachment'."),
        form=form,
        var_names=var_names,
    )

Điều này tạo ra một trang "Tạo tệp đính kèm" giống như sau:

Chế độ xem lựa chọn nội dung mẫu bằng Python

Giáo viên có thể chọn nhiều hình ảnh. Tạo một tệp đính kèm cho mỗi hình ảnh mà giáo viên đã chọn trong phương thức create_attachments.

Đưa ra yêu cầu tạo tệp đính kèm

Bây giờ bạn đã biết những phần nội dung mà giáo viên muốn đính kèm, hãy đưa ra yêu cầu đến API Lớp học để tạo tệp đính kèm trên bài tập của chúng ta. Lưu trữ thông tin chi tiết về tệp đính kèm trong cơ sở dữ liệu sau khi nhận được phản hồi từ API Lớp học.

Bắt đầu bằng cách lấy một phiên bản của dịch vụ Lớp học:

Python

Trong ví dụ mà chúng tôi cung cấp, nội dung này nằm trong tệp webapp/attachment_routes.py.

def create_attachments(filename_caption_pairs):
    """
    Create attachments and show an acknowledgement page.

    Args:
        filename_caption_pairs: A dictionary that maps image filenames to
            captions.
    """
    # Get the Google Classroom service.
    classroom_service = googleapiclient.discovery.build(
        serviceName="classroom",
        version="v1",
        credentials=credentials)

Đưa ra yêu cầu CREATE đến courses.courseWork.addOnAttachments điểm cuối. Đối với mỗi hình ảnh mà giáo viên chọn, trước tiên hãy tạo một AddOnAttachment đối tượng:

Python

Trong ví dụ mà chúng tôi cung cấp, đây là phần tiếp theo của phương thức create_attachments.

# Create a new attachment for each image that was selected.
attachment_count = 0
for key, value in filename_caption_pairs.items():
    attachment_count += 1

    # Create a dictionary with values for the AddOnAttachment object fields.
    attachment = {
        # Specifies the route for a teacher user.
        "teacherViewUri": {
            "uri":
                flask.url_for(
                    "load_content_attachment", _scheme='https', _external=True),
        },
        # Specifies the route for a student user.
        "studentViewUri": {
            "uri":
                flask.url_for(
                    "load_content_attachment", _scheme='https', _external=True)
        },
        # The title of the attachment.
        "title": f"Attachment {attachment_count}",
    }

Bạn phải cung cấp ít nhất các trường teacherViewUri, studentViewUri và title cho mỗi tệp đính kèm. teacherViewUri và studentViewUri đại diện cho các URL được tải khi tệp đính kèm được mở bởi loại người dùng tương ứng.

Gửi đối tượng AddOnAttachment trong nội dung của yêu cầu đến điểm cuối addOnAttachments thích hợp. Cung cấp giá trị nhận dạng courseId, itemId, itemType và addOnToken cho mỗi yêu cầu.

Python

Trong ví dụ mà chúng tôi cung cấp, đây là phần tiếp theo của phương thức create_attachments.

# Use the itemType to determine which stream item type the teacher created
match flask.session["itemType"]:
    case "announcements":
        parent = classroom_service.courses().announcements()
    case "courseWorkMaterials":
        parent = classroom_service.courses().courseWorkMaterials()
    case _:
        parent = classroom_service.courses().courseWork()

# Issue a request to create the attachment.
resp = parent.addOnAttachments().create(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    addOnToken=flask.session["addOnToken"],
    body=attachment).execute()

Tạo một mục nhập cho tệp đính kèm này trong cơ sở dữ liệu cục bộ để sau này bạn có thể tải nội dung chính xác. Lớp học trả về giá trị id duy nhất trong phản hồi cho yêu cầu tạo, vì vậy, hãy sử dụng giá trị này làm khoá chính trong cơ sở dữ liệu của chúng ta. Xin lưu ý rằng Lớp học cũng truyền tham số truy vấn attachmentId khi mở Chế độ xem của giáo viên và Chế độ xem của học viên:

Python

Trong ví dụ mà chúng tôi cung cấp, đây là phần tiếp theo của phương thức create_attachments.

# Store the value by id.
new_attachment = Attachment(
    # The new attachment's unique ID, returned in the CREATE response.
    attachment_id=resp.get("id"),
    image_filename=key,
    image_caption=value)
db.session.add(new_attachment)
db.session.commit()

Cân nhắc việc định tuyến người dùng đến trang xác nhận tại thời điểm này, xác nhận rằng họ đã tạo tệp đính kèm thành công.

Cho phép tệp đính kèm từ tiện ích bổ sung

Bây giờ là thời điểm thích hợp để thêm mọi địa chỉ thích hợp vào trường Tiền tố URI tệp đính kèm được phép trong trang Cấu hình ứng dụng của SDK Google Workspace Marketplace. Tiện ích bổ sung chỉ có thể tạo tệp đính kèm từ một trong các tiền tố URI được liệt kê trên trang này. Đây là biện pháp bảo mật giúp giảm khả năng bị tấn công xen giữa.

Phương pháp đơn giản nhất là cung cấp miền cấp cao nhất của bạn trong trường này, ví dụ: https://example.com. https://localhost:<your port number>/ sẽ hoạt động nếu bạn đang sử dụng máy cục bộ làm máy chủ web.

Thêm các tuyến đường cho Chế độ xem của giáo viên và Chế độ xem của học viên

Có 4 iframe mà tiện ích bổ sung cho Google Lớp học có thể được tải. Cho đến nay, bạn chỉ xây dựng các tuyến đường phân phát iframe Chế độ xem khám phá tệp đính kèm. Tiếp theo, hãy thêm các tuyến đường để phân phát cả iframe Chế độ xem của giáo viên và Chế độ xem của học viên.

Iframe Chế độ xem của giáo viên là bắt buộc để hiển thị bản xem trước trải nghiệm của học viên, nhưng có thể tuỳ chọn bao gồm thông tin bổ sung hoặc các tính năng chỉnh sửa.

Chế độ xem của học viên là trang được trình bày cho mỗi học viên khi họ mở tệp đính kèm tiện ích bổ sung.

Để phục vụ mục đích của bài tập này, hãy tạo một tuyến đường /load-content-attachment duy nhất phân phát cả Chế độ xem của giáo viên và Chế độ xem của học viên. Sử dụng các phương thức API Lớp học để xác định xem người dùng là giáo viên hay học viên khi trang tải.

Python

Trong ví dụ mà chúng tôi cung cấp, nội dung này nằm trong tệp webapp/attachment_routes.py.

@app.route("/load-content-attachment")
def load_content_attachment():
    """
    Load the attachment for the user's role."""

    # Since this is a landing page for the Teacher and Student View iframes, we
    # need to preserve the incoming query parameters.
    if flask.request.args.get("itemId"):
        flask.session["itemId"] = flask.request.args.get("itemId")
    if flask.request.args.get("itemType"):
        flask.session["itemType"] = flask.request.args.get("itemType")
    if flask.request.args.get("courseId"):
        flask.session["courseId"] = flask.request.args.get("courseId")
    if flask.request.args.get("attachmentId"):
        flask.session["attachmentId"] = flask.request.args.get("attachmentId")

Xin lưu ý rằng bạn cũng nên xác thực người dùng tại thời điểm này. Bạn cũng nên xử lý tham số truy vấn login_hint tại đây và định tuyến người dùng đến quy trình uỷ quyền nếu cần. Hãy xem thông tin chi tiết về hướng dẫn đăng nhập được thảo luận trong các hướng dẫn trước để biết thêm thông tin về quy trình này.

Sau đó, gửi yêu cầu đến điểm cuối getAddOnContext khớp với loại mục.

Python

Trong ví dụ mà chúng tôi cung cấp, đây là phần tiếp theo của phương thức load_content_attachment.

# Create an instance of the Classroom service.
classroom_service = googleapiclient.discovery.build(
    serviceName="classroom"
    version="v1",
    credentials=credentials)

# Use the itemType to determine which stream item type the teacher created
match flask.session["itemType"]:
    case "announcements":
        parent = classroom_service.courses().announcements()
    case "courseWorkMaterials":
        parent = classroom_service.courses().courseWorkMaterials()
    case _:
        parent = classroom_service.courses().courseWork()

addon_context_response = parent.getAddOnContext(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"]).execute()

Phương thức này trả về thông tin về vai trò của người dùng hiện tại trong lớp học. Thay đổi chế độ xem được trình bày cho người dùng tuỳ thuộc vào vai trò của họ. Chỉ một trong các trường studentContext hoặc teacherContext được điền trong đối tượng phản hồi. Kiểm tra các trường này để xác định cách giải quyết người dùng.

Trong mọi trường hợp, hãy sử dụng giá trị tham số truy vấn attachmentId để biết tệp đính kèm nào cần truy xuất từ cơ sở dữ liệu của chúng ta. Tham số truy vấn này được cung cấp khi mở URI Chế độ xem của giáo viên hoặc Chế độ xem của học viên.

Python

Trong ví dụ mà chúng tôi cung cấp, đây là phần tiếp theo của phương thức load_content_attachment.

# Determine which view we are in by testing the returned context type.
user_context = "student" if addon_context_response.get(
    "studentContext") else "teacher"

# Look up the attachment in the database.
attachment = Attachment.query.get(flask.session["attachmentId"])

# Set the text for the next page depending on the user's role.
message_str = f"I see that you're a {user_context}! "
message_str += (
    f"I've loaded the attachment with ID {attachment.attachment_id}. "
    if user_context == "teacher" else
    "Please enjoy this image of a famous landmark!")

# Show the content with the customized message text.
return flask.render_template(
    "show-content-attachment.html",
    message=message_str,
    image_filename=attachment.image_filename,
    image_caption=attachment.image_caption,
    responses=response_strings)

Kiểm thử tiện ích bổ sung

Hoàn tất các bước sau để kiểm thử việc tạo tệp đính kèm:

  • Đăng nhập vào [Google Lớp học] với tư cách là một trong những người dùng kiểm thử Giáo viên.
  • Chuyển đến thẻ Bài tập trên lớp rồi tạo Bài tập mới.
  • Nhấp vào nút Tiện ích bổ sung bên dưới vùng văn bản, sau đó chọn tiện ích bổ sung. Iframe sẽ mở và tiện ích bổ sung sẽ tải URI thiết lập tệp đính kèm mà bạn đã chỉ định trong trang Cấu hình ứng dụng của SDK Google Workspace Marketplace.
  • Chọn một phần nội dung để đính kèm vào bài tập.
  • Đóng iframe sau khi hoàn tất quy trình tạo tệp đính kèm.

Bạn sẽ thấy một thẻ tệp đính kèm xuất hiện trong giao diện người dùng tạo bài tập trong Google Google Lớp học. Nhấp vào thẻ để mở iframe Chế độ xem của giáo viên và xác nhận rằng tệp đính kèm chính xác sẽ xuất hiện. Nhấp vào nút Giao bài.

Hoàn tất các bước sau để kiểm thử trải nghiệm của học viên:

  • Sau đó, đăng nhập vào Lớp học với tư cách là người dùng thử nghiệm học viên trong cùng lớp học với người dùng thử nghiệm giáo viên.
  • Tìm bài tập kiểm thử trong thẻ Bài tập trên lớp.
  • Mở rộng bài tập rồi nhấp vào thẻ tệp đính kèm để mở iframe Chế độ xem của học viên.

Xác nhận rằng tệp đính kèm chính xác sẽ xuất hiện cho học viên.

Xin chúc mừng! Bạn đã sẵn sàng chuyển sang bước tiếp theo: tạo tệp đính kèm thuộc loại hoạt động.