Começar a usar rubricas

Um rubric é um modelo que os professores podem usar para avaliar os envios dos alunos. A API Classroom permite que você aja em nome do professor para gerenciar essas rubricas.

Figura 1. Visualização de um exemplo de rubrica em uma atividade do Google Sala de Aula.

Neste guia, explicamos os conceitos básicos e a funcionalidade da API Rubrics. Consulte estes artigos da Central de Ajuda para saber mais sobre a estrutura geral de uma rubrica e como a classificação rubrica é feita na IU do Google Sala de Aula.

Pré-requisitos

Para seguir este guia, você precisa ter:

• Python 3.8.6 ou superior
• A ferramenta de gerenciamento de pacotes pip.
• um projeto do Google Cloud;
• Uma conta do Google Workspace for Education com o Google Sala de Aula ativado.
• Uma turma de teste com pelo menos uma conta de estudante de teste. Se você não tiver uma classe do Google Sala de Aula que possa usar para testes, crie uma na IU e adicione um estudante de teste.

Autorizar credenciais de um aplicativo para computador

Para fazer a autenticação como usuário final e acessar os dados do usuário no app, crie um ou mais IDs do cliente OAuth 2.0. Um ID do cliente é usado para identificar um único app nos servidores OAuth do Google. Caso seu app seja executado em várias plataformas, crie um ID do cliente separado para cada uma delas.

1. Navegue até a página Credenciais do GCP no console do Google Cloud.
2. Clique em Criar credenciais > ID do cliente OAuth.
3. Clique em Tipo de aplicativo > App para computador.
4. No campo Nome, digite um nome para a credencial. Esse nome só é exibido no console do Google Cloud. Por exemplo, "Cliente de visualização de rubricas".
5. Clique em Criar. A tela "Cliente OAuth criado" será exibida, mostrando o novo ID e a chave secreta do cliente.
6. Clique em Fazer o download do JSON e em OK. A credencial recém-criada aparece em IDs do cliente OAuth 2.0.
7. Salve o arquivo JSON salvo como credentials.json e mova-o para o diretório de trabalho.
8. Clique em Criar credenciais > Chave de API e anote a chave de API.

Consulte Criar credenciais de acesso para saber mais.

Configurar escopos OAuth

Dependendo dos escopos OAuth atuais do seu projeto, talvez seja necessário configurar escopos adicionais.

1. Acesse a tela de permissão OAuth.
2. Clique em Edit App > Save and Continue para acessar a tela "Scopes".
3. Clique em Adicionar ou remover escopos.
4. Adicione os seguintes escopos se ainda não tiver feito isso:
   • https://www.googleapis.com/auth/classroom.coursework.students
   • https://www.googleapis.com/auth/classroom.courses
5. Em seguida, clique em Atualizar > Salvar e continuar > Salvar e continuar > Voltar para o painel.

Consulte Configurar a tela de permissão OAuth para saber mais.

O escopo classroom.coursework.students permite acesso de leitura e gravação a rubricas (junto com acesso a CourseWork), e o escopo classroom.courses permite cursos de leitura e gravação.

Os escopos necessários para um determinado método estão listados na documentação de referência do método. Consulte os escopos de autorização courses.courseWork.rubrics.create como exemplo. Veja todos os escopos do Google Sala de Aula em Escopos do OAuth 2.0 para APIs do Google. As rubricas não são mencionadas aqui porque a API ainda está em pré-lançamento.

Configurar o exemplo

No seu diretório de trabalho, instale a biblioteca de cliente do Google para Python:

pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

Observação :os campos e métodos relacionados a rubricas não são expostos nas bibliotecas de cliente padrão porque o CRUD de rubricas está na prévia para desenvolvedores. O exemplo a seguir especifica o rótulo DEVELOPER_PREVIEW durante a geração da biblioteca para ativar a exposição. Consulte Acessar APIs de visualização para saber mais sobre como usar APIs de visualização com bibliotecas de cliente.

Crie um arquivo chamado main.py que crie a biblioteca de cliente e autorize o usuário usando sua chave de API no lugar de YOUR_API_KEY:

import json
import os.path

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

# If modifying these scopes, delete the file token.json.
SCOPES = ['https://www.googleapis.com/auth/classroom.courses',
          'https://www.googleapis.com/auth/classroom.coursework.students']

