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.

Acessar APIs de visualização

Esta página descreve como acessar os recursos de pré-lançamento da API Classroom e especificar versões de pré-lançamento.

As três considerações ao usar recursos de pré-lançamento em comparação com a API v1 estável são:

O projeto do Google Cloud que faz a chamada precisa estar inscrito no Programa de prévia para desenvolvedores do Google Workspace e ser listado pelo Google.
Os recursos de API nos programas de acesso antecipado ou de visualização não estão expostos nas bibliotecas de cliente padrão e podem não ser acessíveis por padrão por HTTP.
A qualquer momento, pode haver vários estados ou versões da API em pré-visualização.

Ativar recursos de visualização em bibliotecas de cliente

Uma opção comum para consumir a API Classroom é uma biblioteca de cliente. Há três tipos de bibliotecas de cliente:

Bibliotecas de cliente geradas dinamicamente
Bibliotecas de cliente estáticas fornecidas pelo Google
Sua própria biblioteca de cliente personalizada

A maneira recomendada de usar a API é com bibliotecas estáticas geradas dinamicamente ou fornecidas pelo Google. Consulte Criar bibliotecas de cliente se precisar criar sua própria biblioteca. A criação da sua própria biblioteca está fora do escopo deste guia, mas você deve consultar a seção bibliotecas dinâmicas para saber mais sobre rótulos de pré-visualização e a função deles no Discovery.

Bibliotecas dinâmicas

Bibliotecas em linguagens como Python geram a biblioteca de cliente no momento da execução usando um documento de descoberta do serviço de descoberta.

Um documento de descoberta é uma especificação legível por máquina para descrever e consumir APIs REST. Ele é usado para criar bibliotecas de cliente, plug-ins de ambiente de desenvolvimento integrado e outras ferramentas que interagem com as APIs do Google. Um serviço pode fornecer vários documentos de descoberta.

Os documentos de descoberta do serviço da API Classroom (classroom.googleapis.com) podem ser encontrados no seguinte endpoint:

https://classroom.googleapis.com/$discovery/rest?labels=PREVIEW_LABEL&version=v1&key=API_KEY

A distinção importante para trabalhar com APIs de visualização é especificar o label apropriado. Para visualizações públicas do Google Sala de Aula, esse rótulo é DEVELOPER_PREVIEW.

Para gerar a biblioteca Python e instanciar o serviço do Google Sala de Aula com métodos de visualização, especifique o URL de descoberta com o serviço, as credenciais e o rótulo apropriados:

classroom_service_with_preview_features = googleapiclient.discovery.build(
  serviceName='classroom',
  version='v1',
  credentials=credentials,
  static_discovery=False,
  discoveryServiceUrl='https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key=API_KEY)'

Consulte a documentação da biblioteca de cliente da API do Google para detalhes sobre cada linguagem.

Bibliotecas estáticas

As bibliotecas de cliente em linguagens como Java, Node.js, PHP, C# e Go precisam ser criadas a partir da origem. Essas bibliotecas são fornecidas para você e já têm os recursos de visualização incorporados.

Para prévias públicas, as bibliotecas de cliente do Google Sala de aula podem ser encontradas com as outras bibliotecas de cliente do Programa de prévia para desenvolvedores do Workspace. Para visualizações particulares, entre em contato com seu contato do Google se precisar gerar bibliotecas estáticas.

Talvez seja necessário modificar a configuração de dependências típicas para usar essas bibliotecas locais em vez de importar as bibliotecas de cliente padrão, que não têm os recursos de visualização.

Por exemplo, para usar a biblioteca de cliente Go, você precisa usar a diretiva replace no arquivo go.mod para requerer um módulo de um diretório local:

module example.com/app

go 1.21.1

require (
    golang.org/x/oauth2 v0.12.0
    google.golang.org/api v0.139.0 // Classroom library is in here.
)

require (
  ...
)

// Use a local copy of the Go client library.
replace google.golang.org/api v0.139.0 => ../google-api-go-client

Como outro exemplo, se você estiver usando o Node.js e o npm, adicione o download da biblioteca de cliente do Node.js (googleapis-classroom-1.0.4.tgz) como uma dependência local em package.json:

{
  "name": "nodejs-classroom-example",
  "version": "1.0.0",
  ...
  "dependencies": {
    "@google-cloud/local-auth": "^2.1.0",
    "googleapis": "^95.0.0",
    "classroom-with-preview-features": "file:./googleapis-classroom-1.0.4.tgz"
  }
}

Em seguida, no aplicativo, exija o módulo classroom-with-preview-features, além das dependências normais, e instancie o serviço classroom desse módulo:

const {authenticate} = require('@google-cloud/local-auth');
const {google} = require('googleapis');
const classroomWithPreviewFeatures = require('classroom-with-preview-features');

...

const classroom = classroomWithPreviewFeatures.classroom({
  version: 'v1',
  auth: auth,
});

...

Especificar uma versão de pré-lançamento da API

Independentemente de usar uma biblioteca estática ou dinâmica, é necessário especificar a versão de visualização ao fazer chamadas de API para métodos com recursos de visualização.

As diferentes versões disponíveis e os recursos que elas incluem estão documentados no Roteiro da API Classroom. A documentação de referência para métodos e campos também descreve em quais versões o método ou campo está disponível.

Para especificar uma versão, defina o campo PreviewVersion nas solicitações. Por exemplo, para criar uma rubrica com a API de visualização Rubrics CRUD, defina previewVersion como V1_20231110_PREVIEW na solicitação CREATE:

rubric = service.courses().courseWork().rubrics().create(
            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",
            body=body
).execute()

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 você a entender qual versão está sendo usada. Por exemplo, a resposta da chamada CREATE anterior contém o valor V1_20231110_PREVIEW:

print(json.dumps(rubric, indent=4))
{
  "courseId": "123",
  "courseWorkId": "456",
  "creationTime": "2023-10-23T18:18:29.932Z",
  "updateTime": "2023-10-23T18:18:29.932Z",
  "id": "789",
  "criteria": [...],
  # The preview version used in the call that returned this resource.
  "previewVersion": "V1_20231110_PREVIEW",
  ...
}

Solicitações HTTP

Também é possível consumir a API Classroom diretamente com HTTP.

Se você fizer solicitações HTTP sem uma biblioteca de cliente, ainda precisará ativar os recursos de pré-lançamento para especificar uma versão de pré-lançamento. Isso é feito definindo um label com um cabeçalho X-Goog-Visibilities e a versão de visualização mencionada anteriormente como um parâmetro de consulta ou um campo de corpo POST (consulte a documentação de referência de API individual adequada). Para pré-lançamentos públicos, o rótulo é DEVELOPER_PREVIEW.

Por exemplo, a solicitação curl a seguir faz uma chamada LIST para o serviço Rubrics com o rótulo de visibilidade e a versão de pré-visualização adequados:

curl \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_WORK_ID/rubrics?key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
  --header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --compressed

Também é possível especificar a versão de visualização no corpo da solicitação, por exemplo, ao fazer uma solicitação POST:

curl --request PATCH \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_WORK_ID/rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
  --header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"criteria":"[...]"}' \
  --compressed

