Os complementos do Google Sala de Aula já estão disponíveis para desenvolvedores. Consulte a documentação sobre complementos para mais informações.

Esta página foi traduzida pela API Cloud Translation.

Anexos externos e entregas

Este é o sétimo tutorial da série sobre os complementos do Google Sala de Aula.

Neste tutorial, você adiciona comportamento a um aplicativo da Web para criar anexos de complemento fora do Google Sala de Aula. Use esse comportamento para permitir que seus usuários criem anexos de complementos com base no seu produto ou site atual. Essa também é uma ótima adição a uma integração do CourseWork, porque você direciona o tráfego atual para a experiência do usuário aprimorada oferecida pelo complemento sem mudar o fluxo. O processo sugerido é apresentado na página do guia Criar anexos fora da Sala de Aula.

Você também adiciona comportamento ao complemento para modificar uma atividade com anexos de complementos de forma programática. É possível modificar qualquer atividade que tenha um dos anexos de complemento, independente de quem criou a atividade. Isso é especialmente útil para entregar atividades depois que um estudante conclui uma atividade, sinalizando ao professor que as tarefas atribuídas estão concluídas e que o trabalho do estudante está pronto para revisão.

Você estende a versão final do complemento que oferece suporte a content-type ou anexos de activity-type. O anexo "content-type" é usado neste guia.

Adicionar o escopo do OAuth de gerenciamento de atividades

Verifique se o aplicativo solicita os seguintes escopos:

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

O escopo classroom.coursework.students não era necessário antes e é usado para criar ou modificar atribuições de CourseWork. Adicione esse escopo às listas de escopos no SDK do Google Workspace Marketplace, na tela de consentimento do OAuth e no código do servidor do projeto do 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",
  ]

Criar uma atividade no Google Sala de Aula

Adicionar botões a uma página da Web sem iframe

O fluxo descrito neste tutorial permite que um usuário crie atividades e anexos do Google Sala de Aula em um produto que não é do Google. Na prática, provavelmente é seu site ou aplicativo atual. Para este exemplo, você precisa criar uma página da Web simulada para atuar como um site externo. Você precisa de um botão ou link que, quando clicado, abra uma nova rota que execute o fluxo CourseWork sugerido para criar uma nova atividade.

Você também precisa adicionar um botão ou link para permitir que o usuário faça login se ainda não tiver um. Você vai precisar das credenciais do usuário para fazer as solicitações de API subsequentes. Portanto, ele precisa concluir o handshake do OAuth 2.0. Consulte o tutorial de login para orientações específicas.

Python

O exemplo em Python fornecido modifica a rota /index apresentada na primeira etapa do tutorial.

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

Adicione um modelo HTML para representar um destino no seu site. Essa página vai representar o conteúdo que será anexado à sua atividade 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>

Crie um arquivo de módulo Python para processar as rotas relacionadas ao CourseWork. Este é coursework_routes.py no exemplo fornecido. Adicione as três rotas a seguir. Observe que você vai preencher parte do conteúdo mais tarde.

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

Verificar a qualificação de um usuário para criar anexos

Há vários pré-requisitos que um usuário precisa atender antes que você possa criar anexos de complementos em nome dele. Para sua conveniência, o Google oferece o método userProfiles.checkUserCapability para determinar se um usuário atende a esses pré-requisitos. Um usuário que atende aos pré-requisitos é chamado de usuário qualificado.

Adicione a verificação de qualificação à implementação da rota de criação de CourseWork. Em seguida, teste o campo allowed na resposta. Para usuários qualificados, siga a lógica para criar uma atividade com um anexo de complemento. Caso contrário, crie um LinkMaterial. Você precisa saber o ID do curso em que o usuário quer criar uma atividade. Normalmente, você pede ao usuário para especificar qual curso usar. Para simplificar, usamos um valor codificado neste exemplo.

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.

Criar uma atividade com anexo de complemento para usuários qualificados

Se o usuário puder criar anexos de complementos, faça o seguinte:

Envie uma solicitação de API para criar uma atividade courseWork no Google Sala de Aula sem anexos.
Extraia o id da atividade recém-criada.
Crie um novo CourseWork AddOnAttachment.
Envie uma solicitação para criar um anexo de complemento na atividade recém-criada no Google Sala de Aula.

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

Criar um material de link

Se o usuário não se qualificar para criar anexos de complemento, crie um Link Material fazendo o seguinte:

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

Modificar uma atividade já criada

Você pode acessar, modificar, enviar, recuperar ou devolver qualquer item do fluxo do Google Sala de Aula que tenha pelo menos um dos seus anexos de complemento, independente de quem criou o item do fluxo. Os itens do mural são Announcement, CourseWork atividade ou CourseWorkMaterial.

Para demonstrar isso, você vai adicionar uma rota para modificar um determinado item de stream. Use esse método para verificar se você pode acessar e modificar itens do stream criados por você usando a API e criados por um professor na interface do Google Sala de Aula.

Adicione mais um link ou botão à página da Web que você editou pela primeira vez neste tutorial. Isso vai abrir uma nova rota para modificar uma atividade CourseWork.

Python

O exemplo em Python fornecido modifica a rota /index que foi alterada anteriormente neste tutorial.

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

Crie uma nova rota para processar as rotas relacionadas a CourseWork. Isso está no arquivo coursework_routes.py no exemplo fornecido.

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

Testar o complemento

Para simplificar, os exemplos fornecidos usam identificadores de curso e atividade fixados no código. É possível receber esses identificadores fazendo solicitações com credenciais de professor para os métodos get e list dos recursos courses e courseWork. Elas também são retornadas na resposta ao criar atribuições de courseWork.

Teste de criação de material de link

Execute o servidor, navegue até a página de índice e faça login como um usuário professor sem uma licença do Teaching and Learning Upgrade ou do Google Workspace for Education Plus. É possível alternar o status da licença de um usuário no Admin Console do domínio de teste.Clique no botão Criar uma atividade do curso, abra a interface do Google Sala de Aula e verifique se uma atividade com um anexo de material de link foi criada. O anexo precisa mostrar o título da página da Web vinculada e um URL.

Testar a criação de anexos de complementos

Volte à página de índice e faça login como um professor com uma licença do Google Workspace for Education Teaching & Learning ou Plus. Clique no botão Criar uma atividade do curso, abra a interface do Google Sala de Aula e verifique se uma atividade com um anexo de complemento foi criada. O anexo precisa mostrar o nome do aplicativo complemento e o título especificado no código.

Teste de modificação de atribuição

Volte à página de índice e verifique se você fez login como um professor com uma licença do Teaching & Learning ou do Plus. Clique no botão Modificar uma atividade do Material da turma e volte para a interface do Google Sala de Aula para verificar se o título da atividade foi alterado.

Parabéns! Você concluiu a série de instruções.

Anexos externos e entregas Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Adicionar o escopo do OAuth de gerenciamento de atividades

Python

Criar uma atividade no Google Sala de Aula

Adicionar botões a uma página da Web sem iframe

Python

Verificar a qualificação de um usuário para criar anexos

Python

Criar uma atividade com anexo de complemento para usuários qualificados

Python

Criar um material de link

Python

Modificar uma atividade já criada

Python

Testar o complemento

Teste de criação de material de link

Testar a criação de anexos de complementos

Teste de modificação de atribuição

Anexos externos e entregas