def build_authenticated_service(api_key):
    """Builds the Classroom service."""
    creds = None
    # The file token.json stores the user's access and refresh tokens, and is
    # created automatically when the authorization flow completes for the first
    # time.
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)
    # If there are no (valid) credentials available, let the user log in.
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(
                'credentials.json', SCOPES)
            creds = flow.run_local_server(port=0)
        # Save the credentials for the next run.
        with open('token.json', 'w') as token:
            token.write(creds.to_json())

    try:
        # Build the Classroom service.
        service = build(
            serviceName="classroom",
            version="v1",
            credentials=creds,
            discoveryServiceUrl=f"https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key={api_key}")

        return service

    except HttpError as error:
        print('An error occurred: %s' % error)

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

Execute o script usando python main.py. Você precisará fazer login e consentir com os escopos do OAuth.

Criar uma atividade

Uma rubrica está associada a uma atribuição, ou CourseWork, e é significativa apenas no contexto dessa CourseWork. As rubricas só podem ser criadas pelo projeto do Google Cloud que criou o item CourseWork pai. Para os fins deste guia, crie uma nova atribuição CourseWork com um script.

Adicione o código abaixo ao método main.py:

def get_latest_course(service):
    """Retrieves the last created course."""
    try:
        response = service.courses().list(pageSize=1).execute()
        courses = response.get("courses", [])
        if not courses:
            print("No courses found. Did you remember to create one in the UI?")
            return
        course = courses[0]
        return course

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

def create_coursework(service, course_id):
    """Creates and returns a sample coursework."""
    try:
        coursework = {
            "title": "Romeo and Juliet analysis.",
            "description": """Write a paper arguing that Romeo and Juliet were
                                time travelers from the future.""",
            "workType": "ASSIGNMENT",
            "state": "PUBLISHED",
        }
        coursework = service.courses().courseWork().create(
            courseId=course_id, body=coursework).execute()
        return coursework

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Agora, atualize main.py para recuperar o course_id da classe de teste que você acabou de criar, criar uma nova atribuição de exemplo e extrair o coursework_id da atribuição:

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    course = get_latest_course(service)
    course_id = course.get("id")
    course_name = course.get("name")
    print(f"'{course_name}' course ID: {course_id}")

    coursework = create_coursework(service, course_id)
    coursework_id = coursework.get("id")
    print(f"Assignment created with ID {coursework_id}")

    #TODO(developer): Save the printed course and coursework IDs.

Salve course_id e coursework_id. Eles são necessários para todas as operações CRUD das rubricas.

Agora você tem um exemplo de CourseWork no Google Sala de Aula.

Figura 2. Visualização de uma atividade de exemplo no Google Sala de Aula.

Criar uma rubrica

Agora você já pode começar a gerenciar rubricas.

Uma rubrica pode ser criada em um CourseWork com uma chamada Create contendo o objeto de rubrica completo, em que as propriedades do ID para critérios e níveis são omitidas (geradas na criação).

Observação: como o CRUD de rubricas está na prévia para desenvolvedores, as chamadas para o serviço de rubricas vão retornar um erro se um previewVersion apropriado não for especificado. O exemplo a seguir e todas as chamadas subsequentes relacionadas a rubricas definem o campo previewVersion como V1_20231110_PREVIEW. Consulte Acessar APIs de visualização para saber mais sobre como especificar versões e o Roteiro para saber quais versões têm suporte.

Adicione a seguinte função a main.py:

