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 os recursos de pré-visualização em comparação com a versão estável A API v1 são:

O projeto do Google Cloud que fez a chamada precisa estar registrado no Google Workspace Programa de prévia para desenvolvedores e listados pelo Google.
Os recursos de API nos programas de acesso antecipado ou de pré-lançamento não são expostos na bibliotecas de cliente padrão e pode não ser acessível por padrão por HTTP.
A qualquer momento pode haver vários estados ou versões de API em prévia.

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

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 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 curso. guia, mas revise a seção bibliotecas dinâmicas para saber mais sobre visualizar os rótulos e o papel 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 que pode ser lida por máquina para descrever e o consumo de 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árias documentos de descoberta.

Documentos de descoberta para o serviço da API Classroom (classroom.googleapis.com) podem ser encontradas 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é-visualização é especificar o label apropriado. Nas visualizações públicas do Google Sala de Aula, o marcador DEVELOPER_PREVIEW:

Para gerar a biblioteca Python e instanciar o serviço Sala de Aula com visualização, é possível especificar o URL de descoberta com o serviço apropriado, credenciais e rótulo:

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 das APIs do Google para detalhes sobre cada idioma de destino.

Bibliotecas estáticas

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

Para visualizações públicas, as bibliotecas de cliente do Google Sala de Aula podem ser encontradas com os outros Bibliotecas de cliente do Programa de prévia para desenvolvedores do Google Workspace. Para visualizações particulares, fale com seu contato do Google se precisar gerar bibliotecas estáticas.

Talvez seja necessário modificar sua configuração de dependências típicas para usá-las bibliotecas locais em vez de importar as bibliotecas-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 classe 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 cliente Node.js download da biblioteca (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 aplicativo, exija o módulo classroom-with-preview-features. além das dependências regulares, e instancie o serviço classroom deste 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 visualização da API

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

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

A especificação de uma versão é feita definindo o campo PreviewVersion nas solicitações. Por exemplo, para criar uma rubrica com a API de visualização de Rubrics CRUD, você deve definir previewVersion para 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()

Recursos associados a uma chamada de método de visualização também contêm a previewVersion usado na chamada como um campo somente leitura para ajudar você a entender qual versão você está usando. Por exemplo, a resposta da instrução CREATE chamada 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 usar a API Classroom diretamente com HTTP.

Se você fizer solicitações HTTP sem uma biblioteca de cliente, ainda será necessário ativar de visualização especificam uma versão de visualização. Isso é feito ao definir um label com um cabeçalho X-Goog-Visibilities e a versão de visualização mencionada, conforme um parâmetro de consulta ou um campo de corpo POST (consulte a API individual apropriada documentação de referência). Para visualizações públicas, o rótulo é DEVELOPER_PREVIEW.

Por exemplo, a seguinte solicitação curl faz uma chamada LIST para o serviço Rubrics com o marcador de visibilidade e a versão de visualização apropriados:

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, quando 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 pelo Google Apps Script. No entanto, existem algumas diferenças em relação ao uso típico do Apps Script.

Configure seu script para usar qualquer projeto do Google Cloud que você inscritos no Programa de prévia para desenvolvedores.
Os Serviços avançados não oferecem suporte a métodos de visualização. solicitações diretamente com HTTP.
Você deve fornecer um rótulo e uma versão de pré-visualização, como descrito no Seção HTTP.

Consulte o guia de início rápido correspondente para se familiarizar com Apps Script e configure 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 Configurações do projeto, clique em Alterar projeto e insira o ID do projeto do Google Cloud de qualquer projeto em que você se inscreveu no programa Desenvolvedor Programa de testes (por padrão, os scripts do Apps Script usam um projeto genérico). Apenas inscritos projetos podem chamar métodos de visualização.

Configurar solicitações HTTP

Em seguida, configure a solicitação HTTP de qualquer método no qual você gostaria de retornar a chamada Editor. Por exemplo, no guia de início rápido, listar os cursos com o Google Sala de Aula tem esta aparência:

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 e faça chamadas HTTP diretas para APIs do Google no Apps Script, você precisa adicionar manualmente os escopos apropriados.

Em Configurações do projeto, ative a opção Mostrar "appsscript.json". arquivo de manifesto editor. Volte ao Editor, adicione oauthScopes ao arquivo appscript.json todos os escopos necessários. Os escopos de um determinado método estão listados na página de referência. Por exemplo, consulte o método de lista courses.courseWork.rubrics. .

O arquivo appscript.json atualizado vai 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"
  ]
}

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

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

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