Внешние вложения и усилитель; сдача

Это седьмое прохождение в серии прохождений надстроек Класса.

В этом пошаговом руководстве вы добавите поведение в веб-приложение для создания дополнительных вложений за пределами Google Classroom . Используйте это поведение, чтобы позволить пользователям создавать дополнительные вложения из вашего существующего продукта или веб-сайта. Это также отличное дополнение к интеграции CourseWork , поскольку вы направляете существующий трафик на улучшенный пользовательский интерфейс, предлагаемый вашим дополнением, не меняя его поток. Предлагаемый процесс представлен на странице руководства «Создание вложений за пределами Класса» .

Вы также добавляете поведение в свою надстройку, чтобы программно изменить задание с вложениями надстройки . Вы можете изменить любое задание, к которому прикреплено одно из ваших дополнительных вложений, независимо от того, кто создал задание. Это особенно полезно для сдачи заданий после того, как учащийся выполнил задание, сигнализируя учителю, что поставленные задачи выполнены и работа учащегося готова к проверке.

Вы расширяете окончательную версию своего дополнения, которая поддерживает вложения типа контента или типа действия . В этом руководстве используется вложение типа контента.

Добавьте область OAuth для управления назначениями.

Убедитесь, что ваше приложение запрашивает следующие области:

  • https://www.googleapis.com/auth/classroom.addons.teacher
  • https://www.googleapis.com/auth/classroom.addons.student
  • https://www.googleapis.com/auth/classroom.coursework.students

Область classroom.coursework.students ранее не требовалась и используется для создания или изменения заданий CourseWork . Добавьте эту область в списки областей в SDK Google Workspace Marketplace вашего облачного проекта, на экране согласия OAuth и в коде вашего сервера.

Питон

  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",
  ]

Создание задания в Классе

Добавление кнопок на веб-страницу без iframe

Последовательность действий, описанная в этом пошаговом руководстве, позволяет пользователю создавать задания и вложения Google Classroom из продуктов, не принадлежащих Google. На практике это, скорее всего, ваш существующий веб-сайт или приложение. В этом примере вам нужно создать макет веб-страницы, которая будет выступать в качестве внешнего сайта. Вам нужна кнопка или ссылка, при нажатии которой открывается новый маршрут , выполняющий предложенный процесс CourseWork для создания нового задания.

Вам также потребуется добавить кнопку или ссылку, позволяющую пользователю войти в систему, если у вас ее еще нет. Для выполнения последующих запросов API вам потребуются учетные данные пользователя, поэтому они должны завершить рукопожатие OAuth 2.0. Подробные инструкции см . в пошаговом руководстве по входу .

Питон

Приведенный пример Python изменяет маршрут /index , который был введен на первом шаге пошагового руководства .

<!-- /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>

Добавьте HTML-шаблон для представления пункта назначения на вашем веб-сайте. На этой странице будет представлен контент, который будет прикреплен к вашему заданию 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>

Создайте новый файл модуля Python для обработки маршрутов, связанных с CourseWork. В нашем примере это coursework_routes.py . Добавьте следующие три маршрута; Обратите внимание, что часть содержимого вы заполните позже.

# /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")

Проверка права пользователя на создание дополнений

Существует несколько предварительных условий, которым должен соответствовать пользователь, прежде чем вы сможете создавать дополнительные вложения от его имени. Для удобства Google предоставляет метод courses.checkAddOnCreationEligibility , чтобы определить, соответствует ли пользователь этим предварительным требованиям. Пользователь, соответствующий предварительным требованиям, называется подходящим пользователем.

Добавьте проверку приемлемости в реализацию маршрута создания CourseWork . Затем проверьте поле isCreateAttachmentEligible в ответе. Для соответствующих критериям пользователей следуйте логике, чтобы создать задание с дополнительным прикрепленным файлом . В противном случае создайте Link Material . Вам потребуется знать идентификатор курса, в котором пользователь хочет создать задание. Обычно вы предлагаете пользователю указать, какой курс использовать. Для простоты в этом примере мы используем жестко запрограммированное значение.