def create_rubric(service, course_id, coursework_id):
    """Creates an example rubric on a coursework."""
    try:
        body = {
            "criteria": [
                {
                    "title": "Argument",
                    "description": "How well structured your argument is.",
                    "levels": [
                        {"title": "Convincing",
                         "description": "A compelling case is made.", "points": 30},
                        {"title": "Passable",
                         "description": "Missing some evidence.", "points": 20},
                        {"title": "Needs Work",
                         "description": "Not enough strong evidence..", "points": 0},
                    ]
                },
                {
                    "title": "Spelling",
                    "description": "How well you spelled all the words.",
                    "levels": [
                        {"title": "Perfect",
                         "description": "No mistakes.", "points": 20},
                        {"title": "Great",
                         "description": "A mistake or two.", "points": 15},
                        {"title": "Needs Work",
                         "description": "Many mistakes.", "points": 5},
                    ]
                },
                {
                    "title": "Grammar",
                    "description": "How grammatically correct your sentences are.",
                    "levels": [
                        {"title": "Perfect",
                         "description": "No mistakes.", "points": 20},
                        {"title": "Great",
                         "description": "A mistake or two.", "points": 15},
                        {"title": "Needs Work",
                         "description": "Many mistakes.", "points": 5},
                    ]
                },
            ]
        }

        rubric = service.courses().courseWork().rubrics().create(
            courseId=course_id, courseWorkId=coursework_id, body=body,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
            ).execute()
        print(f"Rubric created with ID {rubric.get('id')}")
        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Em seguida, atualize e execute main.py para criar a rubrica de exemplo usando os IDs Course e CourseWork anteriores:

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    rubric = create_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
    print(json.dumps(rubric, indent=4))

Observação :observe que a rubrica retornada contém o previewVersion usado na chamada CREATE. Os recursos associados a uma chamada de método de visualização também contêm o previewVersion usado na chamada como um campo somente leitura, para ajudar a entender qual versão você está usando.

Alguns pontos sobre a representação da rubrica:

• O critério e a ordem dos níveis são refletidos na IU do Google Sala de Aula.
• Os níveis pontuados (aqueles com a propriedade points) precisam ser classificados por pontos em ordem crescente ou decrescente. Eles não podem ser ordenados aleatoriamente.
• Os professores podem reordenar os critérios e os níveis com pontuação (mas não os níveis sem pontuação) na IU, e isso muda a ordem nos dados.

Consulte as limitações para ver mais ressalvas sobre a estrutura das rubricas.

De volta à IU, você verá a rubrica na atividade.

Figura 3. Visualização de um exemplo de rubrica em uma atividade do Google Sala de Aula.

Ler uma rubrica

As rubricas podem ser lidas com os métodos padrão List e Get.

Pode haver no máximo uma rubrica em uma atividade, então List pode parecer não intuitivo, mas é útil se você ainda não tem o ID da rubrica. Se não houver rubrica associada a um CourseWork, a resposta List estará vazia.

Adicione a seguinte função a main.py:

def get_rubric(service, course_id, coursework_id):
    """
    Get the rubric on a coursework. There can only be at most one.
    Returns null if there is no rubric.
    """
    try:
        response = service.courses().courseWork().rubrics().list(
            courseId=course_id, courseWorkId=coursework_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
            ).execute()

        rubrics = response.get("rubrics", [])
        if not rubrics:
            print("No rubric found for this assignment.")
            return
        rubric = rubrics[0]
        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Atualize e execute main.py para buscar a rubrica adicionada:

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    rubric = get_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
    print(json.dumps(rubric, indent=4))

    #TODO(developer): Save the printed rubric ID.

Anote a propriedade id na rubrica para as etapas posteriores.

Get funciona bem quando você tem o ID da rubrica. O uso de Get na função pode ficar assim:

def get_rubric(service, course_id, coursework_id, rubric_id):
    """
    Get the rubric on a coursework. There can only be at most one.
    Returns a 404 if there is no rubric.
    """
    try:
        rubric = service.courses().courseWork().rubrics().get(
            courseId=course_id,
            courseWorkId=coursework_id,
            id=rubric_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
        ).execute()

        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Essa implementação retorna um erro 404 se não houver rubrica.

Atualizar uma rubrica

As atualizações de uma rubrica são feitas com chamadas Patch. Devido à estrutura complexa de uma rubrica, as atualizações precisam ser feitas com um padrão de leitura-modificação-gravação, em que toda a propriedade criteria é substituída.

As regras de atualização são as seguintes:

1. Os critérios ou níveis adicionados sem um ID são considerados adições.
2. Os critérios ou níveis ausentes são considerados exclusões.
3. Os critérios ou níveis com um ID atual, mas com dados modificados são considerados edições. As propriedades não modificadas são mantidas como estão.
4. Os critérios ou níveis fornecidos com IDs novos ou desconhecidos são considerados erros.
5. A ordem dos novos critérios e níveis é considerada a nova ordem da IU (com as limitações mencionadas acima).

