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

Nesta página, descrevemos como acessar os recursos em prévia da API Classroom e especificar versões de prévia.

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

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

Ativar recursos de visualização nas bibliotecas de cliente

Uma opção comum para consumir a API Classroom é com 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

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

Bibliotecas dinâmicas

Bibliotecas em linguagens como Python geram a biblioteca de cliente no ambiente de 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 prévia é especificar o label adequado. Para os pré-lançamentos públicos do Google Sala de Aula, o rótulo é DEVELOPER_PREVIEW.

Para gerar a biblioteca Python e instanciar o serviço do Google Sala de Aula com métodos de prévia, especifique o URL do Discovery com o serviço, as credenciais e o rótulo adequados:

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 de cada API do Google para mais detalhes sobre cada linguagem.

Bibliotecas estáticas

As bibliotecas de cliente em linguagens como Java, Node.js, PHP, C# e Go precisam ser criadas da origem. Essas bibliotecas são fornecidas para você e já incorporam os recursos de prévia.

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 pré-lançamentos privados, entre em contato com seu contato do Google se precisar gerar bibliotecas estáticas.

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

Por exemplo, para usar a biblioteca de cliente Go, é necessário usar a diretiva replace no arquivo go.mod para exigir 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 Node.js e 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 regulares e crie uma instância do 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évia da API

Independente de você usar uma biblioteca estática ou dinâmica, especifique a versão de prévia ao fazer chamadas de API para métodos com recursos de prévia.

As diferentes versões disponíveis e os recursos incluídos 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 Rubrics CRUD Preview, 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 prévia também contêm o previewVersion usado na chamada como um campo somente leitura, para ajudar você a entender qual versão está usando. 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 recursos de prévia e especificar uma versão de prévia. Isso é feito definindo um label com um cabeçalho X-Goog-Visibilities e a versão de prévia mencionada como um parâmetro de consulta ou um campo do corpo POST. Consulte a documentação de referência da API individual apropriada. 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 Rubricas com o rótulo de visibilidade e a versão de prévia 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 prévia 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 para cada solicitação HTTP é descrita na documentação REST.

Google Apps Script

É possível chamar APIs de prévia do Google Apps Script. No entanto, há algumas diferenças em relação ao uso típico do Apps Script.

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

Consulte o 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 prévia:

Mudar o projeto do Cloud usado pelo script

Em Configurações do projeto, clique em Mudar projeto e insira o ID do projeto do Cloud em que você se inscreveu no Programa de prévia para desenvolvedores. Por padrão, os scripts do Apps Script usam um projeto genérico. Somente projetos registrados podem chamar métodos de visualização.

Configurar solicitações HTTP

Em seguida, configure a solicitação HTTP de qualquer método que você queira chamar de volta no Editor. Por exemplo, no guia de início rápido, a listagem de cursos com o serviço do Google Sala de Aula é assim:

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 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 Configurações do projeto, ative Mostrar arquivo de manifesto "appsscript.json" no editor. De volta ao Editor, adicione oauthScopes ao arquivo appscript.json para todos os escopos necessários. Os escopos de um determinado método estão listados na página de referência. Por exemplo, consulte a página do método courses.courseWork.rubrics list.

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 prévia

De volta ao script, verifique se você adicionou o rótulo e a versão de prévia adequados, conforme descrito na seção HTTP anterior. A chamada LIST de exemplo para o serviço Rubrics seria assim:

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);
}