A API de cada solicitação HTTP é descrita na documentação da REST.

Google Apps Script

É possível chamar APIs de visualização do Google Apps Script. No entanto, existem algumas diferenças em relação ao uso típico do Apps Script.

É necessário configurar o script para usar o projeto do Google Cloud que você inscreveu no Programa de prévia para desenvolvedores.
Os Serviços avançados não oferecem suporte a métodos de visualização. Portanto, é necessário fazer solicitações diretamente com o HTTP.
Você precisa fornecer um rótulo e uma versão de visualização, conforme descrito na seção HTTP anterior.

Veja o guia de início rápido correspondente para se familiarizar com o Apps Script e configurar um projeto básico. Em seguida, siga estas instruções para começar a chamar APIs de visualização:

Alterar o projeto do Cloud usado pelo script

Em Project Settings, clique em Change project e insira o ID do projeto do Cloud do projeto em que você se inscreveu no Programa de Pré-visualização para Desenvolvedores. Por padrão, os scripts do Apps Script usam um projeto genérico. Somente projetos inscritos podem chamar métodos de visualização.

Configurar solicitações HTTP

Em seguida, configure a solicitação HTTP do método que você quer chamar novamente no Editor. Por exemplo, no guia de início rápido, a listagem dos cursos com o serviço do Google Sala de Aula é semelhante ao seguinte:

function listCourses() {
  try {
    const response = Classroom.Courses.list();
    const courses = response.courses;
    if (!courses || courses.length === 0) {
      console.log('No courses found.');
      return;
    }
    for (const course of courses) {
      console.log('%s (%s)', course.name, course.id);
    }
  } catch (err) {
    // TODO: Developer to handle.
    console.log(err.message);
  }
}

A operação equivalente usando HTTP diretamente é:

function listCourses() {
  const response = UrlFetchApp.fetch(
        'https://classroom.googleapis.com/v1/courses', {
        method: 'GET',
        headers: {'Authorization': 'Bearer ' + ScriptApp.getOAuthToken()},
        contentType: 'application/json',
      });
  const data = JSON.parse(response.getContentText());
  if (data.error) {
    // TODO: Developer to handle.
    console.log(err.message);
    return;
  }
  if (!data.courses || !data.courses.length) {
    console.log('No courses found.');
    return;
  }
  for (const course of data.courses) {
    console.log('%s (%s)', course.name, course.id);
  }
}

Ao usar os serviços avançados, os escopos do OAuth necessários são inferidos, mas para fazer chamadas HTTP diretas para as APIs do Google no Apps Script, é necessário adicionar manualmente os escopos apropriados.

Em Project Settings, ative a opção Show "appsscript.json" manifest file in editor. No Editor, adicione oauthScopes ao arquivo appscript.json para qualquer escopo necessário. Os escopos de um determinado método estão listados na página de referência. Por exemplo, consulte a página de métodos de lista decourses.courseWork.rubrics.

O arquivo appscript.json atualizado pode ficar assim:

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/classroom.coursework.students",
    "https://www.googleapis.com/auth/classroom.courses",
    "https://www.googleapis.com/auth/spreadsheets.readonly",
    "https://www.googleapis.com/auth/spreadsheets"
  ]
}

Fornecer um rótulo e uma versão de visualização

No script, verifique se você adicionou o rótulo e a versão de visualização adequados, conforme descrito na seção HTTP anterior. O exemplo de chamada LIST para o serviço Rubrics seria:

function listRubrics() {
  const courseId = COURSE_ID;
  const courseWorkId = COURSE_WORK_ID;
  const response = UrlFetchApp.fetch(
         `https://classroom.googleapis.com/v1/courses/${courseId}/courseWork/${courseWorkId}/rubrics?previewVersion=V1_20231110_PREVIEW`, {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer ' + ScriptApp.getOAuthToken(),
          'X-Goog-Visibilities': 'DEVELOPER_PREVIEW'
        },
        contentType: 'application/json',
        muteHttpExceptions: true
      });
  const data = JSON.parse(response.getContentText());
  console.log(data)
  if (data.error) {
    // TODO: Developer to handle.
    console.log(error.message);
    return;
  }
  if (!data.rubrics || !data.rubrics.length) {
    console.log('No rubrics for this coursework!');
    return;
  }
  console.log(data.rubrics);
}