Adicione uma função para atualizar uma rubrica:

def update_rubric(service, course_id, coursework_id, rubric_id, body):
    """
    Updates the rubric on a coursework.
    """
    try:
        rubric = service.courses().courseWork().rubrics().patch(
            courseId=course_id,
            courseWorkId=coursework_id,
            id=rubric_id,
            body=body,
            updateMask='criteria',
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
        ).execute()

        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Neste exemplo, o campo criteria é especificado para modificação com um updateMask.

Em seguida, modifique main.py para fazer uma mudança em cada uma das regras de atualização mencionadas:

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    # Get the latest rubric.
    rubric = get_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
    criteria = rubric.get("criteria")
    """
    The "criteria" property should look like this:
    [
        {
            "id": "NkEyMdMyMzM2Nxkw",
            "title": "Argument",
            "description": "How well structured your argument is.",
            "levels": [
                {
                    "id": "NkEyMdMyMzM2Nxkx",
                    "title": "Convincing",
                    "description": "A compelling case is made.",
                    "points": 30
                },
                {
                    "id": "NkEyMdMyMzM2Nxky",
                    "title": "Passable",
                    "description": "Missing some evidence.",
                    "points": 20
                },
                {
                    "id": "NkEyMdMyMzM2Nxkz",
                    "title": "Needs Work",
                    "description": "Not enough strong evidence..",
                    "points": 0
                }
            ]
        },
        {
            "id": "NkEyMdMyMzM2Nxk0",
            "title": "Spelling",
            "description": "How well you spelled all the words.",
            "levels": [...]
        },
        {
            "id": "NkEyMdMyMzM2Nxk4",
            "title": "Grammar",
            "description": "How grammatically correct your sentences are.",
            "levels": [...]
        }
    ]
    """

    # Make edits. This example will make one of each type of change.

    # Add a new level to the first criteria. Levels must remain sorted by
    # points.
    new_level = {
        "title": "Profound",
        "description": "Truly unique insight.",
        "points": 50
    }
    criteria[0]["levels"].insert(0, new_level)

    # Remove the last criteria.
    del criteria[-1]

    # Update the criteria titles with numeric prefixes.
    for index, criterion in enumerate(criteria):
        criterion["title"] = f"{index}: {criterion['title']}"

    # Resort the levels from descending to ascending points.
    for criterion in criteria:
        criterion["levels"].sort(key=lambda level: level["points"])

    # Update the rubric with a patch call.
    new_rubric = update_rubric(
        service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID, YOUR_RUBRIC_ID, rubric)

    print(json.dumps(new_rubric, indent=4))

Agora as mudanças serão aplicadas aos professores no Google Sala de Aula.

Figura 4. Visualização da rubrica atualizada.

Observação: essas regras de edição ficam mais limitadas após o início da avaliação.

Ver envios com nota por rubrica

Por enquanto, os envios dos alunos não podem ser avaliados com uma rubrica pela API, mas você pode ler as notas dos envios que foram avaliados com uma rubrica na IU do Google Sala de Aula.

Como estudante na IU do Google Sala de Aula, conclua e entregue o exemplo de atividade. Depois, como professor, avalie a atividade manualmente usando a rubrica.

Figura 5. Visualização da rubrica para o professor durante a avaliação.

Dica :este é um bom momento para se familiarizar com a flexibilidade do professor ao usar uma rubrica. Por exemplo, observe que o professor pode substituir os pontos do critério dos níveis escolhidos, a pontuação total da atribuição calculada com base nos critérios e pular completamente a escolha dos níveis. Consulte as limitações para mais informações.

Os envios dos estudantes que foram avaliados com uma rubrica têm duas novas propriedades: draftRubricGrades e assignedRubricGrades, representando os pontos e níveis escolhidos pelo professor durante o rascunho e os estados de avaliação atribuídos, respectivamente.

Além disso, os envios dos alunos com uma rubrica associada contêm um campo rubricId, mesmo antes da avaliação. Isso representa a rubrica mais recente associada ao CourseWork e esse valor pode mudar se os professores excluirem e recriarem uma rubrica.

