Tạo tệp đính kèm bên ngoài Google Lớp học

Hướng dẫn này đề cập đến việc tạo tệp đính kèm bằng tiện ích bổ sung trong trang web hoặc ứng dụng của bạn. Các hoạt động tương tác này tương tự như việc tạo bài tập bằng các điểm cuối CourseWork API. Triển khai hành trình này để cho phép người dùng tạo tệp đính kèm bằng tiện ích bổ sung từ trang web hoặc ứng dụng của bạn.

Lưu ý quan trọng: Bạn nên triển khai quy trình tạo tệp đính kèm này nếu đã tạo bài tập CourseWork. Việc mở rộng quá trình triển khai CourseWork giúp bạn chuyển đổi nhiều người dùng hơn nữa sang tiện ích bổ sung của mình và không tốn nhiều công sức.

Luồng công việc

Nhìn chung, quy trình tạo tệp đính kèm sẽ diễn ra theo trình tự sau:

1. Người dùng là giáo viên mở trang web hoặc ứng dụng của bạn. Họ chọn một nội dung để giao cho học viên.
2. Kiểm tra để đảm bảo người dùng có thể tạo tệp đính kèm có tiện ích bổ sung.
3. Nếu người dùng không thể tạo tiện ích bổ sung tệp đính kèm, hãy tạo một bài tập CourseWork có URL đến nội dung đã chọn dưới dạng Tài liệu liên kết.
4. Nếu người dùng có thể tạo tệp đính kèm có tiện ích bổ sung, hãy làm như sau:
   1. Tạo bài tập.
   2. Tạo một tệp đính kèm tiện ích bổ sung liên kết đến nội dung đã chọn và liên kết tệp đó với bài tập mới.
5. Thông báo cho giáo viên biết rằng bài tập đã được tạo thành công.

Mỗi hành động được mô tả trong các phần sau.

Kiểm tra xem người dùng có thể tạo tệp đính kèm có tiện ích bổ sung hay không

Bạn có thể tạo tệp đính kèm bằng tiện ích bổ sung thay cho một người dùng đủ điều kiện. Người dùng đủ điều kiện là người dùng là giáo viên trong khoá học mà bạn đang cố gắng tạo bài tập trong khoá học và được cấp giấy phép Teaching & Learning hoặc Education Plus của phiên bản Google Workspace for Education.

Lưu ý quan trọng: Điều kiện tạo tiện ích bổ sung tệp đính kèm có thể khác nhau đối với mỗi người dùng và có thể thay đổi theo thời gian. Luôn kiểm tra xem người dùng có đủ điều kiện hay không trước khi cố gắng tạo tệp đính kèm bổ sung.

Lưu ý quan trọng: Các bước kiểm tra điều kiện bằng Classroom API đang ở giai đoạn xem trước công khai và có trong phiên bản xem trước V1_20240930_PREVIEW trở lên. Để sử dụng các phương thức API trong bản dùng thử công khai, bạn phải tham gia Chương trình Bản dùng thử cho nhà phát triển Google Workspace và thực hiện thêm bước thiết lập ngoài việc sử dụng API Lớp học thông thường.

Bắt đầu bằng cách xác định xem người dùng có thể tạo tệp đính kèm có tiện ích bổ sung hay không. Bạn có thể thực hiện việc này bằng cách gửi yêu cầu đến điểm cuối userProfiles.checkUserCapability bằng tham số khả năng CREATE_ADD_ON_ATTACHMENT. Kiểm tra trường boolean allowed trong phản hồi; giá trị true cho biết người dùng đủ điều kiện tạo tệp đính kèm bổ sung.

Cảnh báo: Yêu cầu tạo tệp đính kèm bổ sung cho người dùng có khả năng CREATE_ADD_ON_ATTACHMENT không đảm bảo sẽ thành công. Ví dụ: người dùng có quyền này sẽ nhận được lỗi phản hồi 403 nếu bạn cố gắng tạo tệp đính kèm bổ sung thay cho họ trong một khoá học mà người dùng không phải là giáo viên.

Python

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')
)
print('User eligibility for add-on attachment creation: '
      f'{is_create_attachment_eligible}.')

Định tuyến người dùng dựa trên điều kiện của họ

Điều kiện này xác định xem bạn có thể tạo tệp đính kèm có tiện ích bổ sung cho người dùng hay không.

Lưu ý quan trọng: Tiện ích bổ sung mang lại nhiều lợi ích đáng kể cho trải nghiệm người dùng. Luôn tạo tệp đính kèm bổ sung cho người dùng đủ điều kiện.

Người dùng không đủ điều kiện

Nếu người dùng không thể tạo tệp đính kèm tiện ích bổ sung, hãy tạo một bài tập CourseWork mới có URL nội dung do người dùng chọn làm Link.

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.
    'maxPoints': 100,
    'materials': [
      {'link': {'url': my_content_url}}
    ]
  }

  assignment = (
    service.courses()
    .courseWork()
    .create(courseId=course_id, body=coursework)
    .execute()
  )

  print(
    f'Link Material assignment created with ID: {assignment.get("id")}'
  )

Phản hồi chứa một bài tập trong khoá học được yêu cầu có nội dung đính kèm. Người dùng có thể nhấp vào biểu tượng Link để mở nội dung trên trang web của bạn trong một thẻ mới.

Hình 1. Chế độ xem của giáo viên về bài tập nháp trong Khoá học có Tài liệu liên kết.

Người dùng đủ điều kiện

Hãy làm như sau nếu người dùng có thể tạo tệp đính kèm có tiện ích bổ sung.

1. Tạo một bài tập CourseWork mới mà không có tệp đính kèm.
2. Tạo tệp đính kèm có tiện ích bổ sung.
   • Đặt itemId của AddOnAttachment thành id của bài tập mới tạo.
   • Đảm bảo rằng bạn cung cấp URL cho nội dung do người dùng chọn cho mỗi khung hiển thị mà bạn hỗ trợ.

Python

if is_create_attachment_eligible:
  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.
    'maxPoints': 100,
  }

  assignment = (
    classroom_service.courses()
    .courseWork()
    .create(courseId=course_id, body=coursework)
    .execute()
  )

  print(
    f'Empty assignment created with ID: {assignment.get("id")}'
  )

  attachment = {
    'teacherViewUri': {'uri': teacher_view_url},
    'studentViewUri': {'uri': student_view_url},
    'studentWorkReviewUri': {'uri': grade_student_work_url},
    'title': f'Test Attachment {test_label}',
  }

  add_on_attachment = (
    service.courses()
    .courseWork()
    .addOnAttachments()
    .create(
      courseId=course_id,
      itemId=assignment.get("id"),  # ID of the new assignment.
      body=attachment,
    )
    .execute()
  )

  print(
    f'Add-on attachment created with ID: {add_on_attachment.get("id")}'
  )

Lưu ý: Bạn không bắt buộc phải có mã thông báo tiện ích bổ sung nếu tạo tệp đính kèm cho bài tập mà bạn đã tạo.

Tiện ích bổ sung này sẽ xuất hiện dưới dạng một thẻ tệp đính kèm trong Lớp học. Các URL được chỉ định trong yêu cầu sẽ mở trong iframe thích hợp cho từng Lượt xem.