Питон

# /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 ...

  # The ID of the course to which the assignment will be added.
  course_id = 1234567890  # TODO(developer) Replace with an actual course ID.

  # Check whether the user can create add-on attachments.
  eligibility_response = (
      classroom_service.courses()
      .checkAddOnCreationEligibility(courseId=course_id)
      .execute()
  )
  is_create_attachment_eligible = eligibility_response.get("isCreateAttachmentEligible")

  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.

Создайте задание с дополнительным прикрепленным файлом для подходящих пользователей.

Если пользователь имеет право создавать дополнительные вложения, выполните следующие действия:

  1. Отправьте запрос API, чтобы создать задание courseWork в Google Classroom без вложений .
  2. Извлеките id вновь созданного задания.
  3. Создайте новый AddOnAttachment CourseWork .
  4. Отправьте запрос на создание дополнительного вложения к только что созданному заданию в Google Classroom.

Питон

# /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()
  )

Если пользователь не имеет права создавать дополнительные вложения, вместо этого создайте Материал ссылки, выполнив следующие действия:

Питон

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()
    )

Изменение уже созданного задания

Вы можете получить доступ, изменить, сдать, вернуть или вернуть любой элемент потока Google Classroom, к которому имеется хотя бы одно из ваших дополнительных вложений, независимо от того, кто создал этот элемент потока. Элементами потока являются любые Announcement , задания CourseWork или CourseWorkMaterial .

Чтобы продемонстрировать это, вы добавите маршрут для изменения данного элемента потока. Используйте этот метод, чтобы убедиться, что вы можете получать доступ и изменять элементы потока, созданные вами с помощью API и созданные учителем через пользовательский интерфейс Google Classroom.

Добавьте еще одну ссылку или кнопку на веб-страницу, которую вы впервые редактировали в этом пошаговом руководстве. Должен открыться новый маршрут для изменения задания CourseWork .

Питон

Приведенный пример Python изменяет маршрут /index , который был изменен ранее в этом пошаговом руководстве .

<!-- /webapp/templates/index.html -->
<a href="modify-coursework-assignment.html">Create a CourseWork Assignment</a>

Создайте новый маршрут для обработки маршрутов, связанных с CourseWork. Это находится в файле coursework_routes.py в нашем примере.

# 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()
)

Протестируйте дополнение

Для простоты в приведенных примерах используются жестко закодированные идентификаторы курсов и заданий. Вы можете получить эти идентификаторы, отправив запросы с учетными данными преподавателя к методам get и list courses и ресурсов courseWork . Они также возвращаются в ответе при создании заданий courseWork .

Запустите свой сервер, затем перейдите на свою индексную страницу и войдите в систему как преподаватель без лицензии Google Workspace for Education Teaching & Learning или Plus . Вы можете переключить статус лицензии пользователя в консоли администратора вашего тестового домена. Нажмите кнопку «Создать задание курсовой работы» , затем откройте пользовательский интерфейс Google Classroom и убедитесь, что задание с прикрепленным к нему материалом ссылки было создано. Во вложении должно быть указано название связанной веб-страницы и URL-адрес.

Тестирование создания дополнительных вложений

Вернитесь на главную страницу и войдите в систему как преподаватель с лицензией Google Workspace for Education Teaching & Learning или Plus . Нажмите кнопку «Создать задание курсовой работы» , затем откройте пользовательский интерфейс Google Classroom и убедитесь, что задание с дополнительным вложением было создано. Во вложении должно быть указано имя вашего дополнительного приложения и заголовок, указанный в вашем коде.

Модификация тестового задания

Вернитесь на главную страницу и убедитесь, что вы вошли в систему как преподаватель с лицензией Teaching & Learning или Plus. Нажмите кнопку «Изменить задание курсовой работы» , затем вернитесь в пользовательский интерфейс Google Classroom и убедитесь, что название задания было изменено.

Поздравляем! Вы завершили серию прохождений.