Você pode usar os métodos studentSubmissions.Get e studentSubmissions.List para ver os envios com nota.

Aviso: os campos rubricId, draftRubricGrades e assignedRubricGrades não são expostos por padrão na API Classroom e só podem ser acessados na prévia para desenvolvedores. Isso significa que você precisa definir um previewVersion adequado para recuperá-los. Ao contrário do serviço de rubricas, as chamadas para o serviço de envio não retornam erros quando a versão é omitida. Esses campos são anotados como tal na documentação de referência.

Adicione a seguinte função a main.py para listar os envios dos estudantes:

def get_latest_submission(service, course_id, coursework_id):
    """Retrieves the last submission for an assignment."""
    try:
        response = service.courses().courseWork().studentSubmissions().list(
            courseId = course_id,
            courseWorkId = coursework_id,
            pageSize=1,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
        ).execute()
        submissions = response.get("studentSubmissions", [])
        if not submissions:
            print(
                """No submissions found. Did you remember to turn in and grade
                   the assignment in the UI?""")
            return
        submission = submissions[0]
        return submission

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Em seguida, atualize e execute main.py para conferir as notas do envio.

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    submission = get_latest_submission(
        service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
    print(json.dumps(submission, indent=4))

draftRubricGrades e assignedRubricGrades contêm:

• O criterionId dos critérios de rubrica correspondentes.
• O points atribuído pelo professor para cada critério. Pode ser do nível selecionado, mas o professor também pode ter substituído.
• O levelId do nível escolhido para cada critério. Se o professor não escolher um nível, mas ainda tiver atribuído pontos ao critério, esse campo não estará presente.

Essas listas contêm apenas entradas para os critérios em que o professor selecionou um nível ou definiu pontos. Por exemplo, se um professor quiser interagir apenas com um critério durante a avaliação, draftRubricGrades e assignedRubricGrades vão ter apenas um item, mesmo que a rubrica tenha muitos critérios.

Dica :esse é um bom momento para testar essas propriedades. Para corrigir a atividade na IU do Google Sala de Aula, reenvie a atividade como estudante, mude para a conta de professor e escolha Limpar, faça novas seleções e devolva a atividade novamente. Depois de fazer isso, execute novamente o script Python para ver as alterações no objeto de envio do estudante.

Excluir uma rubrica

Uma rubrica pode ser excluída com uma solicitação Delete padrão. O código a seguir mostra uma função de exemplo para integridade, mas, como a avaliação já foi iniciada, não é possível excluir a rubrica atual:

def delete_rubric(service, course_id, coursework_id, rubric_id):
    """Deletes the rubric on a coursework."""
    try:
        service.courses().courseWork().rubrics().delete(
            courseId=course_id,
            courseWorkId=coursework_id,
            id=rubric_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
        ).execute()

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Exportar e importar rubricas

As rubricas podem ser exportadas manualmente para o app Planilhas Google e serem reutilizadas pelos professores.

Além de especificar os critérios de rubrica no código, é possível criar e atualizar rubricas dessas planilhas exportadas especificando o sourceSpreadsheetId no corpo da rubrica em vez de criteria:

Observação: para criar (ou atualizar) uma rubrica na planilha de um usuário, seu aplicativo precisa solicitar o escopo https://www.googleapis.com/auth/spreadsheets.readonly ou https://www.googleapis.com/auth/spreadsheets. Para isso, adicione um dos escopos ao projeto, conforme descrito na seção sobre como configurar o OAuth e atualize a variável SCOPES em main.py para incluir o escopo. Exclua token.json para que seja possível reautorizar com os novos escopos na próxima vez que executar main.py. Saiba que os escopos spreadsheets são considerados confidenciais e podem exigir que seu aplicativo seja verificado.

def create_rubric_from_sheet(service, course_id, coursework_id, sheet_id):
    """Creates an example rubric on a coursework."""
    try:
        body = {
            "sourceSpreadsheetId": sheet_id
        }

        rubric = service.courses().courseWork().rubrics().create(
            courseId=course_id, courseWorkId=coursework_id, body=body,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
            ).execute()

        print(f"Rubric created with ID {rubric.get('id')}")
        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Feedback

Se você encontrar algum problema ou quiser dar sugestões, compartilhe seu feedback.