Anexos externos e entregas

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

Neste tutorial, você vai adicionar comportamento a um aplicativo da Web para criar anexos de complementos fora do Google Sala de Aula. Use esse comportamento para permitir que os usuários criem anexos de complementos no seu produto ou site. Essa também é uma ótima adição a uma integração 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 do Google Sala de Aula.

Você também adiciona comportamento ao complemento para modificar uma atividade com anexos de complementos de maneira programática. É possível modificar qualquer atividade que tenha um dos seus anexos de complementos, independentemente de quem a criou. 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 o trabalho do estudante está pronto para revisão.

Você estende a versão final do complemento que oferece suporte a anexos de tipo de conteúdo ou tipo de atividade. O anexo de tipo de conteúdo é usado neste guia.

Importante: antes de seguir este tutorial, conclua os tutoriais anteriores da série. Este tutorial expande o app da Web desenvolvido nos tutoriais anteriores. Você pode fazer o download do código-fonte completo de todos os tutoriais na página Visão geral. O código deste tutorial específico pode ser encontrado no diretório /07-external-attachments/.

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 atividades CourseWork. Adicione esse escopo às listas de escopos no SDK do Google Workspace Marketplace, na tela de permissão doOAuth 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

Importante: não modifique nenhuma das experiências de iframe nesta etapa do tutorial. Em vez disso, adicione um comportamento para criar anexos de complementos em uma página da Web fora do Google Sala de Aula.

Adicionar botões a uma página da Web não em 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, é provável que seja seu site ou aplicativo. 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 sugerido CourseWork para criar uma nova atividade.

Você também precisará 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 de Python fornecido modifica a rota /index que foi 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 novo arquivo de módulo Python para processar as rotas relacionadas ao CourseWork. Esse é o coursework_routes.py no exemplo fornecido. Adicione as três rotas a seguir. Você vai preencher alguns dos conteúdos 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")

Importante: adicione todas as novas rotas de callback do OAuth ao URI de redirecionamento autorizado do ID do cliente OAuth na página "Credenciais" do projeto do Google Cloud. Para o exemplo fornecido, adicione https://<<your server>>/index e https://<<your server>>/coursework-assignment-callback.

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

**Ponto-chave**: sempre verifique se um usuário está qualificado para criar anexos de complementos antes de tentar criá-los. A qualificação varia de acordo com o usuário e o projeto do Google Cloud solicitante e pode mudar ao longo do tempo.

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

Importante: as verificações de qualificação usando a API Classroom estão em pré-lançamento público e disponíveis na versão de pré-lançamento V1_20240930_PREVIEW e mais recentes. Para usar métodos de API em pré-lançamento público, é necessário fazer parte do Programa de testes para desenvolvedores do Google Workspace e realizar configurações adicionais além do uso típico da API Classroom.

Adicione a verificação de qualificação à implementação da rota de criação CourseWork. Em seguida, teste o campo allowed na resposta. Para usuários qualificados, siga a lógica para criar uma atividade com anexo de complemento. Caso contrário, crie um material de link. Você precisará 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 fixo neste exemplo.

Ponto-chave: sempre crie anexos de complementos se o usuário estiver qualificado. Os complementos oferecem uma experiência superior para usuários e desenvolvedores em relação aos materiais de link.

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 estiver qualificado para criar anexos de complementos, faça o seguinte:

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

Ponto-chave: é necessário emitir as duas solicitações separadamente. A atividade CourseWork precisa ser criada para que o novo anexo de complemento possa ser associado a um ID de atividade.

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

**Ponto-chave**: se o produto já cria atividades CourseWork, é provável que ele já siga o fluxo apresentado aqui.

Se o usuário não estiver qualificado para criar anexos de complementos, crie um material de link 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

Ponto-chave:um dos principais benefícios dos anexos de complementos é que eles concedem a capacidade de executar solicitações de API no item de stream pai.

É possível acessar, modificar, entregar, recuperar ou retornar qualquer item de stream do Google Sala de Aula que tenha pelo menos um dos seus anexos de complementos, independentemente de quem criou o item de stream. Os itens de stream são qualquer 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 é possível acessar e modificar itens de 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 em este tutorial. Ele precisa abrir uma nova rota para modificar uma atividade CourseWork.

Python

O exemplo de Python fornecido modifica a rota /index que foi modificada 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 ao 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

Importante: neste momento do desenvolvimento, só é possível testar o aplicativo nos iframes de complementos do Google Sala de Aula. Leia nossa página do guia de parâmetros de iframe e consulta para uma descrição de cada iframe. Todas as instruções fornecidas neste tutorial pressupõem que o complemento possa ser usado no contexto de um iframe.

Para simplificar, os exemplos fornecidos usam identificadores de curso e atividade fixos. É possível receber esses identificadores fazendo solicitações com credenciais de professor para os métodos get e list dos recursos courses e courseWork. Eles também são retornados na resposta ao criar atividades courseWork.

Testar a criação de materiais 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 Google Workspace for Education Teaching &Learning ou Plus. É possível alternar o status da licença de um usuário no console do administrador do domínio de teste.Clique no botão Criar uma atividade do CourseWork e abra a interface do Google Sala de Aula para verificar 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 usuário professor com uma licença do Google Workspace for Education Teaching & Learning ou Plus. Clique no botão Criar uma atividade do CourseWork e abra a interface do Google Sala de Aula para verificar se uma atividade com um anexo de complemento foi criada. O anexo precisa mostrar o nome do aplicativo de complemento e o título especificado no código.

Testar a modificação de atividades

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

Parabéns! Você concluiu a série de tutoriais.