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:

1. 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.
2. Os recursos da API em programas de acesso antecipado ou de pré-lançamento não são expostos nas bibliotecas de cliente padrão e podem não ser acessíveis por padrão pelo HTTP.
3. A qualquer momento, pode haver vários estados ou versões da API em pré-visualização.

Ativar recursos de visualização nas bibliotecas de cliente

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

1. Bibliotecas de cliente geradas dinamicamente
2. Bibliotecas de cliente estáticas fornecidas pelo Google
3. 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 você 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 língua.

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 seu app, exija o módulo classroom-with-preview-features além das dependências normais e instancie o serviço classroom a partir 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 CRUD de rubricas, 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()

Observação: as versões de pré-lançamento são temporárias enquanto os recursos são validados para disponibilidade geral na API v1. O comportamento da versão de visualização está sujeito a mudanças após a janela de descontinuação. Consulte o Roteiro da API Classroom para mais informações.

Os recursos associados a uma chamada de método de pré-lançamento também contêm o previewVersion usado na chamada como um campo somente leitura para ajudar a entender qual versão você 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",
  ...
}

Observação: a versão de visualização associada a um recurso corresponde à versão usada para recuperar o recurso, não necessariamente a chamada para criar o recurso. Se você fizer uma chamada GET, LIST ou PATCH futura com uma nova versão especificada, a nova versão será retornada.

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 visualização para especificar uma versão de visualização. 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 para cada solicitação HTTP é descrita na documentação do 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.

1. É necessário configurar o script para usar o projeto do Google Cloud que você inscreveu no Programa de prévia para desenvolvedores.
2. 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.
3. Você precisa fornecer um rótulo e uma versão de visualização, conforme descrito na seção HTTP anterior.

Consulte 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:

Mudar 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 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 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 do método cursos.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 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);
}